├── docs ├── .nojekyll ├── articles │ ├── 2023-08-20T183400_how-to-buffer-window.org │ └── 2023-08-20T184309_C_how-to-set-icons-to-be-svg-images.md ├── marginalia.org ├── Makefile ├── resources │ ├── manual.css │ ├── reset.css │ └── style.css ├── fdl.texi └── org-remark.org ├── resources └── images │ ├── 2022-01-22-Title.png │ ├── 2022-01-22-code.png │ ├── 2021-08-17T220032.png │ ├── 2020-12-24T101116_Title.png │ ├── 2022-01-22-Context-menu.png │ ├── v1.2.0 │ └── 2023-08-20-SVG-icon.png │ ├── 2023-08-20-epub-prince-icon.png │ ├── 2020-12-22T141331-OM-screen-shot-01.png │ ├── 2020-12-22T141331-OM-screen-shot-02.png │ ├── 2020-12-22T141331-OM-screen-shot-03.png │ └── v1.3.0 │ └── 2023-08-19-line-highlights-with-icons.png ├── .elpaignore ├── .gitignore ├── .dir-locals.el ├── Makefile ├── .github └── workflows │ └── gh-docs.yml ├── CHANGELOG ├── org-remark-eww.el ├── org-remark-convert-legacy.el ├── org-remark-info.el ├── org-remark-global-tracking.el ├── org-remark-nov.el ├── README-elpa ├── README.org ├── org-remark-icon.el ├── NEWS ├── org-remark-line.el └── LICENSE /docs/.nojekyll: -------------------------------------------------------------------------------- 1 | -------------------------------------------------------------------------------- /resources/images/2022-01-22-Title.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/nobiot/org-remark/HEAD/resources/images/2022-01-22-Title.png -------------------------------------------------------------------------------- /resources/images/2022-01-22-code.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/nobiot/org-remark/HEAD/resources/images/2022-01-22-code.png -------------------------------------------------------------------------------- /resources/images/2021-08-17T220032.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/nobiot/org-remark/HEAD/resources/images/2021-08-17T220032.png -------------------------------------------------------------------------------- /.elpaignore: -------------------------------------------------------------------------------- 1 | demo 2 | test 3 | test* 4 | docs 5 | resources 6 | Makefile 7 | .gitignore 8 | .elpaignore 9 | .github 10 | .dir-locals.el -------------------------------------------------------------------------------- /resources/images/2020-12-24T101116_Title.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/nobiot/org-remark/HEAD/resources/images/2020-12-24T101116_Title.png -------------------------------------------------------------------------------- /resources/images/2022-01-22-Context-menu.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/nobiot/org-remark/HEAD/resources/images/2022-01-22-Context-menu.png -------------------------------------------------------------------------------- /docs/articles/2023-08-20T183400_how-to-buffer-window.org: -------------------------------------------------------------------------------- 1 | Buffer window customization #43 2 | https://github.com/nobiot/org-remark/discussions/43 3 | -------------------------------------------------------------------------------- /resources/images/v1.2.0/2023-08-20-SVG-icon.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/nobiot/org-remark/HEAD/resources/images/v1.2.0/2023-08-20-SVG-icon.png -------------------------------------------------------------------------------- /resources/images/2023-08-20-epub-prince-icon.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/nobiot/org-remark/HEAD/resources/images/2023-08-20-epub-prince-icon.png -------------------------------------------------------------------------------- /resources/images/2020-12-22T141331-OM-screen-shot-01.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/nobiot/org-remark/HEAD/resources/images/2020-12-22T141331-OM-screen-shot-01.png -------------------------------------------------------------------------------- /resources/images/2020-12-22T141331-OM-screen-shot-02.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/nobiot/org-remark/HEAD/resources/images/2020-12-22T141331-OM-screen-shot-02.png -------------------------------------------------------------------------------- /resources/images/2020-12-22T141331-OM-screen-shot-03.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/nobiot/org-remark/HEAD/resources/images/2020-12-22T141331-OM-screen-shot-03.png -------------------------------------------------------------------------------- /resources/images/v1.3.0/2023-08-19-line-highlights-with-icons.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/nobiot/org-remark/HEAD/resources/images/v1.3.0/2023-08-19-line-highlights-with-icons.png -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | */#marginalia.org# 2 | *.bak 3 | *.log 4 | 5 | *.elc 6 | 7 | test 8 | test* 9 | 10 | # ELPA-generated files. 11 | /org-remark-autoloads.el 12 | /org-remark-pkg.el 13 | -------------------------------------------------------------------------------- /.dir-locals.el: -------------------------------------------------------------------------------- 1 | ((nil 2 | (time-stamp-format . "%02d %:B %Y") 3 | (time-stamp-start . "modified:[ ]+\\\\?") 4 | (time-stamp-end . "$") 5 | ;; "Last modified in source code files are at line 20" 6 | (time-stamp-line-limit . 20) 7 | ;; Need this locale to be "C" or "en_US.UTF-8" or something to standardize the 8 | ;; time stamp with English 9 | (system-time-locale . "C")) 10 | (fill-column . 80) 11 | (indent-tabs-mode . nil)) 12 | -------------------------------------------------------------------------------- /Makefile: -------------------------------------------------------------------------------- 1 | # For ELPA, below should be added to the spec: 2 | # ("org-remark" :url "https://github.com/nobiot/org-remark" 3 | # :make "README-elpa" 4 | # :doc "docs/org-remark.org" 5 | # :auto-sync t) 6 | 7 | README-elpa: README.org 8 | -emacs --batch $< -f org-ascii-export-to-ascii 9 | -mv README.txt README-elpa 10 | 11 | .PHONY: test-compile 12 | test-compile: 13 | emacs --batch --eval "(add-to-list 'load-path default-directory)" \ 14 | -f batch-byte-compile ./*.el 15 | # Check declare-function 16 | emacs --batch --eval "(check-declare-directory default-directory)" 17 | 18 | .PHONY: clean 19 | clean: 20 | find . -name "*.elc" -delete 21 | 22 | -------------------------------------------------------------------------------- /docs/marginalia.org: -------------------------------------------------------------------------------- 1 | :PROPERTIES: 2 | :ID: 2022-01-15T093859 3 | :END: 4 | 5 | * Org-remark User Manual 6 | :PROPERTIES: 7 | :org-remark-file: ~/src/org-remark/docs/org-remark.org 8 | :END: 9 | 10 | ** TODO vindex 11 | :PROPERTIES: 12 | :CATEGORY: important 13 | :END: 14 | 15 | - (defcustom org-remark-create-default-pen-set t 16 | 17 | 18 | - [ ] #+vindex: org-remark-notes-file-path 19 | 20 | - [ ] #+vindex: org-remark-notes-display-buffer-action 21 | 22 | - (defcustom org-remark-notes-buffer-name "*marginal notes*" - (defcustom org-remark-use-org-id nil 23 | -------------------------------------------------------------------------------- /.github/workflows/gh-docs.yml: -------------------------------------------------------------------------------- 1 | name: GH-Page AutoGen 2 | 3 | on: 4 | push: 5 | branches: [ main ] 6 | pull_request: 7 | branches: [ main ] 8 | 9 | jobs: 10 | build-and-deploy: 11 | runs-on: ubuntu-latest 12 | continue-on-error: false 13 | steps: 14 | - uses: actions/checkout@v2 15 | - uses: purcell/setup-emacs@master 16 | with: 17 | version: '27.2' 18 | - name: Install dependencies 19 | run: sudo apt-get install texinfo 20 | - name: Run docs/make gh-html 21 | run: | 22 | cd docs 23 | make gh-html 24 | - name: Deploy 🚀 25 | uses: JamesIves/github-pages-deploy-action@4.1.7 26 | with: 27 | branch: gh-pages # The branch the action should deploy to. 28 | folder: docs # The folder the action should deploy. 29 | -------------------------------------------------------------------------------- /docs/Makefile: -------------------------------------------------------------------------------- 1 | .POSIX: 2 | EMACS = emacs 3 | MAKEINFO = makeinfo 4 | INSTALLINFO = install-info 5 | MV = mv 6 | RM = rm 7 | MANUAL_HTML_ARGS =--html --no-split --footnote-style=separate --css-ref=resources/manual.css 8 | 9 | ## Build ############################################################# 10 | 11 | .PHONY: gh-html 12 | gh-html: index.html clean 13 | 14 | .PHONY: all 15 | all: index.html org-remark.info clean 16 | 17 | index.html: org-remark.texi 18 | @printf "\n\n### Generating manual .html files \n\n" 19 | $(MAKEINFO) $(MANUAL_HTML_ARGS) $< -o index.html 20 | 21 | org-remark.texi: org-remark.org 22 | @printf "\n\n### Generating manual .texi file \n\n" 23 | $(EMACS) --batch -L --file $< \ 24 | -f org-texinfo-export-to-texinfo 25 | 26 | org-remark.info: org-remark.texi 27 | @printf "\n\n### Generating manual .info file \n\n" 28 | makeinfo org-remark.texi -o org-remark.info 29 | 30 | 31 | .PHONY: clean 32 | clean: 33 | @printf "\n\n### Clear .texi file \n\n" 34 | $(RM) org-remark.texi* 35 | -------------------------------------------------------------------------------- /docs/resources/manual.css: -------------------------------------------------------------------------------- 1 | /* Style-sheet to use for Emacs manuals */ 2 | 3 | /* Copyright (C) 2013-2022 Free Software Foundation, Inc. 4 | 5 | Copying and distribution of this file, with or without modification, 6 | are permitted in any medium without royalty provided the copyright 7 | notice and this notice are preserved. This file is offered as-is, 8 | without any warranty. 9 | */ 10 | 11 | @import url('style.css'); 12 | 13 | /* makeinfo convert @deffn and similar functions to something inside 14 |
. style.css uses italic for blockquote. This looks poor 15 | in the Emacs manuals, which make extensive use of @defun (etc). 16 | In particular, references to function arguments appear as 17 | inside
. Since is also italic, it makes it 18 | impossible to distinguish variables. We could change to 19 | e.g. bold-italic, or normal, or a different color, but that does 20 | not look as good IMO. So we just override blockquote to be non-italic. 21 | */ 22 | blockquote { font-style: normal; } 23 | 24 | var { font-style: italic; } 25 | -------------------------------------------------------------------------------- /docs/articles/2023-08-20T184309_C_how-to-set-icons-to-be-svg-images.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: How to Set Org-remark to Use SVG Icons 3 | created: 2023-08-20 4 | modified: 16 September 2023 5 | category: #creation 6 | id: 2023-08-20T184309 7 | --- 8 | 9 | # How to Set Org-remark to Use SVG Icons 10 | 11 | ![Highlights with an icon indicating annotations exist](../screen-images/v1.2.0/2023-08-20-SVG-icon.png "Highlights with an icon indicating annotations exist") 12 | 13 | I have released version 1.2.0 of Org-remark. In this version, highlights can display an icon to visually indicate that annotations exist for them. This was implemented in response to a feature request I received via YouTube comments and recorded in [issue #64](https://github.com/nobiot/org-remark/issues/64). 14 | 15 | The icon by default is a string of ASCII characters "`(*)`" so that it can be used for terminals. You can easily customize Org-remark to use an SVG image as shown in the image above. 16 | 17 | There are mainly two ways: 18 | 19 | 1. Use the new built-in `icons` library available as of Emacs version 29.1 20 | 21 | 2. Create a custom function and use a third-party library such as [`svg-lib`](https://github.com/rougier/svg-lib) by Nicolas Rougier 22 | 23 | I will quickly show you the first option to use the new built-in library, which I believe is the easier. 24 | 25 | ## Define an icon 26 | 27 | 1. Get or create an SVG icon 28 | 29 | In my example, I downloaded a "pen" icon as an `.svg` file from [Boxicons](https://boxicons.com/?query=pen) ([licensed under The MIT License](https://boxicons.com/usage#license)). 30 | 31 | 2. Put the downloaded SVG file somewhere in your local 32 | 33 | I put it at `~/.config/emacs/.cache/svg/bx-pen.svg`. 34 | 35 | 3. Use `define-icon` macro to create an icon with the SVG file 36 | 37 | For example, I used the code below. Make sure to change my example to your own file name. You can also play with the `:height` property as you see fit. You can refer to the relevant Info nodes for more configuration detail by evaluating `(info "(elisp)icons)` and `(info "(emacs)icons")` in Emacs (version 29.1 onward). 38 | 39 | ``` emacs-lisp 40 | (define-icon annotation nil 41 | '((image "/home/nobiot/.config/emacs/.cache/svg/bx-pen.svg" 42 | :height (0.8 . em))) 43 | "Notes svg icon for Org-remark" 44 | :version 29.1) 45 | ``` 46 | 47 | ## Customize Org-remark to use the icon 48 | 49 | Now the icon has been defined, you can set it to customizing variable `org-remark-icon-notes`, like so: 50 | 51 | ``` emacs-lisp 52 | ;; I use `setopt` that is made available as of 29.1. `setq` works too. 53 | ;; Use whichever you prefer. 54 | (setopt org-remark-icon-notes (icon-string 'annotation)) 55 | ``` 56 | 57 | If you have a buffer with highlights already open, you would need to `revert-buffer` to reload the highlights. You should see the icon you have defined instead of the default "`(*)`" string, like you see in the screen capture at the top of this article. 58 | -------------------------------------------------------------------------------- /docs/resources/reset.css: -------------------------------------------------------------------------------- 1 | /* 2 | Software License Agreement (BSD License) 3 | 4 | Copyright (c) 2006, Yahoo! Inc. 5 | All rights reserved. 6 | 7 | Redistribution and use of this software in source and 8 | binary forms, with or without modification, arepermitted 9 | provided that the following conditions are met: 10 | 11 | * Redistributions of source code must retain the above 12 | copyright notice, this list of conditions and the 13 | following disclaimer. 14 | 15 | * Redistributions in binary form must reproduce the above 16 | copyright notice, this list of conditions and the 17 | following disclaimer in the documentation and/or other 18 | materials provided with the distribution. 19 | 20 | * Neither the name of Yahoo! Inc. nor the names of its 21 | contributors may be used to endorse or promote products 22 | derived from this software without specific prior 23 | written permission of Yahoo! Inc. 24 | 25 | THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND 26 | CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, 27 | INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF 28 | MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE 29 | DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR 30 | CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 31 | SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 32 | NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 33 | LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 34 | HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER 35 | IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING 36 | NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE 37 | OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 38 | SUCH DAMAGE. 39 | */ 40 | 41 | html { 42 | color: #000; 43 | background: #FFF; 44 | } 45 | 46 | body, div, dl, dt, dd, ul, ol, li, h1, h2, h3, h4, 47 | h5, h6, pre, code, form, fieldset, legend, input, 48 | button, textarea, p, blockquote, th, td { 49 | margin: 0; 50 | padding: 0; 51 | } 52 | 53 | table { 54 | border-collapse: collapse; 55 | border-spacing: 0; 56 | } 57 | 58 | fieldset, img { 59 | border: 0; 60 | } 61 | 62 | address, caption, cite, code, dfn, em, strong, 63 | th, var, optgroup { 64 | font-style: inherit; 65 | font-weight: inherit; 66 | } 67 | 68 | del, ins { 69 | text-decoration: none; 70 | } 71 | 72 | li { 73 | list-style:none; 74 | } 75 | 76 | caption, th { 77 | text-align: left; 78 | } 79 | 80 | h1, h2, h3, h4, h5, h6 { 81 | font-size: 100%; 82 | font-weight: normal; 83 | } 84 | 85 | q:before, q:after { 86 | content:''; 87 | } 88 | 89 | abbr, acronym { 90 | border: 0; 91 | font-variant: normal; 92 | } 93 | 94 | sup { 95 | vertical-align: baseline; 96 | } 97 | sub { 98 | vertical-align: baseline; 99 | } 100 | 101 | legend { 102 | color: #000; 103 | } 104 | 105 | input, button, textarea, select, optgroup, option { 106 | font-family: inherit; 107 | font-size: inherit; 108 | font-style: inherit; 109 | font-weight: inherit; 110 | } 111 | 112 | input, button, textarea, select { 113 | *font-size: 100%; 114 | } 115 | -------------------------------------------------------------------------------- /CHANGELOG: -------------------------------------------------------------------------------- 1 | [More recent changes v1.0.0 are in NEWS file] 2 | 3 | Version 0.2.0 4 | - add: org-remark-delete 5 | - rm: Adding Org-ID automatically to file level when file is empty 6 | 7 | Version 0.1.0 8 | * Features & additions 9 | 10 | - docs: comprehensive user manual (online - Info to be added on ELPA release) 11 | 12 | - feat: org-remark-create macro to let users create their own custom pens 13 | 14 | - feat: minor-mode menu for menu-bar-mode 15 | 16 | This works as mouse context-menu for the new context-menu-mode (>= 17 | Emacs 28) 18 | 19 | - add: browse-next/prev: move and display next/prev marginal notes at the same 20 | time 21 | 22 | - add: view/open to display side-window by default (user option) 23 | 24 | - add: org-remark-link property in marginal notes file with ::line-number 25 | search option 26 | 27 | - feat: org-remark-legacy-convert as a separate feature 28 | 29 | This is for automatically converting legacy Org-marginalia file to 30 | Org-remark. 31 | 32 | - feat: Legacy data facility with org-remark-tracking 33 | 34 | * Changes 35 | 36 | - chg: `remove' (and delete) only removes one highlight at a time instead of 37 | remove all at point 38 | 39 | - chg: Save marginal notes on `mark' instead of wainting for `save' 40 | 41 | - chg: define org-remark-mark explicitly for autoload cookie 42 | 43 | - chg: `org-remark-view' and `org-remark-open'. View will stay in the 44 | current main note; open will move the cursor to the marginal notes 45 | buffer for further editing. 46 | 47 | - chg: When updating the existing headline and position properties, don't 48 | update the headline text when it already exists. Let the user decide 49 | how to manage headlines. 50 | 51 | - doc: copyright assignment to FSF; copyright years 52 | 53 | * Alpha 54 | 55 | ** 0.0.6 56 | 57 | Feature: 58 | - feat: Add =org-marginalia-global-tracking-mode= with a separate .el file 59 | - feat: Use Org-ID to create a link from the marginal notes back to the main file 60 | Add Customizable variable =org-marginalia-use-org-id=; default is =t= 61 | 62 | Change: 63 | - chg: Highlights are now overlay; no longer text-properties 64 | 65 | Improvement to existing functions 66 | - add: Deactivate mark after highlighting 67 | - add: org-marginalia-remove can take C-u to delete 68 | 69 | Fix & Internal Refactor 70 | - intrnl: Add housekeeping for =org-marginalia-highlights= variable 71 | - fix: org-id-uuid is not found 72 | - fix: Add highlighter face def for terminal 73 | 74 | ** 0.0.5 75 | - break: Replace the prefix "om/" in the source code with "org-marginalia" 76 | - break: Remove default keybindings; add examples in readme instead. Addresses [#3](https://github.com/nobiot/org-marginalia/issues/3) 77 | 78 | ** 0.0.4 79 | - feat: Add transient navigation to next/prev 80 | See [[*Credits][§ Credits]] for the piece of code to achieve the transient map I used. 81 | 82 | ** 0.0.3 83 | - feat: Add om/toggle for show/hide highlighters 84 | 85 | ** 0.0.2 86 | - feat: Add om/next and /prev 87 | - break: Change om/open-at-point to org-marginalia-open 88 | - break: Change om/save-all to org-marginalia-save 89 | 90 | ** 0.0.1 91 | Initial alpha release. I consider it to be the minimal viable scope. 92 | -------------------------------------------------------------------------------- /org-remark-eww.el: -------------------------------------------------------------------------------- 1 | ;;; org-remark-eww.el --- Enable Org-remark for EWW -*- lexical-binding: t; -*- 2 | 3 | ;; Copyright (C) 2021-2025 Free Software Foundation, Inc. 4 | 5 | ;; Authors: Vedang Manerikar 6 | ;; Noboru Ota 7 | ;; URL: https://github.com/nobiot/org-remark 8 | ;; Created: 23 December 2022 9 | ;; Last modified: 23 January 2025 10 | ;; Package-Requires: ((emacs "27.1") (org "9.4")) 11 | ;; Keywords: org-mode, annotation, note-taking, marginal-notes, wp 12 | 13 | ;; This file is not part of GNU Emacs. 14 | 15 | ;; This program is free software; you can redistribute it and/or modify 16 | ;; it under the terms of the GNU General Public License as published by 17 | ;; the Free Software Foundation, either version 3 of the License, or 18 | ;; (at your option) any later version. 19 | 20 | ;; This program is distributed in the hope that it will be useful, 21 | ;; but WITHOUT ANY WARRANTY; without even the implied warranty of 22 | ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 23 | ;; GNU General Public License for more details. 24 | 25 | ;; You should have received a copy of the GNU General Public License 26 | ;; along with this program. If not, see . 27 | 28 | ;;; Commentary: 29 | ;; This file is part of org-remark. 30 | 31 | ;; This feature to support for EWW was originally added by Vedang 32 | ;; Manerika with commit 5e4b27ar feat: Support taking annotations in eww 33 | ;; buffers. nobit has refactored it as a separate file. 34 | 35 | ;;; Code: 36 | 37 | (require 'eww) 38 | (require 'org-remark-global-tracking) 39 | 40 | ;;;###autoload 41 | (define-minor-mode org-remark-eww-mode 42 | "Enable Org-remark to work with EWW." 43 | :global t 44 | :group 'org-remark-eww 45 | (if org-remark-eww-mode 46 | ;; Enable 47 | (progn 48 | (add-hook 'eww-after-render-hook #'org-remark-auto-on) 49 | (add-hook 'org-remark-source-find-file-name-functions 50 | #'org-remark-eww-find-file-name) 51 | (add-hook 'org-remark-highlight-link-to-source-functions 52 | #'org-remark-eww-highlight-link-to-source)) 53 | ;; Disable 54 | (remove-hook 'eww-after-render-hook #'org-remark-auto-on) 55 | (remove-hook 'org-remark-source-find-file-name-functions 56 | #'org-remark-eww-find-file-name) 57 | (remove-hook 'org-remark-highlight-link-to-source-functions 58 | #'org-remark-eww-highlight-link-to-source))) 59 | 60 | (defun org-remark-eww-find-file-name () 61 | "Return URL without the protocol as the file name for the website. 62 | It assumes the buffer is the source website to be annotated. 63 | This function is meant to be set to hook 64 | `org-remark-source-find-file-name-functions'." 65 | (when (eq major-mode 'eww-mode) 66 | (let ((url-parsed (url-generic-parse-url (eww-current-url)))) 67 | (concat (url-host url-parsed) (url-filename url-parsed))))) 68 | 69 | (defun org-remark-eww-highlight-link-to-source (filename _point) 70 | "Return URL pointinting to the source website (FILENAME). 71 | It assumes https: 72 | This function is meant to be set to hook 73 | `org-remark-highlight-link-to-source-functions'." 74 | (when (eq major-mode 'eww-mode) 75 | ;;; FIXME we shhould not assume https? 76 | (concat "[[https://" filename "]]"))) 77 | 78 | (provide 'org-remark-eww) 79 | ;;; org-remark-eww.el ends here 80 | -------------------------------------------------------------------------------- /org-remark-convert-legacy.el: -------------------------------------------------------------------------------- 1 | ;;; org-remark-convert-legacy.el --- Convert legacy Org-marginalia files to Org-remark -*- lexical-binding: t; -*- 2 | 3 | ;; Copyright (C) 2022-2025 Free Software Foundation, Inc. 4 | 5 | ;; Author: Noboru Ota 6 | ;; URL: https://github.com/nobiot/org-remark 7 | ;; Last modified: 23 January 2025 8 | ;; Created: 16 January 2022 9 | ;; Package-Requires: ((emacs "27.1") (org "9.4")) 10 | ;; Keywords: org-mode, annotation, writing, note-taking, marginal notes 11 | 12 | ;; This file is not part of GNU Emacs. 13 | 14 | ;; This program is free software; you can redistribute it and/or modify 15 | ;; it under the terms of the GNU General Public License as published by 16 | ;; the Free Software Foundation, either version 3 of the License, or 17 | ;; (at your option) any later version. 18 | 19 | ;; This program is distributed in the hope that it will be useful, 20 | ;; but WITHOUT ANY WARRANTY; without even the implied warranty of 21 | ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 22 | ;; GNU General Public License for more details. 23 | 24 | ;; You should have received a copy of the GNU General Public License 25 | ;; along with this program. If not, see . 26 | 27 | ;;; Commentary: 28 | ;; This file is part of Org-remark and contains a feature that helps users of 29 | ;; Org-marginalia (former name of Org-remark) convert their legacy 30 | ;; marginalia.org files to those compatible with Org-remark. 31 | ;; 32 | ;; (require 'org-remark-convert-legacy-data) for `org-remark' to use 33 | ;; `org-remark-convert-legacy-data' function to automatically convert legacy 34 | ;; data on save and load. Alternatively, use the same function as an 35 | ;; interactive command on a marginalia.org buffer that contains legacy 36 | ;; Org-marginalia data. 37 | 38 | ;;; Code: 39 | 40 | (require 'org) 41 | (require 'org-remark) 42 | 43 | (defun org-remark-convert-legacy-data () 44 | "Convert the legacy Org-marginalia properties to those for Org-remark. 45 | 46 | You can call this function interactively to convert the current 47 | buffer. It also gets automatically triggered when you save or 48 | load Org-remark marginal notes file if 49 | `org-remark-convert-legacy' user option is non-nil. 50 | 51 | This function checks whether or not there is at least one legacy entry with 52 | property \"marginalia-source-file\" in the current buffer. 53 | 54 | If one found, this function will: 55 | 56 | 1. Create a backup copy with the filename \"_archive\" 57 | 2. Convert all \"marginalia-*\" properties to \"org-remark-*\" equivalents 58 | 59 | - marginalia-source-file -> org-remark-file 60 | - marginalia-id -> org-remark-id 61 | - marginalia-source-beg -> org-remark-beg 62 | - marginalia-source-end -> org-remark-end 63 | 64 | This assumes that all the \"marginalia-*\" properties were used 65 | solely by Org-marginalia." 66 | (interactive) 67 | (org-with-wide-buffer 68 | ;; Check that there is at least one legacy entry in the current buffer 69 | (goto-char (point-min)) 70 | (when (save-excursion (org-find-property "marginalia-source-file")) 71 | ;; Do the process only when there is at least one entry 72 | ;; Create a backup copy 73 | (let ((filename (abbreviate-file-name 74 | (concat (buffer-file-name) "_archive")))) 75 | (write-region (point-min) (point-max) filename) 76 | (message (format "org-remark: created backup file %s" filename))) 77 | ;; Scan the whole marginal notes file 78 | (while (not (org-next-visible-heading 1)) 79 | (when-let (source-file (org-entry-get (point) "marginalia-source-file")) 80 | (org-delete-property "marginalia-source-file") 81 | (org-set-property org-remark-prop-source-file source-file)) 82 | (when-let ((id (org-entry-get (point) "marginalia-id")) 83 | (beg (string-to-number 84 | (org-entry-get (point) 85 | "marginalia-source-beg"))) 86 | (end (string-to-number 87 | (org-entry-get (point) 88 | "marginalia-source-end")))) 89 | (org-delete-property "marginalia-id") 90 | (org-delete-property "marginalia-source-beg") 91 | (org-delete-property "marginalia-source-end") 92 | (org-set-property org-remark-prop-id id) 93 | (let ((props '())) 94 | (plist-put props org-remark-prop-source-beg (number-to-string beg)) 95 | (plist-put props org-remark-prop-source-end (number-to-string end)) 96 | (org-remark-notes-set-properties props)))) 97 | (goto-char (point-min)) 98 | (message (format "org-remark: Legacy \"marginalia-*\" properties updated for %s" 99 | (abbreviate-file-name (buffer-file-name)))) 100 | t))) 101 | 102 | (provide 'org-remark-convert-legacy) 103 | 104 | ;;; org-remark-convert-legacy.el ends here 105 | -------------------------------------------------------------------------------- /docs/resources/style.css: -------------------------------------------------------------------------------- 1 | /* This stylesheet is used by manuals and a few older resources. */ 2 | 3 | @import url('reset.css'); 4 | 5 | 6 | /*** PAGE LAYOUT ***/ 7 | 8 | html, body { 9 | font-size: 1em; 10 | text-align: left; 11 | text-decoration: none; 12 | } 13 | html { background-color: #e7e7e7; } 14 | 15 | body { 16 | max-width: 74.92em; 17 | margin: 0 auto; 18 | padding: .5em 1em 1em 1em; 19 | background-color: white; 20 | border: .1em solid #c0c0c0; 21 | } 22 | 23 | /*** BASIC ELEMENTS ***/ 24 | 25 | /* Size and positioning */ 26 | 27 | p, pre, li, dt, dd, table, code, address { line-height: 1.3em; } 28 | 29 | h1 { font-size: 2em; margin: 1em 0 } 30 | h2 { font-size: 1.50em; margin: 1.0em 0 0.87em 0; } 31 | h3 { font-size: 1.30em; margin: 1.0em 0 0.87em 0; } 32 | h4 { font-size: 1.13em; margin: 1.0em 0 0.88em 0; } 33 | h5 { font-size: 1.00em; margin: 1.0em 0 1.00em 0; } 34 | 35 | p, pre { margin: 1em 0; } 36 | pre { overflow: auto; padding-bottom: .3em; } 37 | 38 | ul, ol, blockquote { margin-left: 1.5%; margin-right: 1.5%; } 39 | hr { margin: 1em 0; } 40 | /* Lists of underlined links are difficult to read. The top margin 41 | gives a little more spacing between entries. */ 42 | ul li { margin: .5em 1em; } 43 | ol li { margin: 1em; } 44 | ol ul li { margin: .5em 1em; } 45 | ul li p, ul ul li { margin-top: .3em; margin-bottom: .3em; } 46 | ul ul, ol ul { margin-top: 0; margin-bottom: 0; } 47 | 48 | /* Separate description lists from preceding text */ 49 | dl { margin: 1em 0 0 0; } 50 | /* separate the "term" from subsequent "description" */ 51 | dt { margin: .5em 0; } 52 | /* separate the "description" from subsequent list item 53 | when the final
child is an anonymous box */ 54 | dd { margin: .5em 3% 1em 3%; } 55 | /* separate anonymous box (used to be the first element in
) 56 | from subsequent

*/ 57 | dd p { margin: .5em 0; } 58 | 59 | table { 60 | display: block; overflow: auto; 61 | margin-top: 1.5em; margin-bottom: 1.5em; 62 | } 63 | th { padding: .3em .5em; text-align: center; } 64 | td { padding: .2em .5em; } 65 | 66 | address { margin-bottom: 1em; } 67 | caption { margin-bottom: .5em; text-align: center; } 68 | sup { vertical-align: super; } 69 | sub { vertical-align: sub; } 70 | 71 | /* Style */ 72 | 73 | h1, h2, h3, h4, h5, h6, strong, dt, th { font-weight: bold; } 74 | 75 | /* The default color (black) is too dark for large text in 76 | bold font. */ 77 | h1, h2, h3, h4 { color: #333; } 78 | h5, h6, dt { color: #222; } 79 | 80 | a[href] { color: #005090; } 81 | a[href]:visited { color: #100070; } 82 | a[href]:active, a[href]:hover { 83 | color: #100070; 84 | text-decoration: none; 85 | } 86 | 87 | h1 a[href]:visited, h2 a[href]:visited, h3 a[href]:visited, 88 | h4 a[href]:visited { color: #005090; } 89 | h1 a[href]:hover, h2 a[href]:hover, h3 a[href]:hover, 90 | h4 a[href]:hover { color: #100070; } 91 | 92 | ol { list-style: decimal outside;} 93 | ul { list-style: square outside; } 94 | ul ul, ol ul { list-style: circle; } 95 | li { list-style: inherit; } 96 | 97 | hr { background-color: #ede6d5; } 98 | table { border: 0; } 99 | 100 | abbr,acronym { 101 | border-bottom:1px dotted #000; 102 | text-decoration: none; 103 | cursor:help; 104 | } 105 | del { text-decoration: line-through; } 106 | em { font-style: italic; } 107 | small { font-size: .9em; } 108 | 109 | img { max-width: 100%} 110 | 111 | 112 | /*** SIMPLE CLASSES ***/ 113 | 114 | .center, .c { text-align: center; } 115 | .nocenter{ text-align: left; } 116 | 117 | .underline { text-decoration: underline; } 118 | .nounderline { text-decoration: none; } 119 | 120 | .no-bullet { list-style: none; } 121 | .inline-list li { display: inline } 122 | 123 | .netscape4, .no-display { display: none; } 124 | 125 | 126 | /*** MANUAL PAGES ***/ 127 | 128 | /* This makes the very long tables of contents in Gnulib and other 129 | manuals easier to read. */ 130 | .contents ul, .shortcontents ul { font-weight: bold; } 131 | .contents ul ul, .shortcontents ul ul { font-weight: normal; } 132 | .contents ul { list-style: none; } 133 | 134 | /* For colored navigation bars (Emacs manual): make the bar extend 135 | across the whole width of the page and give it a decent height. */ 136 | .header, .node { margin: 0 -1em; padding: 0 1em; } 137 | .header p, .node p { line-height: 2em; } 138 | 139 | /* For navigation links. We can't use inline-block display to avoid wrapping 140 | because this makes the links appear much smaller than normal text on 141 | phones with Chromium (RT #1872370). */ 142 | .node a, .header a { /*display: inline-block;*/ line-height: 2em; } 143 | .node a:hover, .header a:hover { background: #f2efe4; } 144 | 145 | /* Inserts */ 146 | table.cartouche td { padding: 1.5em; } 147 | 148 | div.display, div.lisp, div.smalldisplay, 149 | div.smallexample, div.smalllisp { margin-left: 3%; } 150 | 151 | div.example { padding: .8em 1.2em .4em; } 152 | pre.example { padding: .8em 1.2em; } 153 | div.example, pre.example { 154 | margin: 1em 0 1em 3% ; 155 | -webkit-border-radius: .3em; 156 | -moz-border-radius: .3em; 157 | border-radius: .3em; 158 | border: 1px solid #d4cbb6; 159 | background-color: #f2efe4; 160 | } 161 | div.example > pre.example { 162 | padding: 0 0 .4em; 163 | margin: 0; 164 | border: none; 165 | } 166 | 167 | pre.menu-comment { padding-top: 1.3em; margin: 0; } 168 | 169 | 170 | /*** FOR WIDE SCREENS ***/ 171 | 172 | @media (min-width: 40em) { 173 | body { padding: .5em 3em 1em 3em; } 174 | div.header, div.node { margin: 0 -3em; padding: 0 3em; } 175 | } 176 | -------------------------------------------------------------------------------- /org-remark-info.el: -------------------------------------------------------------------------------- 1 | ;;; org-remark-info.el --- Support Org-remark with Info-mode -*- lexical-binding: t; -*- 2 | 3 | ;; Copyright (C) 2021-2025 Free Software Foundation, Inc. 4 | 5 | ;; Author: Noboru Ota 6 | ;; URL: https://github.com/nobiot/org-remark 7 | ;; Created: 16 July 2023 8 | ;; Last modified: 23 January 2025 9 | ;; Package-Requires: ((emacs "27.1") (org "9.4")) 10 | ;; Keywords: org-mode, annotation, note-taking, marginal-notes, wp 11 | 12 | ;; This file is not part of GNU Emacs. 13 | 14 | ;; This program is free software; you can redistribute it and/or modify 15 | ;; it under the terms of the GNU General Public License as published by 16 | ;; the Free Software Foundation, either version 3 of the License, or (at 17 | ;; your option) any later version. 18 | 19 | ;; This program is distributed in the hope that it will be useful, but 20 | ;; WITHOUT ANY WARRANTY; without even the implied warranty of 21 | ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 22 | ;; General Public License for more details. 23 | 24 | ;; You should have received a copy of the GNU General Public License 25 | ;; along with this program. If not, see . 26 | 27 | ;;; Commentary: 28 | ;; 29 | ;; This file is an Org-remark extension to add highlights and 30 | ;; annotation support for Info-mode. 31 | ;; 32 | ;; The extension can be enabled globally with `org-remark-info-mode' 33 | ;; 34 | ;; Highlights will include the links to the original with using 35 | ;; `ol-info' (Org mode's info: link type). By default, it opens the 36 | ;; node within the same window as the Org buffer, which is not 37 | ;; convenient for the purpose of Org-remark. You can configure Emacs to 38 | ;; open info: link into another window. See an example of such a 39 | ;; customization below: 40 | ;; 41 | ;; (setopt switch-to-buffer-obey-display-actions t) 42 | ;; (add-to-list 'display-buffer-alist 43 | ;; '("\*info\*.*" 44 | ;; (display-buffer-reuse-mode-window) 45 | ;; (mode . Info-mode))) 46 | ;; 47 | ;; You will need to use `org-remark-info-mode' in conjunction with 48 | ;; `org-remark-global-tracking-mode' and `org-remark-mode'. For more, 49 | ;; refer to the following Info node: 50 | ;; 51 | ;; - Info node `(org-remark) Installation' 52 | ;; - Info node `(org-remark) Getting Started' 53 | 54 | 55 | ;;; Code: 56 | 57 | (require 'ol-info) 58 | (require 'info) 59 | (require 'org-remark-global-tracking) 60 | (defvar org-remark-prop-source-file) 61 | (defvar org-remark-mode) 62 | (declare-function org-remark-highlights-load "org-remark") 63 | (declare-function org-remark-mode "org-remark") 64 | 65 | ;;;###autoload 66 | (define-minor-mode org-remark-info-mode 67 | "Enable Org-remark to work with `Info-mode' for Info documentation reader." 68 | :global t 69 | :group 'org-remark-info 70 | (if org-remark-info-mode 71 | ;; Enable 72 | (progn 73 | (add-hook 'org-remark-source-find-file-name-functions 74 | #'org-remark-info-get-node) 75 | (add-hook 'org-remark-highlight-link-to-source-functions 76 | #'org-remark-info-link) 77 | (add-hook 'Info-selection-hook #'org-remark-info-highlights-load)) 78 | ;; Disable 79 | (remove-hook 'org-remark-source-find-file-name-functions 80 | #'org-remark-info-get-node) 81 | (remove-hook 'org-remark-highlight-link-to-source-functions 82 | #'org-remark-info-link) 83 | (remove-hook 'Info-selection-hook #'org-remark-info-highlights-load))) 84 | 85 | (defun org-remark-info-highlights-load (&rest _args) 86 | "Wrapper for `org-remark-highlights-load'. 87 | It is necessary as this function is intended to be used as part 88 | of advice for `Info-goto-node', which gets arguments passed to 89 | it. `org-remark-highlights-load' should be called with no 90 | arguments for the purpose of `org-remark-info-mode'." 91 | ;; Enabling `org-remark-mode' runs `org-remark-highlights-load', which 92 | ;; would result in duplicating the highlights. As this function should 93 | ;; be run only once for initial load or only once for subsequent 94 | ;; re-load. This `if' statement is to differentiate the initial load 95 | ;; when no Info node has been opened from subsequent reloads when the 96 | ;; user moves to another Info node. In addition, `featurep' is used 97 | ;; because variable `org-remark-mode' may not have been loaded yet to 98 | ;; avoid symbol void. 99 | (if (or (not (featurep 'org-remark)) 100 | (not org-remark-mode)) 101 | (org-remark-mode +1) 102 | (org-remark-highlights-load))) 103 | 104 | (defun org-remark-info-get-node () 105 | "Return the current Info file/node." 106 | (when (eq major-mode 'Info-mode) 107 | (concat (file-name-nondirectory Info-current-file) 108 | "/" 109 | Info-current-node))) 110 | 111 | (defun org-remark-info-link (_filname _point) 112 | "Return \"info:\" link with current point in `Info-mode' buffer. 113 | This function only works when the mode is `Info-mode'. 114 | Assume the point is on the highlight in source Info document 115 | buffer and `ol-info' is loaded. The latter is necessary for 116 | `org-store-link' to work wiht Info buffer." 117 | (when (eq major-mode 'Info-mode) 118 | (org-store-link nil nil))) 119 | 120 | (cl-defmethod org-remark-highlight-get-constructors (&context (major-mode Info-mode)) 121 | "Construct lists for creating MAJOR-MODE specific hierarchy. 122 | This method is for `Info-mode'. Return the value in a alist like 123 | this: 124 | (SOURCE-FILENAME-FN TITLE-FN PROP-TO-FIND)" 125 | (let* ((headline-1 (list 126 | ;; SOURCE-FILENAME-FN 127 | ;; Don't include the full directory path for Info 128 | ;; node. This may change when Emacs version or 129 | ;; package version changes. 130 | (lambda () (file-name-nondirectory Info-current-file)) 131 | ;; TITLE-FN 132 | (lambda () (file-name-nondirectory Info-current-file)) 133 | ;; PROP-TO-FIND 134 | "org-remark-info-file")) 135 | (headline-2 (list 136 | ;; SOURCE-FILENAME-FN 137 | #'org-remark-info-get-node 138 | ;; TITLE-FN 139 | (lambda () Info-current-node) 140 | ;; PROP-TO-FIND 141 | org-remark-prop-source-file)) 142 | (headline-constructors (list headline-1 headline-2))) 143 | headline-constructors)) 144 | 145 | (provide 'org-remark-info) 146 | ;;; org-remark-info.el ends here 147 | -------------------------------------------------------------------------------- /org-remark-global-tracking.el: -------------------------------------------------------------------------------- 1 | ;;; org-remark-global-tracking.el --- Track files and auto-activate Org-remark -*- lexical-binding: t; -*- 2 | 3 | ;; Copyright (C) 2021-2025 Free Software Foundation, Inc. 4 | 5 | ;; Author: Noboru Ota 6 | ;; URL: https://github.com/nobiot/org-remark 7 | ;; Created: 15 August 2021 8 | ;; Last modified: 23 January 2025 9 | ;; Package-Requires: ((emacs "27.1") (org "9.4")) 10 | ;; Keywords: org-mode, annotation, note-taking, marginal-notes, wp 11 | 12 | ;; This file is not part of GNU Emacs. 13 | 14 | ;; This program is free software; you can redistribute it and/or modify 15 | ;; it under the terms of the GNU General Public License as published by 16 | ;; the Free Software Foundation, either version 3 of the License, or 17 | ;; (at your option) any later version. 18 | 19 | ;; This program is distributed in the hope that it will be useful, 20 | ;; but WITHOUT ANY WARRANTY; without even the implied warranty of 21 | ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 22 | ;; GNU General Public License for more details. 23 | 24 | ;; You should have received a copy of the GNU General Public License 25 | ;; along with this program. If not, see . 26 | 27 | ;;; Commentary: 28 | ;; This file is part of org-remark 29 | 30 | ;;; Code: 31 | 32 | (declare-function org-remark-mode "org-remark") 33 | 34 | (defvaralias 'org-remark-notes-file-path 'org-remark-notes-file-name) 35 | 36 | (make-obsolete-variable 37 | 'org-remark-notes-file-path 'org-remark-notes-file-name "0.2.0") 38 | 39 | (defcustom org-remark-notes-file-name "marginalia.org" 40 | "Name of the file where we store highlights and marginal notes. 41 | It can be either a string or function. 42 | 43 | If it is a string, it should be a file name to the marginal notes 44 | file. The default is \"marginalia.org\". The default will 45 | result in one marginal notes file per directory. Ensure that it 46 | is an Org file. 47 | 48 | If it is a function, the default function is 49 | `org-remark-notes-file-name-function'. It returns a file name 50 | like this: \"FILE-notes.org\" by adding \"-notes.org\" as a 51 | suffix to the file name without the extension. When the buffer is 52 | not visiting a file (e.g. a website via EWW), the file name will 53 | be \"marginalia.org\" in your `user-emacs-directory'." 54 | :group 'org-remark 55 | :safe #'stringp 56 | :type '(choice 57 | (file "marginalia.org") 58 | (function org-remark-notes-file-name-function))) 59 | 60 | (defcustom org-remark-highlight-link-to-source-functions nil 61 | "Abnormal hook called to create a link to source in notes file. 62 | Each one is called with FILENAME as an argument." 63 | :group 'org-remark 64 | :type '(repeat function)) 65 | 66 | (defvar org-remark-source-find-file-name-functions nil 67 | "List of functions to get the source file name. 68 | It is an abnormal hook run with no argument and each function 69 | must return a file-name-equvalent as a string that uniquely 70 | identifies the source. The hook is run when `buffer-file-name` 71 | in source buffer returns nil, meaning the source buffer is not 72 | visiting a file. 73 | 74 | Meant to be set by extensions such as `org-remark-eww'") 75 | 76 | ;;;###autoload 77 | (define-minor-mode org-remark-global-tracking-mode 78 | "Automatically activates local minor mode `org-remark-mode'. 79 | When this global minor mode is active, a function added to 80 | `find-file-hook' will look for a marginal notes file for the file 81 | as defined by `org-remark-notes-file-path'. If it is found and 82 | readable, the function automatically activates `org-remark'." 83 | :init-value nil 84 | :lighter " ormk-auto" 85 | :global t 86 | :group 'org-remark 87 | (if org-remark-global-tracking-mode 88 | ;; Enable 89 | (add-hook 'find-file-hook #'org-remark-auto-on) 90 | ;; Disable 91 | (remove-hook 'find-file-hook #'org-remark-auto-on))) 92 | 93 | ;;; Functions 94 | (defun org-remark-notes-file-name-function () 95 | "Return a marginal notes file name for the current buffer. 96 | 97 | This is the default function for the customizing variable 98 | `org-remark-notes-file-name' for its function option. 99 | 100 | When the current buffer is visiting a file, the name of marginal 101 | notes file will be \"FILE-notes.org\", adding \"-notes.org\" as a 102 | suffix to the file name without the extension. 103 | 104 | If the current buffer is not visiting a file, the file name will 105 | be marginalia.org in your `user-emacs-directory'. If this file 106 | name is not suitable, either override the function or set the 107 | user option to use your own custom function." 108 | (if buffer-file-name 109 | (let ((source-filename (org-remark-source-find-file-name))) 110 | (when (and (stringp source-filename) 111 | (file-exists-p source-filename)) 112 | (concat (file-name-sans-extension 113 | (file-name-nondirectory source-filename)) 114 | "-notes.org"))) 115 | ;; If buffer is not visiting a file, we use the default file name. 116 | ;; If this file name is not suitable, either override the function 117 | ;; or set the user option to a custom function. 118 | (expand-file-name "marginalia.org" user-emacs-directory))) 119 | 120 | (defalias 121 | 'org-remark-notes-file-path-function 122 | 'org-remark-notes-file-name-function) 123 | 124 | (make-obsolete 125 | 'org-remark-notes-file-path-function 126 | 'org-remark-notes-file-name-function "0.2.0" ) 127 | 128 | ;;;; Private Functions 129 | 130 | (defun org-remark-auto-on () 131 | "Automatically activates `org-remark-mode' for current buffer when relevant. 132 | This function is meant to be added to `find-file-hook' by 133 | `org-remark-global-tracking-mode'." 134 | (when-let (notes-file (org-remark-notes-get-file-name)) 135 | (when (file-readable-p notes-file) 136 | (unless (featurep 'org-remark) (require 'org-remark)) 137 | (org-remark-mode +1)))) 138 | 139 | (cl-defgeneric org-remark-notes-get-file-name () 140 | "Return the name of marginal notes file for current buffer.") 141 | 142 | (cl-defmethod org-remark-notes-get-file-name () 143 | "Return the name of marginal notes file for current buffer. 144 | This method is major modes derived from `text-mode'." 145 | (if (functionp org-remark-notes-file-name) 146 | (funcall org-remark-notes-file-name) 147 | (if buffer-file-name org-remark-notes-file-name 148 | (expand-file-name org-remark-notes-file-name user-emacs-directory)))) 149 | 150 | (defun org-remark-source-find-file-name () 151 | "Return the filename for the source buffer. 152 | We use this filename to identify the source buffer in all 153 | operations related to marginal notes. 154 | Assumes that we are currently in the source buffer." 155 | (let ((filename (or (and (not (derived-mode-p 'special-mode)) 156 | buffer-file-name) 157 | (run-hook-with-args-until-success 158 | 'org-remark-source-find-file-name-functions)))) 159 | filename)) 160 | 161 | (provide 'org-remark-global-tracking) 162 | 163 | ;;; org-remark-global-tracking.el ends here 164 | -------------------------------------------------------------------------------- /org-remark-nov.el: -------------------------------------------------------------------------------- 1 | ;;; org-remark-nov.el --- Compatibility with nov-mode -*- lexical-binding: t; -*- 2 | 3 | ;; Copyright (C) 2021-2025 Free Software Foundation, Inc. 4 | 5 | ;; Author: Noboru Ota 6 | ;; URL: https://github.com/nobiot/org-remark 7 | ;; Created: 9 January 2023 8 | ;; Last modified: 23 January 2025 9 | ;; Package-Requires: ((emacs "27.1") (org "9.4")) 10 | ;; Keywords: org-mode, annotation, note-taking, marginal-notes, wp 11 | 12 | ;; This file is not part of GNU Emacs. 13 | 14 | ;; This program is free software; you can redistribute it and/or modify 15 | ;; it under the terms of the GNU General Public License as published by 16 | ;; the Free Software Foundation, either version 3 of the License, or (at 17 | ;; your option) any later version. 18 | 19 | ;; This program is distributed in the hope that it will be useful, but 20 | ;; WITHOUT ANY WARRANTY; without even the implied warranty of 21 | ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 22 | ;; General Public License for more details. 23 | 24 | ;; You should have received a copy of the GNU General Public License 25 | ;; along with this program. If not, see . 26 | 27 | ;;; Commentary: 28 | ;; 29 | ;; This feature would not have been possible without the collaboration 30 | ;; with Tan Yin Hoe (GitHub user sati-bodhi). 31 | ;; 32 | ;; This file is an Org-remark extension to add highlights and 33 | ;; annotation support for EPUB books rendered by nov.el [1]. Org-remark 34 | ;; does not automatically install nov.el. Users are expected to obtain 35 | ;; it separately, for example, via MELPA. 36 | ;; 37 | ;; The extension can be enabled globally with `org-remark-nov-mode'. 38 | ;; You will need to use it in conjunction with 39 | ;; `org-remark-global-tracking-mode' and `org-remark-mode'. For more, 40 | ;; refer to the following Info node: 41 | ;; 42 | ;; - Info node `(org-remark) Installation' 43 | ;; - Info node `(org-remark) Getting Started' 44 | ;; 45 | ;; [1]: 46 | 47 | ;;; Code: 48 | 49 | (if (locate-library "nov") (require 'nov) 50 | (error "Org-remark: package `nov' is missing")) 51 | (require 'org-remark-global-tracking) 52 | (declare-function org-remark-highlights-load "org-remark") 53 | (declare-function org-store-link "ol") 54 | (defvar org-remark-prop-source-file) 55 | ;; To silence flymake 56 | (defvar nov-file-name) 57 | (defvar nov-documents) 58 | (defvar nov-documents-index) 59 | (defvar nov-metadata) 60 | 61 | ;;;###autoload 62 | (define-minor-mode org-remark-nov-mode 63 | "Enable Org-remark to work with `nov-mode' for eub." 64 | :global t 65 | :group 'org-remark-nov 66 | (if org-remark-nov-mode 67 | ;; Enable 68 | (progn 69 | (add-hook 'org-remark-source-find-file-name-functions 70 | #'org-remark-nov-get-epub-source) 71 | (add-hook 'org-remark-highlight-link-to-source-functions 72 | #'org-remark-nov-link) 73 | ;; When users turn the page (document in nov-mode's terminology) 74 | ;; `nov-mode' will erase the current buffer and render the new 75 | ;; document content in the same buffer. This means the 76 | ;; highlights currently displayed get removed; the ones for the 77 | ;; new document need to be loaded document after `nov-mode' 78 | ;; renders the new document. 79 | (add-hook 'nov-post-html-render-hook #'org-remark-highlights-load)) 80 | ;; Disable 81 | (remove-hook 'org-remark-source-find-file-name-functions 82 | #'org-remark-nov-get-epub-source) 83 | (remove-hook 'org-remark-highlight-link-to-source-functions 84 | #'org-remark-nov-link) 85 | (remove-hook 'nov-post-html-render-hook #'org-remark-highlights-load))) 86 | 87 | (cl-defmethod org-remark-notes-get-file-name (&context (major-mode nov-mode)) 88 | "Return the name of marginal notes file for current buffer. 89 | This method is for `nov-mode' MAJOR-MODE." 90 | (let ((filename 91 | (cond (;; if `org-remark-notes-file-name' is a user's custom function, use it as is. 92 | (and (functionp org-remark-notes-file-name) 93 | (not (eq org-remark-notes-file-name #'org-remark-notes-file-name-function))) 94 | (funcall org-remark-notes-file-name)) 95 | ;; if it is a default function, then do something different for nov.el. 96 | ((functionp org-remark-notes-file-name) 97 | (concat (file-name-sans-extension nov-file-name) 98 | "-notes.org")) 99 | ;; the only other case is a string. Assume the default 100 | ;; marginalia.org but it should be the same for custom 101 | ;; string. 102 | (t 103 | org-remark-notes-file-name)))) 104 | ;; Even if `org-remark-notes-file-name' is a user-defined custom 105 | ;; function, check if it is relative. If so, make it absolute by 106 | ;; adding the directory path to the epub file. The purpose is to 107 | ;; avoid the directory to be the temp file that nov.el creates for 108 | ;; the html file to be rendered. 109 | (unless (file-name-absolute-p filename) 110 | ;; major mode is nov and in the document buffer. 111 | (setq filename (expand-file-name filename (file-name-directory nov-file-name)))) 112 | filename)) 113 | 114 | (defun org-remark-nov-get-epub-source () 115 | "Return the path of the epub source from which the present session is initiated." 116 | (when (eq major-mode 'nov-mode) 117 | (concat 118 | (file-name-nondirectory nov-file-name) 119 | "/" 120 | (file-name-base (cdr (aref nov-documents nov-documents-index)))))) 121 | 122 | (defun org-remark-nov-get-epub-document-title () 123 | "Return the path of the epub source from which the present session is initiated." 124 | (when (eq major-mode 'nov-mode) 125 | (let ((temp-filename (cdr (aref nov-documents nov-documents-index)))) 126 | (file-name-base temp-filename)))) 127 | 128 | (defun org-remark-nov-link (_filname _point) 129 | "Return \"nov:\" link with current point in `nov-mode' buffer. 130 | 131 | This function only works when the mode is `nov-mode'. 132 | 133 | Assume the point is on the highlight in source epub document 134 | buffer." 135 | (when (eq major-mode 'nov-mode) 136 | (org-store-link nil))) 137 | 138 | (cl-defmethod org-remark-highlight-get-constructors (&context (major-mode nov-mode)) 139 | "Construct lists for creating MAJOR-MODE specific hierarchy. 140 | Return the value in a alist like this: 141 | 142 | (SOURCE-FILENAME-FN TITLE-FN PROP-TO-FIND)" 143 | (let* ((headline-1 (list 144 | ;; SOURCE-FILENAME-FN 145 | (lambda () nov-file-name) 146 | ;; TITLE-FN 147 | (lambda () (cdr (assoc 'title nov-metadata))) 148 | ;; PROP-TO-FIND 149 | "org-remark-nov-file")) 150 | (headline-2 (list 151 | ;; SOURCE-FILENAME-FN 152 | #'org-remark-nov-get-epub-source 153 | ;; TITLE-FN 154 | #'org-remark-nov-get-epub-document-title 155 | ;; PROP-TO-FIND 156 | org-remark-prop-source-file)) 157 | (headline-constructors (list headline-1 headline-2))) 158 | headline-constructors)) 159 | 160 | (provide 'org-remark-nov) 161 | ;;; org-remark-nov.el ends here 162 | -------------------------------------------------------------------------------- /README-elpa: -------------------------------------------------------------------------------- 1 | _____________________ 2 | 3 | README – ORG-REMARK 4 | _____________________ 5 | 6 | 7 | Table of Contents 8 | _________________ 9 | 10 | 1. Introduction 11 | 2. Features 12 | 3. Installation 13 | 4. Contributing and Feedback 14 | 5. Contributors 15 | 6. License 16 | 17 | 18 | 19 | 20 | 21 | 1 Introduction 22 | ============== 23 | 24 | Org-remark lets you highlight and annotate text files, websites, EPUB 25 | books and Info documentation with using Org mode. 26 | 27 | A user manual is available [online] or Emacs in-system as an Info node 28 | `(org-remark)': (`C-h i' and find the `Org-remark' node) . 29 | 30 | The user manual is also available in Japanese: [マニュアル日本語版] 🇯🇵 31 | (translated by ayatajesi, GitHub user @ayatakesi) together with his 32 | review with EWW, "[org-remarkでウェブページに注釈をつける]". 33 | 34 | For installation and minimum configuration, refer to [Installation] 35 | below or the user manual: [online] or Info node `(org-remark) 36 | Installation'. 37 | 38 | Getting Started in the user manual will get you started in 5 minutes: 39 | [online] or or Info node `(org-remark) Getting Started'. 40 | 41 | For customization, refer to the customization group `org-remark' or 42 | user manual: [online] or Info node `(org-remark) Customizing'. A 43 | [separate online article] has been written to guide you on how to 44 | customize an icon (also part of the user manual. Evaluate (info 45 | "(or-gremark) How to Set Org-remark to Use SVG Icons"). 46 | 47 | An [introductory video] (8 minutes) and [V1.1.0 release introduction] 48 | (12 minutes) are available on YouTube. 49 | 50 | 51 | [online] 52 | 53 | [マニュアル日本語版] 54 | 55 | 56 | [org-remarkでウェブページに注釈をつける] 57 | 58 | 59 | [Installation] See section 3 60 | 61 | [online] 62 | 63 | [online] 64 | 65 | [online] 66 | 67 | [separate online article] 68 | 69 | 70 | [introductory video] 71 | 72 | [V1.1.0 release introduction] 73 | 74 | 75 | 2 Features 76 | ========== 77 | 78 | - Highlight and annotate any text file. The highlights and notes are 79 | kept in an Org file as the plain text database. This lets you easily 80 | manage your marginal notes and use the built-in Org facilities on 81 | them -- e.g. create a sparse tree based on the category of the notes 82 | 83 | - Create your your own highlighter pens with different colors, type 84 | (e.g. underline, squiggle, etc. optionally with Org's category for 85 | search and filter on your highlights and notes) 86 | 87 | - Have the same highlighting and annotating functionality for 88 | 89 | + Websites when you use EWW to browse them 90 | 91 | + EPUB books with [nov.el] 92 | 93 | + Info documentation 94 | 95 | + [wallabag.el] (it has been [reported]) 96 | 97 | Refer to [NEWS] file for a list of new features and fixes. 98 | 99 | 100 | [nov.el] 101 | 102 | [wallabag.el] 103 | 104 | [reported] 105 | 106 | 107 | [NEWS] 108 | 109 | 110 | 3 Installation 111 | ============== 112 | 113 | This package is available on: 114 | 115 | - [GNU-ELPA] (releases only; equivalent to MELPA-Stable) 116 | - [GNU-devel ELPA] (unreleased main branch; equivalent to MELPA) 117 | 118 | GNU ELPA should be already set up in your Emacs by default. If you 119 | wish to add GNU-devel ELPA, simply add its URL to `package-archives' 120 | like this: 121 | 122 | ,---- 123 | | (add-to-list 'package-archives 124 | | '("gnu-devel" . "https://elpa.gnu.org/devel/") :append) 125 | `---- 126 | 127 | After installation, we suggest you put the setup below in your 128 | configuration. 129 | 130 | ,---- 131 | | (org-remark-global-tracking-mode +1) 132 | | 133 | | ;; Optional if you would like to highlight websites via eww-mode 134 | | (with-eval-after-load 'eww 135 | | (org-remark-eww-mode +1)) 136 | | 137 | | ;; Optional if you would like to highlight EPUB books via nov.el 138 | | (with-eval-after-load 'nov 139 | | (org-remark-nov-mode +1)) 140 | | 141 | | ;; Optional if you would like to highlight Info documentation via Info-mode 142 | | (with-eval-after-load 'info 143 | | (org-remark-info-mode +1)) 144 | `---- 145 | 146 | Unless you explicitly load `org' during Emacs initialization, I 147 | suggest to defer loading `org-remark' (thus there is no `(require 148 | 'org-remark)' in the example above). This is because it will also pull 149 | in `org', which can slow down initialization. You can control the 150 | timing of loading `org-remark' by autoloading some commands in a 151 | similar way with the example keybindings below. 152 | 153 | Below are example keybindings you might like to consider: 154 | 155 | ,---- 156 | | ;; Key-bind `org-remark-mark' to global-map so that you can call it 157 | | ;; globally before the library is loaded. 158 | | 159 | | (define-key global-map (kbd "C-c n m") #'org-remark-mark) 160 | | 161 | | ;; The rest of keybidings are done only on loading `org-remark' 162 | | (with-eval-after-load 'org-remark 163 | | (define-key org-remark-mode-map (kbd "C-c n o") #'org-remark-open) 164 | | (define-key org-remark-mode-map (kbd "C-c n ]") #'org-remark-view-next) 165 | | (define-key org-remark-mode-map (kbd "C-c n [") #'org-remark-view-prev) 166 | | (define-key org-remark-mode-map (kbd "C-c n r") #'org-remark-remove) 167 | | (define-key org-remark-mode-map (kbd "C-c n d") #'org-remark-delete)) 168 | `---- 169 | 170 | Alternatively, you can use `use-package' to set up Org-remark. The 171 | example provided below should be equivalent to the setup described 172 | above. 173 | 174 | ,---- 175 | | (use-package org-remark-global-tracking 176 | | ;; It is recommended that `org-remark-global-tracking-mode' be 177 | | ;; enabled when Emacs initializes. You can set it in 178 | | ;; `after-init-hook'. 179 | | :hook after-init 180 | | :config 181 | | ;; Selectively keep or comment out the following if you want to use 182 | | ;; extensions for Info-mode, EWW, and NOV.el (EPUB) respectively. 183 | | (use-package org-remark-info :after info :config (org-remark-info-mode +1)) 184 | | (use-package org-remark-eww :after eww :config (org-remark-eww-mode +1)) 185 | | (use-package org-remark-nov :after nov :config (org-remark-nov-mode +1))) 186 | | 187 | | (use-package org-remark 188 | | :bind (;; :bind keyword also implicitly defers org-remark itself. 189 | | ;; Keybindings before :map is set for global-map. Adjust the keybinds 190 | | ;; as you see fit. 191 | | ("C-c n m" . org-remark-mark) 192 | | ("C-c n l" . org-remark-mark-line) 193 | | :map org-remark-mode-map 194 | | ("C-c n o" . org-remark-open) 195 | | ("C-c n ]" . org-remark-view-next) 196 | | ("C-c n [" . org-remark-view-prev) 197 | | ("C-c n r" . org-remark-remove) 198 | | ("C-c n d" . org-remark-delete))) 199 | `---- 200 | 201 | 202 | [GNU-ELPA] 203 | 204 | [GNU-devel ELPA] 205 | 206 | 207 | 4 Contributing and Feedback 208 | =========================== 209 | 210 | Create issues, discussion, and/or pull requests in the GitHub 211 | repository. All welcome. 212 | 213 | Org-remark is available on GNU ELPA and thus copyrighted by the [Free 214 | Software Foundation] (FSF). This means that anyone who is making a 215 | substantive code contribution will need to "assign the copyright for 216 | your contributions to the FSF so that they can be included in GNU 217 | Emacs" ([Org Mode website]). 218 | 219 | Thank you. 220 | 221 | 222 | [Free Software Foundation] 223 | 224 | [Org Mode website] 225 | 226 | 227 | 5 Contributors 228 | ============== 229 | 230 | *New features* 231 | 232 | - User option `org-remark-report-no-highlights`by Kristoffer Balintona 233 | (@krisbalintona) 234 | - EPUB books (nov.el) support would not have been possible without 235 | collaboration with @sati-bodhi 236 | - `echo-text' update from the marginal notes to the source buffer by 237 | marty hiatt (@mooseyboots) 238 | - Support for websites with `eww-mode' by Vedang Manerikar (@vedang) 239 | 240 | *Bug fixes* 241 | 242 | Joseph Turner (@josephmturner) @alan-w-255, Nan Jun Jie (@nanjj), 243 | @sgati-bodhi 244 | 245 | *Documentation (including README, NEWS, CHANGELOG)* 246 | 247 | @randomwangran, marty hiatt (@mooseyboots), @jsntn 248 | 249 | Thank-you to all the comments, issues, and questions on GitHub! 250 | 251 | 252 | 6 License 253 | ========= 254 | 255 | This work is licensed under a GPLv3 license. For a full copy of the 256 | license, refer to [LICENSE]. 257 | 258 | 259 | [LICENSE] <./LICENSE> 260 | -------------------------------------------------------------------------------- /README.org: -------------------------------------------------------------------------------- 1 | #+title: README – Org-remark 2 | #+options: toc:t creator:nil author:nil broken-links:t 3 | 4 | #+html: GNU Emacs 5 | #+html: GPLv3 6 | #+html: GNU ELPA 7 | #+html: GNU-devel ELPA 8 | 9 | * Introduction 10 | 11 | Org-remark lets you highlight and annotate text files, websites, EPUB books and Info documentation with using Org mode. 12 | 13 | A user manual is available [[https://nobiot.github.io/org-remark/][online]] or Emacs in-system as an Info node `(org-remark)': (~C-h i~ and find the =Org-remark= node) . 14 | 15 | The user manual is also available in Japanese: [[https://qiita.com/ayatakesi/items/69d43671b28bb27a9c52][マニュアル日本語版]] 🇯🇵 16 | (translated by ayatajesi, GitHub user @ayatakesi) together with his review with EWW, "[[https://qiita.com/ayatakesi/items/8986af2bf2ccca170439][org-remarkでウェブページに注釈をつける]]". 17 | 18 | For installation and minimum configuration, refer to [[#installation][Installation]] below or the user manual: [[https://nobiot.github.io/org-remark/#Installation][online]] or Info node `(org-remark) Installation'. 19 | 20 | Getting Started in the user manual will get you started in 5 minutes: [[https://nobiot.github.io/org-remark/#Getting-Started][online]] or or Info node `(org-remark) Getting Started'. 21 | 22 | For customization, refer to the customization group `org-remark' or user manual: [[https://nobiot.github.io/org-remark/#Customizing][online]] or Info node `(org-remark) Customizing'. A [[https://github.com/nobiot/org-remark/tree/main/docs/articles/2023-08-20T184309_C_how-to-set-icons-to-be-svg-images.md][separate online article]] has been written to guide you on how to customize an icon (also part of the user manual. Evaluate (info "(or-gremark) How to Set Org-remark to Use SVG Icons"). 23 | 24 | An [[https://youtu.be/c8DHrAsFiLc][introductory video]] (8 minutes) and [[https://youtu.be/BTFuS21N00k][V1.1.0 release introduction]] (12 minutes) are available on YouTube. 25 | 26 | * Features 27 | 28 | - Highlight and annotate any text file. The highlights and notes are kept in an Org file as the plain text database. This lets you easily manage your marginal notes and use the built-in Org facilities on them -- e.g. create a sparse tree based on the category of the notes 29 | 30 | - Create your your own highlighter pens with different colors, type (e.g. underline, squiggle, etc. optionally with Org's category for search and filter on your highlights and notes) 31 | 32 | - Have the same highlighting and annotating functionality for 33 | 34 | + Websites when you use EWW to browse them 35 | 36 | + EPUB books with [[https://depp.brause.cc/nov.el/][nov.el]] 37 | 38 | + Info documentation 39 | 40 | + [[https://github.com/chenyanming/wallabag.el][wallabag.el]] (it has been [[https://github.com/nobiot/org-remark/issues/92#issuecomment-2601307855][reported]]) 41 | 42 | Refer to [[https://github.com/nobiot/org-remark/blob/main/NEWS][NEWS]] file for a list of new features and fixes. 43 | 44 | * Screenshots and Videos :noexport: 45 | 46 | [[./resources/images/2022-01-22-Title.png]] 47 | *Figure 1*. Left: Org-mode with text enlarged; Right: marginal notes with an inline image. [[https://youtu.be/c8DHrAsFiLc][Introductory video]] (8 minutes) and [[https://youtu.be/BTFuS21N00k][v1.1.0 release introduction]] (12 minutes) are available on YouTube 48 | 49 | [[./resources/images/2022-01-22-Context-menu.png]] 50 | *Figure 2*. Mouse context menu with built-in ~context-menu-mode~ available with Emacs version 28 onward 51 | 52 | [[./resources/images/2023-08-20-epub-prince-icon.png]] 53 | *Figure 3*. EPUB book ("Prince" by Niccolò Machiavelli via https://www.gutenberg.org/) with icon indicating there are annotations to the highlight: new features with v1.2.0 (2023-08-20). Left: marginal notes file with annotations; Right: an EPUB book file with a highlight and simple ASCII icon. 54 | 55 | [[./resources/images/v1.3.0/2023-08-19-line-highlights-with-icons.png]] 56 | *Figure 4*. Line-highlights with using icons (as of v1.3.0). Refer to the user manual or [[https://nobiot.com/blog/2023-09-11_org-remark-v1.3-line-highlight/][this article]] for more detail. 57 | 58 | * Installation 59 | :PROPERTIES: 60 | :CUSTOM_ID: installation 61 | :END: 62 | 63 | This package is available on: 64 | 65 | - [[https://elpa.gnu.org/packages/org-remark.html][GNU-ELPA]] (releases only; equivalent to MELPA-Stable) 66 | - [[https://elpa.gnu.org/devel/org-remark.html][GNU-devel ELPA]] (unreleased main branch; equivalent to MELPA) 67 | 68 | GNU ELPA should be already set up in your Emacs by default. If you wish to add GNU-devel ELPA, simply add its URL to ~package-archives~ like this: 69 | 70 | #+BEGIN_SRC elisp 71 | (add-to-list 'package-archives 72 | '("gnu-devel" . "https://elpa.gnu.org/devel/") :append) 73 | #+END_SRC 74 | 75 | After installation, we suggest you put the setup below in your configuration. 76 | 77 | #+begin_src emacs-lisp 78 | (org-remark-global-tracking-mode +1) 79 | 80 | ;; Optional if you would like to highlight websites via eww-mode 81 | (with-eval-after-load 'eww 82 | (org-remark-eww-mode +1)) 83 | 84 | ;; Optional if you would like to highlight EPUB books via nov.el 85 | (with-eval-after-load 'nov 86 | (org-remark-nov-mode +1)) 87 | 88 | ;; Optional if you would like to highlight Info documentation via Info-mode 89 | (with-eval-after-load 'info 90 | (org-remark-info-mode +1)) 91 | #+end_src 92 | 93 | Unless you explicitly load ~org~ during Emacs initialization, I suggest to defer loading ~org-remark~ (thus there is no ~(require 'org-remark)~ in the example above). This is because it will also pull in ~org~, which can slow down initialization. You can control the timing of loading ~org-remark~ by autoloading some commands in a similar way with the example keybindings below. 94 | 95 | Below are example keybindings you might like to consider: 96 | 97 | #+begin_src emacs-lisp 98 | ;; Key-bind `org-remark-mark' to global-map so that you can call it 99 | ;; globally before the library is loaded. 100 | 101 | (define-key global-map (kbd "C-c n m") #'org-remark-mark) 102 | 103 | ;; The rest of keybidings are done only on loading `org-remark' 104 | (with-eval-after-load 'org-remark 105 | (define-key org-remark-mode-map (kbd "C-c n o") #'org-remark-open) 106 | (define-key org-remark-mode-map (kbd "C-c n ]") #'org-remark-view-next) 107 | (define-key org-remark-mode-map (kbd "C-c n [") #'org-remark-view-prev) 108 | (define-key org-remark-mode-map (kbd "C-c n r") #'org-remark-remove) 109 | (define-key org-remark-mode-map (kbd "C-c n d") #'org-remark-delete)) 110 | #+end_src 111 | 112 | Alternatively, you can use ~use-package~ to set up Org-remark. The example provided below should be equivalent to the setup described above. 113 | 114 | #+begin_src emacs-lisp 115 | (use-package org-remark-global-tracking 116 | ;; It is recommended that `org-remark-global-tracking-mode' be 117 | ;; enabled when Emacs initializes. You can set it in 118 | ;; `after-init-hook'. 119 | :hook after-init 120 | :config 121 | ;; Selectively keep or comment out the following if you want to use 122 | ;; extensions for Info-mode, EWW, and NOV.el (EPUB) respectively. 123 | (use-package org-remark-info :after info :config (org-remark-info-mode +1)) 124 | (use-package org-remark-eww :after eww :config (org-remark-eww-mode +1)) 125 | (use-package org-remark-nov :after nov :config (org-remark-nov-mode +1))) 126 | 127 | (use-package org-remark 128 | :bind (;; :bind keyword also implicitly defers org-remark itself. 129 | ;; Keybindings before :map is set for global-map. Adjust the keybinds 130 | ;; as you see fit. 131 | ("C-c n m" . org-remark-mark) 132 | ("C-c n l" . org-remark-mark-line) 133 | :map org-remark-mode-map 134 | ("C-c n o" . org-remark-open) 135 | ("C-c n ]" . org-remark-view-next) 136 | ("C-c n [" . org-remark-view-prev) 137 | ("C-c n r" . org-remark-remove) 138 | ("C-c n d" . org-remark-delete))) 139 | #+end_src 140 | 141 | * Contributing and Feedback 142 | 143 | Create issues, discussion, and/or pull requests in the GitHub repository. All welcome. 144 | 145 | Org-remark is available on GNU ELPA and thus copyrighted by the [[http://fsf.org][Free Software Foundation]] (FSF). This means that anyone who is making a substantive code contribution will need to "assign the copyright for your contributions to the FSF so that they can be included in GNU Emacs" ([[https://orgmode.org/contribute.html#copyright][Org Mode website]]). 146 | 147 | Thank you. 148 | 149 | * Contributors 150 | 151 | *New features* 152 | 153 | - User option `org-remark-report-no-highlights`by Kristoffer Balintona (@krisbalintona) 154 | - EPUB books (nov.el) support would not have been possible without 155 | collaboration with @sati-bodhi 156 | - ~echo-text~ update from the marginal notes to the source buffer by marty hiatt (@mooseyboots) 157 | - Support for websites with ~eww-mode~ by Vedang Manerikar (@vedang) 158 | 159 | *Bug fixes* 160 | 161 | Joseph Turner (@josephmturner) @alan-w-255, Nan Jun Jie (@nanjj), @sgati-bodhi 162 | 163 | *Documentation (including README, NEWS, CHANGELOG)* 164 | 165 | @randomwangran, marty hiatt (@mooseyboots), @jsntn 166 | 167 | Thank-you to all the comments, issues, and questions on GitHub! 168 | 169 | * License 170 | 171 | This work is licensed under a GPLv3 license. For a full copy of the license, refer to [[./LICENSE][LICENSE]]. 172 | -------------------------------------------------------------------------------- /org-remark-icon.el: -------------------------------------------------------------------------------- 1 | ;;; org-remark-icon.el --- Enable Org-remark to use icons -*- lexical-binding: t; -*- 2 | 3 | ;; Copyright (C) 2021-2025 Free Software Foundation, Inc. 4 | 5 | ;; Author: Noboru Ota 6 | ;; URL: https://github.com/nobiot/org-remark 7 | ;; Created: 29 July 2023 8 | ;; Last modified: 23 January 2025 9 | ;; Package-Requires: ((emacs "27.1") (org "9.4")) 10 | ;; Keywords: org-mode, annotation, note-taking, marginal-notes, wp 11 | 12 | ;; This file is not part of GNU Emacs. 13 | 14 | ;; This program is free software; you can redistribute it and/or modify 15 | ;; it under the terms of the GNU General Public License as published by 16 | ;; the Free Software Foundation, either version 3 of the License, or (at 17 | ;; your option) any later version. 18 | 19 | ;; This program is distributed in the hope that it will be useful, but 20 | ;; WITHOUT ANY WARRANTY; without even the implied warranty of 21 | ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 22 | ;; General Public License for more details. 23 | 24 | ;; You should have received a copy of the GNU General Public License 25 | ;; along with this program. If not, see . 26 | 27 | ;;; Commentary: 28 | 29 | ;;; Code: 30 | (require 'cl-macs) 31 | ;; Silence compiler 32 | (defvar org-remark-default-feature-modes) 33 | 34 | (defgroup org-remark-icon nil 35 | "Enable `org-remark' to display glyph/icon indicators." 36 | :group 'org-remark 37 | :prefix "org-remark-icon" 38 | :link '(url-link :tag "GitHub" "https://github.com/nobiot/org-remark")) 39 | 40 | (defcustom org-remark-icon-notes "(*)" 41 | "String to be displayed when notes exist for a given highlight. 42 | 43 | You can set a function to this user option. In this case, the 44 | function must take one argument, which is FACE. FACE can be a 45 | named face (a symbol), or an anonymous face (plist of face 46 | attributes). The function can ignore them and set its own face 47 | and/or text-property to the string. This means you can return a 48 | string with a display property to show an SVG icon instead of the 49 | underlying string. 50 | 51 | Nil means no icon is to be displayed. 52 | 53 | If you wants to use image icons (e.g. SVG image icon created with 54 | package `icons', available Emacs 29.1 or higher), you're limited 55 | to a single character with no space before and after the 56 | character. This limitation does not apply to string of characters 57 | without images, but it is generally assumed that the the value 58 | set to this customizing variable will be a short string (e.g 3 59 | characters long with a pair of parentheses before and after a 60 | single character, such as the default value.)" 61 | :safe #'stringp 62 | :type '(choice 63 | (string "(*)") 64 | (function))) 65 | 66 | (defcustom org-remark-icon-position-adjusted "(d)" 67 | "String to be displayed when a highlight position adjusted. 68 | 69 | You can set a function to this user option. In this case, the 70 | function must take one argument, which is FACE. FACE can be a 71 | named face (a symbol), or an anonymous face (plist of face 72 | attributes). The function can ignore them and set its own face 73 | and/or text-property to the string. This means you can return a 74 | string with a display property to show an SVG icon instead of the 75 | underlying string. 76 | 77 | Nil means no icon is to be displayed. 78 | 79 | If you wants to use image icons (e.g. SVG image icon created with 80 | package `icons', available Emacs 29.1 or higher), you're limited 81 | to a single character with no space before and after the 82 | character. This limitation does not apply to string of characters 83 | without images, but it is generally assumed that the the value 84 | set to this customizing variable will be a short string (e.g 3 85 | characters long with a pair of parentheses before and after a 86 | single character, such as the default value." 87 | :safe #'stringp 88 | :type '(choice 89 | (string "(d)") 90 | (function))) 91 | 92 | ;; Register a mode for automatic enablement at the same time as 93 | ;; `org-remark-mode'. 94 | (add-to-list 'org-remark-default-feature-modes #'org-remark-icon-mode) 95 | 96 | ;;;###autoload 97 | (define-minor-mode org-remark-icon-mode 98 | "Enable Org-remark to display icons. 99 | The icons currently available are defined in `org-remark-icons'." 100 | :global nil 101 | :group 'org-remark 102 | (if org-remark-icon-mode 103 | ;; Enable 104 | (progn 105 | (add-hook 'org-remark-highlights-toggle-hide-functions 106 | #'org-remark-icon-toggle-hide nil :local) 107 | (add-hook 'org-remark-highlights-toggle-show-functions 108 | #'org-remark-icon-toggle-show :local) 109 | ;; Add-icons should be the last function because other functions may do 110 | ;; something relevant for an icon -- e.g. adjust-positon." 111 | (add-hook 'org-remark-highlights-after-load-functions 112 | #'org-remark-highlights-add-icons-maybe 80 :local)) 113 | ;; Disable 114 | (remove-hook 'org-remark-highlights-toggle-hide-functions 115 | #'org-remark-icon-toggle-hide :local) 116 | (remove-hook 'org-remark-highlights-toggle-show-functions 117 | #'org-remark-icon-toggle-show :local) 118 | (remove-hook 'org-remark-highlights-after-load-functions 119 | #'org-remark-highlights-add-icons-maybe :local))) 120 | 121 | (defvar org-remark-icons 122 | (list 123 | (list 'notes 124 | #'org-remark-icon-notes-p 125 | nil) 126 | (list 'position-adjusted 127 | #'org-remark-icon-position-adjusted-p 128 | 'org-remark-highlighter-warning)) 129 | "List of icons enabled. 130 | It is an alist. Each element is a list of this form: 131 | (ICON-NAME PREDICATE DEFAULT-FACE) 132 | 133 | ICON-NAME must be a symbol such as \\='notes\\=' and 134 | \\='position-adjusted\\='. They are used as a suffix to be added to 135 | \\='org-remark-icon-\\=' to form a customizing variable such as 136 | `org-remark-icon-notes' and `org-remark-icon-position-adjusted'. 137 | 138 | PREDICATE must be a function that accepts one argument OV, which 139 | is the highlight overlay. If PREDICATE returns non-nil, the icon 140 | for ICON-NAME will be added to the highlight. 141 | 142 | DEFAULT FACE must be a named face. It is optinal and can be nil.") 143 | 144 | (defun org-remark-icon-notes-p (ov) 145 | (and org-remark-icon-notes 146 | (overlay-get ov '*org-remark-note-body))) 147 | 148 | (defun org-remark-icon-position-adjusted-p (ov) 149 | (and org-remark-icon-position-adjusted 150 | (overlay-get ov '*org-remark-position-adjusted))) 151 | 152 | (defun org-remark-icon-toggle-hide (highlight) 153 | (overlay-put highlight '*org-remark-icons (overlay-get highlight 'after-string)) 154 | (overlay-put highlight 'after-string nil)) 155 | 156 | (defun org-remark-icon-toggle-show (highlight) 157 | (overlay-put highlight 'after-string (overlay-get highlight '*org-remark-icons)) 158 | (overlay-put highlight '*org-remark-icons nil)) 159 | 160 | (defun org-remark-highlights-add-icons-maybe (overlays _notes-buf) 161 | "Add icons to OVERLAYS. 162 | Each overlay is a highlight." 163 | (dolist (ov overlays) 164 | ;; icons added to line highlighters differently from normal ones. 165 | (cl-flet ((add-icon-maybe (icon) 166 | (cl-destructuring-bind 167 | (icon-name pred default-face) icon 168 | (when (funcall pred ov) 169 | (org-remark-icon-propertize icon-name ov default-face))))) 170 | (let ((icon-string 171 | ;; The third arg of `mapconcat' is not optional in Emacs 28 or lower. 172 | (mapconcat #'add-icon-maybe org-remark-icons nil))) 173 | (when (length> icon-string 0) 174 | (org-remark-icon-overlay-put 175 | ov icon-string 176 | (overlay-get ov 'org-remark-type))))))) 177 | 178 | (cl-defgeneric org-remark-icon-overlay-put (_ov _icon-string _org-remark-type) 179 | "Default method to deal with icon. 180 | This is used when a method specific \\='org-remark-type\\=' not 181 | implemented." 182 | (ignore)) 183 | 184 | (cl-defmethod org-remark-icon-overlay-put (ov icon-string (_org-remark-type (eql nil))) 185 | (overlay-put ov 'after-string icon-string)) 186 | 187 | (defun org-remark-icon-propertize (icon-name highlight default-face) 188 | "Return a propertized string. 189 | 190 | ICON-NAME is a symbol such as \\='notes\\=' and 191 | \\='position-adjusted\\='. They are used as a suffix to be added 192 | to \\='org-remark-icon-\\=' to form an ICON, which is a 193 | customizing variable such as `org-remark-icon-notes' and 194 | `org-remark-icon-position-adjusted'. 195 | 196 | HIGHLIGHT is the current highlight overlay being worked on. It is 197 | useful to obtain its face to add the matching face to the 198 | icon (HIGHLIGHT-FACE). 199 | 200 | DEFAULT-FACE is the default face for the ICON. It can be nil, in 201 | which case the face of the HIGHLIGHT should be used. This 202 | depends on the value of ICON. 203 | 204 | ICON is a customizing variable, it can be set to a string. In 205 | this case, the DEFAULT-FACE is used when available; if not, 206 | HIGHLIGHT-FACE. ICON can also be a function. In this case, three 207 | arguments are pass to it: ICON-NAME, HIGHLIGHT-FACE, and 208 | DEFAULT-FACE. It is up to the function whether or not to use any 209 | of them. All it needs to do is to return a string that represents 210 | an icon, typically propertized with a face." 211 | (let ((icon (symbol-value (intern (concat "org-remark-icon-" 212 | (symbol-name icon-name))))) 213 | (highlight-face (org-remark-icon-highlight-get-face 214 | highlight 215 | (overlay-get highlight 'org-remark-type))) 216 | (default-face default-face)) 217 | (if (functionp icon) 218 | (funcall icon icon-name highlight-face default-face) 219 | (propertize icon 'face (if default-face default-face highlight-face))))) 220 | 221 | (cl-defgeneric org-remark-icon-highlight-get-face (highlight _org-remark-type) 222 | "Return the face of the HIGHLIGHT overlay. 223 | This is default method for range-highlights." 224 | (overlay-get highlight 'face)) 225 | 226 | 227 | (provide 'org-remark-icon) 228 | ;;; org-remark-icon.el ends here 229 | -------------------------------------------------------------------------------- /NEWS: -------------------------------------------------------------------------------- 1 | Current development version 2 | 3 | Fixes: 4 | 5 | - fix: When the notes = source, the title is incorrect #97 6 | 7 | Version 1.3.0 - 2025-01-28 8 | 9 | Features: 10 | 11 | - feat: Define `org-remark-report-no-highlights` 12 | krisbalintona/chatty-no-highlights (#86) by Kristoffer Balintona 13 | 14 | - Ability to highlight a whole line and show a mark on the margin (#71) 15 | 16 | - Option to delete the whole notes entry when highlight is removed if 17 | there is no notes body text (#21) 18 | 19 | - `org-remark-open` to open the associated marginal notes file if 20 | cursor outside a highlight (#72) 21 | 22 | Fixes: 23 | 24 | - fix: crash when highlighting non-org source and org-remark-use-org-id is 25 | true (#95) 26 | 27 | - fix: org-remark-info-mode interfering with isearch-forward (#93) 28 | 29 | - fix: fix: args-out-of-range error during loading highlights (#89) 30 | 31 | - fix: `org-remark-link` gets wrongly referenced (#83) 32 | 33 | - fix: josephmturner/fixes (#87): typo in package description 34 | 35 | - fix: compiler warning ‘org-remark-highlight-save’ is an obsolete... 36 | 37 | - fix: Highlights overlay can get added to unsupported buffer (ef98c27) 38 | 39 | - fix(highlights-delay-load): rm window-state-change-functions (#82) 40 | 41 | Version 1.2.2 - 2024-03-25 42 | 43 | - fix: program error #78 mapconcat's 3rd arg is not optional in Emacs 28 44 | 45 | Version 1.2.1 - 2023-08-20 46 | 47 | - fix: org-remark-icon-mode is a void symbol 48 | 49 | Version 1.2.0 - 2023-08-20 50 | 51 | - feat(info): Org-remark supports Info 52 | 53 | + Advice has been implemented. It is added and removed by 54 | `org-remark-info-mode`. 55 | 56 | + No suitable hook is avaialble to trigger a function after the Info node 57 | is rendered. This is necessary as Info renders a new node in the same 58 | buffer (in the same way as Nov.el does). 59 | 60 | - feat: icons for additional information for highlights 61 | 62 | + Notes exists for the highlight (*) 63 | 64 | + The highlight position auto-adjusted (d) 65 | 66 | + Uses the new `org-remark-highlights-after-load-functions' 67 | 68 | + Icons are customizable. You can also disable icons by setting 69 | the respective customizing variable to nil 70 | 71 | + The default face of auto-adjusted icon is customizable with 72 | face `org-remark-highlighter-warning' 73 | 74 | + `org-remark-toggle' also toggles the icon display 75 | 76 | - feat: nov.el support for epub books 77 | 78 | + The link is added to the notes org file correctly pointing 79 | back to epub's highlight location with using :nov link type 80 | added by nov.el.l 81 | 82 | - feat: Adjust positions after load 83 | 84 | + This is useful especially for epubs via nov.el. Nov.el 85 | renders tables on differently depending on the size of the 86 | window. This causes the positions of subsequent text elements 87 | to move depending on the window size when the page is 88 | rendered, dislocating the positions of highlights. This 89 | feature attemps to auto-correct the location on the fly. The 90 | feature works generically, so Org-remark attemps to correct 91 | minior edits to websites (for EWW). 92 | 93 | + The fact that a given highlight has been automatically moved 94 | is indicated by an icon 95 | 96 | - feat: org-remark-highlights-after-load-functions 97 | Abnormal hook 98 | 99 | Fixes: 100 | 101 | - fix: org 9.6.7 breaks org-remark-highlights-get (#70) 102 | 103 | - fix: Make load process robust 104 | 105 | + When error occurs during the load process, instead of 106 | emitting an error, Org-remark now halts the load process and 107 | returns without an error. This has been proven useful 108 | especially for epub support with nov.el. Nov.el renders by 109 | reusing the same buffer instead of generating a new one. When 110 | error occurs during the load process (e.g. user accidentally 111 | deletes some property data in the notes org buffer), the 112 | error would cause nov.el to not properly render the epub 113 | book. This could override the epub archive file wiht a plain 114 | text file of a single file from the book, errasing the entire 115 | book. With this change, Org-remark does not cause the error 116 | when loading highlights from the notes org file to preven 117 | this distructive process from happening. 118 | 119 | + `org-remark-highlights-get' existence checks beg and end 120 | 121 | beg and end must exist. If either is nil, `number-to-string` 122 | errors and load stops prematurely. This can happen when the 123 | user manually manages the notes file and accidentally deletes 124 | the beg/end props. 125 | 126 | - fix: default highlighter color for dark theme 127 | 128 | No functional change. Changed the default color of the 129 | highlighter to be more visible in the dark theme. 130 | 131 | Version 1.1.0 - 2023-05-20 132 | 133 | Features: 134 | 135 | - feat: notes-and-source sync 136 | Previously, Org-remark was designed to create/update/delete 137 | highlights from the source buffer to its marginal notes 138 | buffer; this was always one-way from the source to the notes. 139 | 140 | Now we have implemented the updating process in the other 141 | direction from the notes to source. 142 | 143 | Functionally, we currently have echo-text/tooltip containing 144 | an excerpt from the body of notes from the notes buffer 145 | (thanks to @mooseyboots). 146 | 147 | Other than this additional feature, there should be no visible 148 | change for end users. The update should all happen 149 | transparently behind the scenes with no to little change for 150 | end users of Org-remark. 151 | 152 | - feat: echo-text update from the marginal notes to the source buffer 153 | This is a code contribution by marty hiatt (@mooseyboots). He 154 | has done FSF copyright assignment in July, 2022. 155 | 156 | Now the source buffer can Display annotation text as help-echo 157 | or tooltip. Thank you, @mooseyboots. 158 | 159 | This has opened up an avenue to implement "notes sync" feature 160 | which updates select elements of marginal notes buffer back 161 | into the source buffer for highlight overlays. 162 | 163 | - feat: Extend support for non-file-visiting buffer 164 | We now have an approach to extend Org-remark to support 165 | non-file-visiting buffers of various modes. Currently it is 166 | assumed that the support is to be implemented per mode 167 | basis. We have support for EWW with 'org-remark-eww-mode' and 168 | its dedicated file and feature 'org-remark-eww'. Refer to its 169 | implementation as a reference as to how this approach is 170 | currently practiced. 171 | 172 | - feat: Global minor mode org-remark-eww-mode 173 | Support taking annotations in eww buffers for websites A new 174 | feature contributed by Vedang Manerikar (@vedang). He has 175 | completed FSF paperwork in May, 2022 and received a PDF 176 | regarding the same from the FSF. 177 | 178 | This has opened up a big new avenue to support highlights in 179 | non-file visiting buffers. Thank you @vedang. 180 | 181 | EWW support is modularized in a separate file 182 | 'org-remark-eww.el'. 183 | 184 | org-remark-link: prop for EWW 185 | Now 'org-remark-link' property in the marginal notes buffer 186 | contains the URL that you can follow for the source website. 187 | 188 | - add: org-remark-open-hook #40 189 | Hook run when a note buffer is opened/visited. The current 190 | buffer is the note buffer. 191 | 192 | Fixes: 193 | 194 | - refactor: change the default colors of yellow pen #52 195 | This is to cater to users who have dark theme that may render 196 | the highlighted text illegible due to the default background 197 | color of yellow. 198 | 199 | - fix: Text cut off in notes if the highlight spans across two lines #56 200 | Thanks to GitHub user @sati-bodhi for reporting and suggesting a fix 201 | (code implemented by nobiot). Thank you @sati-bodhi. 202 | 203 | - fix: issue #44 change CATEGORY 204 | Now CATEGORY property from the highlight can be properly 205 | deleted if a new pen does not have CATEGORY. 206 | 207 | - fix: case for highlight-get-text empty notes at the bottom of buffer 208 | 209 | - fix: text-property org-remark-label to be symbol 210 | Fixes the error when you do 'describe-text-properties' on the 211 | highlight overlay 212 | 213 | - fix: move org-remark-source-find-file-name to tracking 214 | After EWW support, 'org-remark-source-get-file-name' is now 215 | moved to 'org-remark-global-tracking.el' file 216 | 217 | - fix: source-file-name incorrect issue #39 218 | PR #38 by Nan Jun Jie (@nanjj). Thank you @nanjj. 219 | 220 | Version 1.0.5 221 | - fix #28 toggle causes error on saving highlights 222 | - fix #39 source-file-name incorrect issue 223 | 224 | Version 1.0.4 225 | - fix: "Wrong type argument: stringp, nil" on highlightintg in scratch 226 | 227 | Version 1.0.3 228 | - fix #23: "Wrong type argument: stringp, nil" on org export 229 | - fix #22: highlights not found when marginalia does not show all 230 | 231 | Version 1.0.2 232 | - Update README, user manual, and doc strings in source 233 | 234 | Version 1.0.1 235 | - Update user manual 236 | 237 | Version 1.0.0 238 | - chg: align with GNU convention: path -> file name 239 | 240 | Regarding user option `org-remark-notes-file-path`, the GNU convention 241 | is to call this a "file name" rather than a "path"; "path" is only used 242 | for lists of directories as in `load-path` (pointed out by Stefan 243 | Monnier; thank you). 244 | 245 | To align with the GNU convention, the following changes are done. 246 | Users should not have to change their existing customization as the old 247 | names are aliased to the new ones. 248 | 249 | User option: 250 | - org-remark-notes-file-path -> org-remark-notes-file-name 251 | - org-remark-source-path-function -> 'org-remark-source-file-name 252 | 253 | Function: 254 | - org-remark-notes-file-path-function -> org-remark-notes-file-name-function 255 | 256 | Private Function: 257 | - org-remark-notes-get-file-path -> org-remark-notes-get-file-name 258 | 259 | `org-remark-notes-file-path`, `org-remark-source-path-function`, and 260 | `org-remark-notes-file-path-function` are used by existing 261 | customization, thus both explicitly made obsolete and aliased to the 262 | new file-name equivalents. 263 | 264 | - fix: Relative file name of the source file in the notes file 265 | 266 | The relative file name of the source was not relative from the marginal notes 267 | file but from the source file itself -- this should be relative from the 268 | marginal notes. 269 | 270 | - chg: `org-remark-global-tracking-mode' has been simplified. 271 | 272 | This is not expected to break the user's workflow or configuration 273 | -- simply removing a superfluous feature. 274 | 275 | .org-remark-tracking file is no longer necessary and can be safely 276 | deleted from the user's Emacs configuraiton directory if present. 277 | Automatic activation of `org-remark-mode' is done by looking the 278 | presence of a marginal notes file for current buffer open. 279 | 280 | `org-remark-global-tracking-mode' itself is still relevant and 281 | recommended to be setup as was previously in the user manual. 282 | 283 | - add: Option to use relative links from the marginal notes back to the source 284 | 285 | Adding user option org-remark-source-path-function. The default is 286 | file-relative-name. 287 | 288 | - add: Adding a new option to org-remark-notes-file-path to use a function 289 | 290 | Its default function is org-remark-notes-file-path-function. It 291 | returns a file name like this: "FILE-notes.org" by adding 292 | "-notes.org" as a suffix to the file name without the extension. 293 | 294 | [Older changes before v1.0.0 are in CHANGELOG file] 295 | -------------------------------------------------------------------------------- /org-remark-line.el: -------------------------------------------------------------------------------- 1 | ;;; org-remark-line.el --- Enable Org-remark to highlight a line -*- lexical-binding: t; -*- 2 | 3 | ;; Copyright (C) 2021-2025 Free Software Foundation, Inc. 4 | 5 | ;; Author: Noboru Ota 6 | ;; URL: https://github.com/nobiot/org-remark 7 | ;; Created: 01 August 2023 8 | ;; Last modified: 23 January 2025 9 | ;; Package-Requires: ((emacs "27.1") (org "9.4")) 10 | ;; Keywords: org-mode, annotation, note-taking, marginal-notes, wp 11 | 12 | ;; This file is not part of GNU Emacs. 13 | 14 | ;; This program is free software; you can redistribute it and/or modify 15 | ;; it under the terms of the GNU General Public License as published by 16 | ;; the Free Software Foundation, either version 3 of the License, or (at 17 | ;; your option) any later version. 18 | 19 | ;; This program is distributed in the hope that it will be useful, but 20 | ;; WITHOUT ANY WARRANTY; without even the implied warranty of 21 | ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 22 | ;; General Public License for more details. 23 | 24 | ;; You should have received a copy of the GNU General Public License 25 | ;; along with this program. If not, see . 26 | 27 | ;;; Commentary: 28 | 29 | ;;; Code: 30 | 31 | (require 'org-remark) 32 | 33 | (defgroup org-remark-line nil 34 | "Enable`org-remark' to highlight and annotate whole lines." 35 | :group 'org-remark 36 | :prefix "org-remark-line" 37 | :link '(url-link :tag "GitHub" "https://github.com/nobiot/org-remark")) 38 | 39 | (defcustom org-remark-line-icon " * " 40 | "Glyph displayed on the margin to indicate the line-highlight. 41 | If you wants to use image icons (e.g. SVG image icon created with 42 | package `icons', available Emacs 29.1 or higher), you're limited 43 | to a single character with no space before and after the 44 | character. This limitation does not apply to string of characters 45 | without images, but it is generally assumed that the the value 46 | set to this customizing variable will be a short string (e.g 3 47 | characters long with a padding spaces before and after a single 48 | character, such as the default value.)" 49 | :local t 50 | :type 'string 51 | :safe 'stringp) 52 | 53 | (defcustom org-remark-line-minimum-margin-width 3 54 | "Margin width in a natural number. 55 | It can be a single number or a cons cell of two. When it is a 56 | single number, both the left and right margin widths will be the 57 | same. When this customizing variable is a cons cell, the format 58 | is as follows: (LEFT-MARGIN-WIDTH . RIGHT-MARGIN-WIDTH)." 59 | :local t 60 | :type '(choice 61 | (natnum :tag "Minimum margin width for both left and right margins" 3) 62 | (cons :tag "Left and right margin widths" natnum natnum))) 63 | 64 | (defcustom org-remark-line-margin-padding 1 65 | "Padding between the main text area the glyph/icon on the margin." 66 | :local t 67 | :type 'natnum) 68 | 69 | (defcustom org-remark-line-margin-side 'left-margin 70 | "The side of margin to display line highlights. 71 | Left or right can be chosen." 72 | :local t 73 | :type '(radio 74 | (const :tag "Left margin" left-margin) 75 | (const :tag "Right margin" right-margin))) 76 | 77 | (defcustom org-remark-line-heading-title-max-length 40 78 | "Maximum length of string included as the highlight title." 79 | :type 'natnum) 80 | 81 | (defcustom org-remark-line-ellipsis "…" 82 | "Ellipsis used when the highlight title is longer than maximum. 83 | The maximum is set in `org-remark-line-heading-title-max-length'." 84 | :type 'string 85 | :safe 'stringp) 86 | 87 | (defface org-remark-line-highlighter 88 | '((((class color) (min-colors 88) (background light)) 89 | :foreground "#dbba3f" :inherit default) 90 | (((class color) (min-colors 88) (background dark)) 91 | :foreground "#e2d980" :inherit default) 92 | (t 93 | :inherit highlight)) 94 | "Face for the default line highlighter pen.") 95 | 96 | (defvar-local org-remark-line-minimum-left-margin-width nil 97 | "Computed minimum `left-margin' width.") 98 | 99 | (defvar-local org-remark-line-minimum-right-margin-width nil 100 | "Computed minimum `right-margin' width.") 101 | 102 | (defvar-local org-remark-line-margins-original '() 103 | "Original window margin width values. 104 | It is the original margins returned by function `window-margins' 105 | in cons cell (or nil) before function 106 | `org-remark-line-set-window-margins' set margins.") 107 | 108 | (defvar-local org-remark-line-margins-set-p nil 109 | "Status indicating if margins are set by `org-remark-line'.") 110 | 111 | ;;;###autoload 112 | (define-minor-mode org-remark-line-mode 113 | "Enable Org-remark to highlight and annotate the whole line." 114 | :global nil 115 | :group 'org-remark 116 | (if org-remark-line-mode 117 | ;; Enable 118 | (progn 119 | ;; Depth is deeper than the default one for range-highlight. 120 | ;; This is to prioritize it over line-highlight when the fomer 121 | ;; is at point and yet on the same line of another 122 | ;; line-highlight. 123 | (add-hook 'org-remark-find-dwim-functions 124 | #'org-remark-line-find 80 :local) 125 | ;; olivetti sets DEPTH to t (=90). We need go lower priority than it 126 | (add-hook 'window-size-change-functions 127 | #'org-remark-line-set-window-margins 95 :local) 128 | ;; Need to reload to cater to margin changes done by `olivetti'. 129 | (add-hook 'window-size-change-functions 130 | #'org-remark-line-highlights-redraw 96 :local) 131 | (add-hook 'org-remark-highlight-other-props-functions 132 | #'org-remark-line-prop-line-number-get) 133 | (org-remark-line-set-window-margins)) 134 | ;; Disable 135 | (remove-hook 'org-remark-find-dwim-functions #'org-remark-line-find :local) 136 | (remove-hook 'window-size-change-functions 137 | #'org-remark-line-set-window-margins :local) 138 | (remove-hook 'window-size-change-functions 139 | #'org-remark-line-highlights-redraw :local) 140 | (remove-hook 'org-remark-highlight-other-props-functions 141 | #'org-remark-line-prop-line-number-get) 142 | (when org-remark-line-margins-set-p 143 | (setq left-margin-width (car org-remark-line-margins-original)) 144 | (setq right-margin-width (cdr org-remark-line-margins-original)) 145 | (set-window-margins nil left-margin-width right-margin-width) 146 | (set-window-buffer (get-buffer-window) (current-buffer) nil) 147 | (setq org-remark-line-minimum-left-margin-width nil) 148 | (setq org-remark-line-minimum-right-margin-width nil) 149 | (setq org-remark-line-margins-set-p nil)))) 150 | 151 | ;; Default line-highlighter pen 152 | 153 | ;;;###autoload 154 | (defun org-remark-mark-line (_beg _end &optional _id _mode) 155 | "Apply face to the region selected by BEG and END. 156 | Dummy function definition to let autoload work. 157 | The actual implementation is added when this library is loaded 158 | and macro `org-remark-create' creates the actual function.") 159 | 160 | (org-remark-create "line" 161 | `org-remark-line-highlighter 162 | `(org-remark-type line)) 163 | 164 | (defun org-remark-line-set-window-margins (&optional window) 165 | "Set the margins of WINDOW or window that displays current buffer. 166 | Return a cons of the form (LEFT-WIDTH . RIGHT-WIDTH). If a 167 | marginal area does not exist, return nil." 168 | (let ((window (or window (get-buffer-window)))) 169 | (when (and (windowp window) (not (window-minibuffer-p window))) 170 | (cl-destructuring-bind (left-width . right-width) (window-margins) 171 | (unless org-remark-line-margins-set-p 172 | (setq org-remark-line-margins-original (window-margins)) 173 | (setq org-remark-line-margins-set-p t) 174 | (setq org-remark-line-minimum-left-margin-width 175 | (+ (if (numberp org-remark-line-minimum-margin-width) 176 | org-remark-line-minimum-margin-width 177 | (car org-remark-line-minimum-margin-width)) 178 | org-remark-line-margin-padding)) 179 | (setq org-remark-line-minimum-right-margin-width 180 | (+ (if (numberp org-remark-line-minimum-margin-width) 181 | org-remark-line-minimum-margin-width 182 | (cdr org-remark-line-minimum-margin-width)) 183 | org-remark-line-margin-padding))) 184 | (if (or (eq left-width nil) (< left-width 185 | org-remark-line-minimum-left-margin-width)) 186 | (setq left-margin-width org-remark-line-minimum-left-margin-width) 187 | (setq left-margin-width left-width)) 188 | (if (or (eq right-width nil) (< right-width 189 | org-remark-line-minimum-right-margin-width)) 190 | (setq right-margin-width org-remark-line-minimum-right-margin-width) 191 | (setq right-margin-width right-width)) 192 | ;; For `set-window-margins' window should be specified. 193 | ;; Howerver, `set-window-buffer' should get nil for window. 194 | ;; Otherwise, the minibuffer also gets the margins. It's a 195 | ;; little tricky behaviour. Both functions seem to be required. 196 | ;; The former changes the current window's margin display 197 | ;; immediately. The latter makes the margin widths the default 198 | ;; for future, when window gets split, etc. 199 | (set-window-margins window left-margin-width right-margin-width) 200 | (set-window-buffer nil (current-buffer) 'keep-margins) 201 | (window-margins))))) 202 | 203 | (defun org-remark-line-pos-bol (pos) 204 | "Return the beginning of the line position for POS." 205 | (save-excursion 206 | (goto-char pos) 207 | (pos-bol))) 208 | 209 | (defun org-remark-line-highlight-p (highlight) 210 | "Return t if HIGHLIGHT is one for the line. 211 | HIGHLIGHT is an overlay." 212 | (eql 'line (overlay-get highlight 'org-remark-type))) 213 | 214 | (defun org-remark-line-find (&optional point) 215 | "Return the line-highight (overlay) of the current line. 216 | When POINT is passed, one for the line it belongs to. If there 217 | are multiple line-hilights, return the car of the list returned 218 | by `overlays-in'." 219 | (let* ((point (or point (point))) 220 | (bol (org-remark-line-pos-bol point)) 221 | (highlights (overlays-in bol bol))) 222 | (seq-find #'org-remark-line-highlight-p highlights))) 223 | 224 | (defun org-remark-line-prop-line-number-get (highlight) 225 | "Return the line number for HIGHLIGHT overlay. 226 | This happens only when HIGHLIGHT is a line-highlight." 227 | (when (org-remark-line-highlight-p highlight) 228 | (list 'org-remark-line-number 229 | (number-to-string (org-current-line (overlay-start highlight)))))) 230 | 231 | (cl-defmethod org-remark-beg-end ((_org-remark-type (eql 'line))) 232 | "Return beg and end for ORG-REMARK-TYPE line." 233 | (let ((bol (org-remark-line-pos-bol (point)))) 234 | (list bol bol))) 235 | 236 | (defun org-remark-line-make-spacer-overlay (pos) 237 | "Return a spacer overlay at POS." 238 | (let* ((left-margin (or (car (window-margins)) left-margin-width)) 239 | ;;(right-margin (or (cdr (window-margins)) right-margin-width)) 240 | (string-length (length org-remark-line-icon)) 241 | (spaces-base-length (if (eql org-remark-line-margin-side 'right-margin) 242 | org-remark-line-margin-padding 243 | (- left-margin 244 | (+ string-length org-remark-line-margin-padding)))) 245 | (spaces-length (if (> spaces-base-length 0) spaces-base-length 0)) 246 | (spacer-ov (make-overlay pos pos nil :front-advance))) 247 | ;; Add a spacing overlay before the line-highlight overlay but we 248 | ;; only need one of these; remove it if one already exits 249 | (remove-overlays (overlay-start spacer-ov) (overlay-end spacer-ov) 250 | 'category 'org-remark-spacer) 251 | (overlay-put spacer-ov 'before-string 252 | (propertize " " 253 | 'display 254 | `((margin ,org-remark-line-margin-side) 255 | (space . (:width ,spaces-length))))) 256 | (overlay-put spacer-ov 'category 'org-remark-spacer) 257 | spacer-ov)) 258 | 259 | (defun org-remark-line-highlights-redraw (&optional window) 260 | "Redraw line-highlights to adjust the spaces/padding. 261 | When WINDOW is nil, this function gets window that current buffer is displayed." 262 | (let ((window (or window (get-buffer-window)))) 263 | (when (and (windowp window) (not (window-minibuffer-p window))) 264 | (org-with-wide-buffer 265 | (let ((highlights 266 | (seq-filter (lambda (ov) (eql 'line (overlay-get ov 'org-remark-type))) 267 | org-remark-highlights))) 268 | (dolist (ov highlights) 269 | (let* ((beg (overlay-start ov)) 270 | (spacer-ov (org-remark-line-make-spacer-overlay beg)) 271 | (copied-highlight (copy-overlay ov)) 272 | (display-props 273 | (get-text-property 0 'display (overlay-get copied-highlight 'before-string)))) 274 | (setf (car display-props) `(margin ,org-remark-line-margin-side)) 275 | (push copied-highlight org-remark-highlights) 276 | (copy-overlay spacer-ov) 277 | (delete-overlay ov) 278 | (org-remark-highlights-housekeep) 279 | (org-remark-highlights-sort)))))))) 280 | 281 | (defun org-remark-line-highlight-propertize (ov icon-string) 282 | "Propertize ICON-STRING and add it to OV." 283 | ;; If the icon-string has a display properties, assume it is an icon image 284 | (let ((display-prop (get-text-property 0 'display icon-string))) 285 | (cond (display-prop ; svg-based icon 286 | (let* ((display-prop (list `(margin ,org-remark-line-margin-side) display-prop)) 287 | ;; TODO margin needs to be calculated 288 | ;; (list `(margin ,org-remark-line-margin-side) 289 | ;; (append display-prop '(:margin (10 . 0)))))) 290 | (icon-face (get-text-property 0 'face icon-string)) 291 | (icon-string (propertize " " 'display display-prop))) 292 | (when icon-face 293 | (setq icon-string (propertize icon-string 'face icon-face))) 294 | (overlay-put ov 'before-string icon-string))) 295 | (icon-string ; text/string-based icon 296 | (let ((icon-string icon-string)) 297 | (overlay-put 298 | ov 299 | 'before-string 300 | (propertize 301 | " " 'display 302 | (list `(margin ,org-remark-line-margin-side) icon-string))))) 303 | (t (ignore))))) 304 | 305 | (cl-defmethod org-remark-highlight-make-overlay (beg end face (_org-remark-type (eql 'line))) 306 | "Make and return a highlight overlay in BEG END for line-highlight. 307 | This function adds FACE to line icon string. If FACE is nil, this 308 | function uses default `org-remark-line-highlighter'. Return nil 309 | when no window is created for current buffer." 310 | (when (get-buffer-window) 311 | (unless org-remark-line-mode (org-remark-line-mode +1)) 312 | (let* ((face (or face 'org-remark-line-highlighter)) 313 | (string (propertize org-remark-line-icon 'face face)) 314 | (spacer-ov (org-remark-line-make-spacer-overlay beg)) 315 | (ov (make-overlay beg end nil :front-advance))) 316 | ;; line-highlight overlay 317 | (org-remark-line-highlight-propertize ov string) 318 | ;; Let highlight overlay to take care of the spacer movement 319 | (overlay-put ov 'insert-in-front-hooks (list 'org-remark-line-highlight-modified)) 320 | ;; Copy spacer overlay. It is put after the line-highlight to 321 | ;; limit and reset the face added by the line-highlight back to 322 | ;; default. This is especially done for RTL languages and when the 323 | ;; face include a background color different from that of default. 324 | ;; Without it, the background color goes all the way to the end of 325 | ;; the right margin. 326 | (copy-overlay spacer-ov) 327 | ov))) 328 | 329 | (defun org-remark-line-highlight-find-spacers (pos) 330 | "Find the two spacers for POS." 331 | (let ((highlights (overlays-in pos pos))) 332 | (seq-filter (lambda (ov) 333 | (eql 'org-remark-spacer (overlay-get ov 'category))) 334 | highlights))) 335 | 336 | (defun org-remark-line-highlight-modified (ov after-p beg _end &optional _length) 337 | "Move spacers and lighlight OV to follow the point. 338 | Without this function, the line-highlighter mark does not move 339 | when the user press RET to add a newline at the beginning of the 340 | line-highlight. This is unintuitive for the user. 341 | 342 | This function is meant to be added to insert-in-front-hooks of 343 | the overlay that represents line-highlight. It must be called 344 | AFTER-P is non-nil and move BEG to one position forward." 345 | (when after-p 346 | (save-excursion (goto-char beg) 347 | (when (looking-at "\n") 348 | ;; The sequence must be 1. spacer; 2. highlight 3. spacer 349 | (let ((spacers (org-remark-line-highlight-find-spacers beg))) 350 | (when spacers 351 | (move-overlay (pop spacers) (1+ beg) (1+ beg))) 352 | (move-overlay ov (1+ beg) (1+ beg)) 353 | (when spacers 354 | (move-overlay (pop spacers) (1+ beg) (1+ beg)))))))) 355 | 356 | (cl-defmethod org-remark-highlight-headline-text (ov (_org-remark-type (eql 'line))) 357 | "Return the first N characters of the highlighted line OV. 358 | N is customized with `org-remark-line-heading-title-max-length'. 359 | If the line starts with any space or tab, they will be trimmed. 360 | If the line (after trimming) is shorter than N, then this 361 | function will include the charcters up to the newline char. 362 | 363 | In addition, if the text happens to be empty, the function uses 364 | \"Empty line highlight\" as the fallback; headlines with no title 365 | is not considered valid for the purpose of `org-remark' and thus 366 | risks unexpected results (mostly the highlight skipped when 367 | loading highlights)." 368 | (let ((line-text (buffer-substring-no-properties 369 | (overlay-start ov) (pos-eol)))) 370 | (if (or (eq line-text nil) 371 | (string= line-text "")) 372 | "Empty line highlight" 373 | (setq line-text (string-trim-left line-text)) 374 | (if (length< line-text 375 | (1+ org-remark-line-heading-title-max-length)) 376 | line-text 377 | (concat (substring line-text 0 org-remark-line-heading-title-max-length) 378 | org-remark-line-ellipsis))))) 379 | 380 | (cl-defmethod org-remark-highlights-adjust-positions-p ((_org-remark-type (eql 'line))) 381 | "Return t if adjust-positions feature is relevant. 382 | For line-highlights, adjust-positions is not relevant." 383 | nil) 384 | 385 | (cl-defmethod org-remark-highlights-housekeep-delete-p (_ov (_org-remark-type (eql 'line))) 386 | "Always return nil when ORG-REMARK-TYPE is \\='line\\='. 387 | Line-highlights are designed to be zero length with the start and 388 | end of overlay being identical." 389 | nil) 390 | 391 | (cl-defmethod org-remark-highlights-housekeep-per-type (ov (_org-remark-type (eql 'line))) 392 | "Ensure line-highlight OV is always at the beginning of line." 393 | ;; if `pos-bol' is used to move, you can actually get the highlight to 394 | ;; always follow the point, keeping the original place unless you 395 | ;; directly change the notes. That's not really an intutive behaviour, 396 | ;; though in some cases, it imay be useful. 397 | ;; (if (not (overlay-start ov)) (delete-overlay ov) 398 | (when (overlay-buffer ov) 399 | (let* ((ov-start (overlay-start ov)) 400 | (ov-line-bol (org-remark-line-pos-bol ov-start))) 401 | (unless (= ov-start ov-line-bol) 402 | (move-overlay ov ov-line-bol ov-line-bol))))) 403 | 404 | (cl-defmethod org-remark-icon-overlay-put (ov icon-string (_org-remark-type (eql 'line))) 405 | "Add ICON-STRING to OV. 406 | Each overlay is a highlight. Return nil when no window is created 407 | for current buffer." 408 | (when (get-buffer-window) 409 | (org-remark-line-highlight-propertize ov icon-string))) 410 | 411 | (cl-defmethod org-remark-icon-highlight-get-face (highlight (_org-remark-type (eql 'line))) 412 | "Return the face of HIGHLIGHT in margin for line-highlight." 413 | (let* ((before-string (overlay-get highlight 'before-string)) 414 | (face (get-text-property 0 'face before-string))) 415 | ;; When the highlight already is an SVG icon, face is in the display 416 | ;; property of before-string 417 | (unless face 418 | (let ((display-string 419 | (cadr (get-text-property 0 'display before-string)))) 420 | (when (stringp display-string) 421 | (setq face (get-text-property 0 'face display-string))))) 422 | face)) 423 | 424 | (provide 'org-remark-line) 425 | ;;; org-remark-line.el ends here 426 | -------------------------------------------------------------------------------- /docs/fdl.texi: -------------------------------------------------------------------------------- 1 | @c The GNU Free Documentation License. 2 | @center Version 1.3, 3 November 2008 3 | 4 | @c This file is intended to be included within another document, 5 | @c hence no sectioning command or @node. 6 | 7 | @display 8 | Copyright @copyright{} 2000, 2001, 2002, 2007, 2008 Free Software Foundation, Inc. 9 | @uref{https://fsf.org/} 10 | 11 | Everyone is permitted to copy and distribute verbatim copies 12 | of this license document, but changing it is not allowed. 13 | @end display 14 | 15 | @enumerate 0 16 | @item 17 | PREAMBLE 18 | 19 | The purpose of this License is to make a manual, textbook, or other 20 | functional and useful document @dfn{free} in the sense of freedom: to 21 | assure everyone the effective freedom to copy and redistribute it, 22 | with or without modifying it, either commercially or noncommercially. 23 | Secondarily, this License preserves for the author and publisher a way 24 | to get credit for their work, while not being considered responsible 25 | for modifications made by others. 26 | 27 | This License is a kind of ``copyleft'', which means that derivative 28 | works of the document must themselves be free in the same sense. It 29 | complements the GNU General Public License, which is a copyleft 30 | license designed for free software. 31 | 32 | We have designed this License in order to use it for manuals for free 33 | software, because free software needs free documentation: a free 34 | program should come with manuals providing the same freedoms that the 35 | software does. But this License is not limited to software manuals; 36 | it can be used for any textual work, regardless of subject matter or 37 | whether it is published as a printed book. We recommend this License 38 | principally for works whose purpose is instruction or reference. 39 | 40 | @item 41 | APPLICABILITY AND DEFINITIONS 42 | 43 | This License applies to any manual or other work, in any medium, that 44 | contains a notice placed by the copyright holder saying it can be 45 | distributed under the terms of this License. Such a notice grants a 46 | world-wide, royalty-free license, unlimited in duration, to use that 47 | work under the conditions stated herein. The ``Document'', below, 48 | refers to any such manual or work. Any member of the public is a 49 | licensee, and is addressed as ``you''. You accept the license if you 50 | copy, modify or distribute the work in a way requiring permission 51 | under copyright law. 52 | 53 | A ``Modified Version'' of the Document means any work containing the 54 | Document or a portion of it, either copied verbatim, or with 55 | modifications and/or translated into another language. 56 | 57 | A ``Secondary Section'' is a named appendix or a front-matter section 58 | of the Document that deals exclusively with the relationship of the 59 | publishers or authors of the Document to the Document's overall 60 | subject (or to related matters) and contains nothing that could fall 61 | directly within that overall subject. (Thus, if the Document is in 62 | part a textbook of mathematics, a Secondary Section may not explain 63 | any mathematics.) The relationship could be a matter of historical 64 | connection with the subject or with related matters, or of legal, 65 | commercial, philosophical, ethical or political position regarding 66 | them. 67 | 68 | The ``Invariant Sections'' are certain Secondary Sections whose titles 69 | are designated, as being those of Invariant Sections, in the notice 70 | that says that the Document is released under this License. If a 71 | section does not fit the above definition of Secondary then it is not 72 | allowed to be designated as Invariant. The Document may contain zero 73 | Invariant Sections. If the Document does not identify any Invariant 74 | Sections then there are none. 75 | 76 | The ``Cover Texts'' are certain short passages of text that are listed, 77 | as Front-Cover Texts or Back-Cover Texts, in the notice that says that 78 | the Document is released under this License. A Front-Cover Text may 79 | be at most 5 words, and a Back-Cover Text may be at most 25 words. 80 | 81 | A ``Transparent'' copy of the Document means a machine-readable copy, 82 | represented in a format whose specification is available to the 83 | general public, that is suitable for revising the document 84 | straightforwardly with generic text editors or (for images composed of 85 | pixels) generic paint programs or (for drawings) some widely available 86 | drawing editor, and that is suitable for input to text formatters or 87 | for automatic translation to a variety of formats suitable for input 88 | to text formatters. A copy made in an otherwise Transparent file 89 | format whose markup, or absence of markup, has been arranged to thwart 90 | or discourage subsequent modification by readers is not Transparent. 91 | An image format is not Transparent if used for any substantial amount 92 | of text. A copy that is not ``Transparent'' is called ``Opaque''. 93 | 94 | Examples of suitable formats for Transparent copies include plain 95 | ASCII without markup, Texinfo input format, La@TeX{} input 96 | format, SGML or XML using a publicly available 97 | DTD, and standard-conforming simple HTML, 98 | PostScript or PDF designed for human modification. Examples 99 | of transparent image formats include PNG, XCF and 100 | JPG@. Opaque formats include proprietary formats that can be 101 | read and edited only by proprietary word processors, SGML or 102 | XML for which the DTD and/or processing tools are 103 | not generally available, and the machine-generated HTML, 104 | PostScript or PDF produced by some word processors for 105 | output purposes only. 106 | 107 | The ``Title Page'' means, for a printed book, the title page itself, 108 | plus such following pages as are needed to hold, legibly, the material 109 | this License requires to appear in the title page. For works in 110 | formats which do not have any title page as such, ``Title Page'' means 111 | the text near the most prominent appearance of the work's title, 112 | preceding the beginning of the body of the text. 113 | 114 | The ``publisher'' means any person or entity that distributes copies 115 | of the Document to the public. 116 | 117 | A section ``Entitled XYZ'' means a named subunit of the Document whose 118 | title either is precisely XYZ or contains XYZ in parentheses following 119 | text that translates XYZ in another language. (Here XYZ stands for a 120 | specific section name mentioned below, such as ``Acknowledgements'', 121 | ``Dedications'', ``Endorsements'', or ``History''.) To ``Preserve the Title'' 122 | of such a section when you modify the Document means that it remains a 123 | section ``Entitled XYZ'' according to this definition. 124 | 125 | The Document may include Warranty Disclaimers next to the notice which 126 | states that this License applies to the Document. These Warranty 127 | Disclaimers are considered to be included by reference in this 128 | License, but only as regards disclaiming warranties: any other 129 | implication that these Warranty Disclaimers may have is void and has 130 | no effect on the meaning of this License. 131 | 132 | @item 133 | VERBATIM COPYING 134 | 135 | You may copy and distribute the Document in any medium, either 136 | commercially or noncommercially, provided that this License, the 137 | copyright notices, and the license notice saying this License applies 138 | to the Document are reproduced in all copies, and that you add no other 139 | conditions whatsoever to those of this License. You may not use 140 | technical measures to obstruct or control the reading or further 141 | copying of the copies you make or distribute. However, you may accept 142 | compensation in exchange for copies. If you distribute a large enough 143 | number of copies you must also follow the conditions in section 3. 144 | 145 | You may also lend copies, under the same conditions stated above, and 146 | you may publicly display copies. 147 | 148 | @item 149 | COPYING IN QUANTITY 150 | 151 | If you publish printed copies (or copies in media that commonly have 152 | printed covers) of the Document, numbering more than 100, and the 153 | Document's license notice requires Cover Texts, you must enclose the 154 | copies in covers that carry, clearly and legibly, all these Cover 155 | Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on 156 | the back cover. Both covers must also clearly and legibly identify 157 | you as the publisher of these copies. The front cover must present 158 | the full title with all words of the title equally prominent and 159 | visible. You may add other material on the covers in addition. 160 | Copying with changes limited to the covers, as long as they preserve 161 | the title of the Document and satisfy these conditions, can be treated 162 | as verbatim copying in other respects. 163 | 164 | If the required texts for either cover are too voluminous to fit 165 | legibly, you should put the first ones listed (as many as fit 166 | reasonably) on the actual cover, and continue the rest onto adjacent 167 | pages. 168 | 169 | If you publish or distribute Opaque copies of the Document numbering 170 | more than 100, you must either include a machine-readable Transparent 171 | copy along with each Opaque copy, or state in or with each Opaque copy 172 | a computer-network location from which the general network-using 173 | public has access to download using public-standard network protocols 174 | a complete Transparent copy of the Document, free of added material. 175 | If you use the latter option, you must take reasonably prudent steps, 176 | when you begin distribution of Opaque copies in quantity, to ensure 177 | that this Transparent copy will remain thus accessible at the stated 178 | location until at least one year after the last time you distribute an 179 | Opaque copy (directly or through your agents or retailers) of that 180 | edition to the public. 181 | 182 | It is requested, but not required, that you contact the authors of the 183 | Document well before redistributing any large number of copies, to give 184 | them a chance to provide you with an updated version of the Document. 185 | 186 | @item 187 | MODIFICATIONS 188 | 189 | You may copy and distribute a Modified Version of the Document under 190 | the conditions of sections 2 and 3 above, provided that you release 191 | the Modified Version under precisely this License, with the Modified 192 | Version filling the role of the Document, thus licensing distribution 193 | and modification of the Modified Version to whoever possesses a copy 194 | of it. In addition, you must do these things in the Modified Version: 195 | 196 | @enumerate A 197 | @item 198 | Use in the Title Page (and on the covers, if any) a title distinct 199 | from that of the Document, and from those of previous versions 200 | (which should, if there were any, be listed in the History section 201 | of the Document). You may use the same title as a previous version 202 | if the original publisher of that version gives permission. 203 | 204 | @item 205 | List on the Title Page, as authors, one or more persons or entities 206 | responsible for authorship of the modifications in the Modified 207 | Version, together with at least five of the principal authors of the 208 | Document (all of its principal authors, if it has fewer than five), 209 | unless they release you from this requirement. 210 | 211 | @item 212 | State on the Title page the name of the publisher of the 213 | Modified Version, as the publisher. 214 | 215 | @item 216 | Preserve all the copyright notices of the Document. 217 | 218 | @item 219 | Add an appropriate copyright notice for your modifications 220 | adjacent to the other copyright notices. 221 | 222 | @item 223 | Include, immediately after the copyright notices, a license notice 224 | giving the public permission to use the Modified Version under the 225 | terms of this License, in the form shown in the Addendum below. 226 | 227 | @item 228 | Preserve in that license notice the full lists of Invariant Sections 229 | and required Cover Texts given in the Document's license notice. 230 | 231 | @item 232 | Include an unaltered copy of this License. 233 | 234 | @item 235 | Preserve the section Entitled ``History'', Preserve its Title, and add 236 | to it an item stating at least the title, year, new authors, and 237 | publisher of the Modified Version as given on the Title Page. If 238 | there is no section Entitled ``History'' in the Document, create one 239 | stating the title, year, authors, and publisher of the Document as 240 | given on its Title Page, then add an item describing the Modified 241 | Version as stated in the previous sentence. 242 | 243 | @item 244 | Preserve the network location, if any, given in the Document for 245 | public access to a Transparent copy of the Document, and likewise 246 | the network locations given in the Document for previous versions 247 | it was based on. These may be placed in the ``History'' section. 248 | You may omit a network location for a work that was published at 249 | least four years before the Document itself, or if the original 250 | publisher of the version it refers to gives permission. 251 | 252 | @item 253 | For any section Entitled ``Acknowledgements'' or ``Dedications'', Preserve 254 | the Title of the section, and preserve in the section all the 255 | substance and tone of each of the contributor acknowledgements and/or 256 | dedications given therein. 257 | 258 | @item 259 | Preserve all the Invariant Sections of the Document, 260 | unaltered in their text and in their titles. Section numbers 261 | or the equivalent are not considered part of the section titles. 262 | 263 | @item 264 | Delete any section Entitled ``Endorsements''. Such a section 265 | may not be included in the Modified Version. 266 | 267 | @item 268 | Do not retitle any existing section to be Entitled ``Endorsements'' or 269 | to conflict in title with any Invariant Section. 270 | 271 | @item 272 | Preserve any Warranty Disclaimers. 273 | @end enumerate 274 | 275 | If the Modified Version includes new front-matter sections or 276 | appendices that qualify as Secondary Sections and contain no material 277 | copied from the Document, you may at your option designate some or all 278 | of these sections as invariant. To do this, add their titles to the 279 | list of Invariant Sections in the Modified Version's license notice. 280 | These titles must be distinct from any other section titles. 281 | 282 | You may add a section Entitled ``Endorsements'', provided it contains 283 | nothing but endorsements of your Modified Version by various 284 | parties---for example, statements of peer review or that the text has 285 | been approved by an organization as the authoritative definition of a 286 | standard. 287 | 288 | You may add a passage of up to five words as a Front-Cover Text, and a 289 | passage of up to 25 words as a Back-Cover Text, to the end of the list 290 | of Cover Texts in the Modified Version. Only one passage of 291 | Front-Cover Text and one of Back-Cover Text may be added by (or 292 | through arrangements made by) any one entity. If the Document already 293 | includes a cover text for the same cover, previously added by you or 294 | by arrangement made by the same entity you are acting on behalf of, 295 | you may not add another; but you may replace the old one, on explicit 296 | permission from the previous publisher that added the old one. 297 | 298 | The author(s) and publisher(s) of the Document do not by this License 299 | give permission to use their names for publicity for or to assert or 300 | imply endorsement of any Modified Version. 301 | 302 | @item 303 | COMBINING DOCUMENTS 304 | 305 | You may combine the Document with other documents released under this 306 | License, under the terms defined in section 4 above for modified 307 | versions, provided that you include in the combination all of the 308 | Invariant Sections of all of the original documents, unmodified, and 309 | list them all as Invariant Sections of your combined work in its 310 | license notice, and that you preserve all their Warranty Disclaimers. 311 | 312 | The combined work need only contain one copy of this License, and 313 | multiple identical Invariant Sections may be replaced with a single 314 | copy. If there are multiple Invariant Sections with the same name but 315 | different contents, make the title of each such section unique by 316 | adding at the end of it, in parentheses, the name of the original 317 | author or publisher of that section if known, or else a unique number. 318 | Make the same adjustment to the section titles in the list of 319 | Invariant Sections in the license notice of the combined work. 320 | 321 | In the combination, you must combine any sections Entitled ``History'' 322 | in the various original documents, forming one section Entitled 323 | ``History''; likewise combine any sections Entitled ``Acknowledgements'', 324 | and any sections Entitled ``Dedications''. You must delete all 325 | sections Entitled ``Endorsements.'' 326 | 327 | @item 328 | COLLECTIONS OF DOCUMENTS 329 | 330 | You may make a collection consisting of the Document and other documents 331 | released under this License, and replace the individual copies of this 332 | License in the various documents with a single copy that is included in 333 | the collection, provided that you follow the rules of this License for 334 | verbatim copying of each of the documents in all other respects. 335 | 336 | You may extract a single document from such a collection, and distribute 337 | it individually under this License, provided you insert a copy of this 338 | License into the extracted document, and follow this License in all 339 | other respects regarding verbatim copying of that document. 340 | 341 | @item 342 | AGGREGATION WITH INDEPENDENT WORKS 343 | 344 | A compilation of the Document or its derivatives with other separate 345 | and independent documents or works, in or on a volume of a storage or 346 | distribution medium, is called an ``aggregate'' if the copyright 347 | resulting from the compilation is not used to limit the legal rights 348 | of the compilation's users beyond what the individual works permit. 349 | When the Document is included in an aggregate, this License does not 350 | apply to the other works in the aggregate which are not themselves 351 | derivative works of the Document. 352 | 353 | If the Cover Text requirement of section 3 is applicable to these 354 | copies of the Document, then if the Document is less than one half of 355 | the entire aggregate, the Document's Cover Texts may be placed on 356 | covers that bracket the Document within the aggregate, or the 357 | electronic equivalent of covers if the Document is in electronic form. 358 | Otherwise they must appear on printed covers that bracket the whole 359 | aggregate. 360 | 361 | @item 362 | TRANSLATION 363 | 364 | Translation is considered a kind of modification, so you may 365 | distribute translations of the Document under the terms of section 4. 366 | Replacing Invariant Sections with translations requires special 367 | permission from their copyright holders, but you may include 368 | translations of some or all Invariant Sections in addition to the 369 | original versions of these Invariant Sections. You may include a 370 | translation of this License, and all the license notices in the 371 | Document, and any Warranty Disclaimers, provided that you also include 372 | the original English version of this License and the original versions 373 | of those notices and disclaimers. In case of a disagreement between 374 | the translation and the original version of this License or a notice 375 | or disclaimer, the original version will prevail. 376 | 377 | If a section in the Document is Entitled ``Acknowledgements'', 378 | ``Dedications'', or ``History'', the requirement (section 4) to Preserve 379 | its Title (section 1) will typically require changing the actual 380 | title. 381 | 382 | @item 383 | TERMINATION 384 | 385 | You may not copy, modify, sublicense, or distribute the Document 386 | except as expressly provided under this License. Any attempt 387 | otherwise to copy, modify, sublicense, or distribute it is void, and 388 | will automatically terminate your rights under this License. 389 | 390 | However, if you cease all violation of this License, then your license 391 | from a particular copyright holder is reinstated (a) provisionally, 392 | unless and until the copyright holder explicitly and finally 393 | terminates your license, and (b) permanently, if the copyright holder 394 | fails to notify you of the violation by some reasonable means prior to 395 | 60 days after the cessation. 396 | 397 | Moreover, your license from a particular copyright holder is 398 | reinstated permanently if the copyright holder notifies you of the 399 | violation by some reasonable means, this is the first time you have 400 | received notice of violation of this License (for any work) from that 401 | copyright holder, and you cure the violation prior to 30 days after 402 | your receipt of the notice. 403 | 404 | Termination of your rights under this section does not terminate the 405 | licenses of parties who have received copies or rights from you under 406 | this License. If your rights have been terminated and not permanently 407 | reinstated, receipt of a copy of some or all of the same material does 408 | not give you any rights to use it. 409 | 410 | @item 411 | FUTURE REVISIONS OF THIS LICENSE 412 | 413 | The Free Software Foundation may publish new, revised versions 414 | of the GNU Free Documentation License from time to time. Such new 415 | versions will be similar in spirit to the present version, but may 416 | differ in detail to address new problems or concerns. See 417 | @uref{https://www.gnu.org/licenses/}. 418 | 419 | Each version of the License is given a distinguishing version number. 420 | If the Document specifies that a particular numbered version of this 421 | License ``or any later version'' applies to it, you have the option of 422 | following the terms and conditions either of that specified version or 423 | of any later version that has been published (not as a draft) by the 424 | Free Software Foundation. If the Document does not specify a version 425 | number of this License, you may choose any version ever published (not 426 | as a draft) by the Free Software Foundation. If the Document 427 | specifies that a proxy can decide which future versions of this 428 | License can be used, that proxy's public statement of acceptance of a 429 | version permanently authorizes you to choose that version for the 430 | Document. 431 | 432 | @item 433 | RELICENSING 434 | 435 | ``Massive Multiauthor Collaboration Site'' (or ``MMC Site'') means any 436 | World Wide Web server that publishes copyrightable works and also 437 | provides prominent facilities for anybody to edit those works. A 438 | public wiki that anybody can edit is an example of such a server. A 439 | ``Massive Multiauthor Collaboration'' (or ``MMC'') contained in the 440 | site means any set of copyrightable works thus published on the MMC 441 | site. 442 | 443 | ``CC-BY-SA'' means the Creative Commons Attribution-Share Alike 3.0 444 | license published by Creative Commons Corporation, a not-for-profit 445 | corporation with a principal place of business in San Francisco, 446 | California, as well as future copyleft versions of that license 447 | published by that same organization. 448 | 449 | ``Incorporate'' means to publish or republish a Document, in whole or 450 | in part, as part of another Document. 451 | 452 | An MMC is ``eligible for relicensing'' if it is licensed under this 453 | License, and if all works that were first published under this License 454 | somewhere other than this MMC, and subsequently incorporated in whole 455 | or in part into the MMC, (1) had no cover texts or invariant sections, 456 | and (2) were thus incorporated prior to November 1, 2008. 457 | 458 | The operator of an MMC Site may republish an MMC contained in the site 459 | under CC-BY-SA on the same site at any time before August 1, 2009, 460 | provided the MMC is eligible for relicensing. 461 | 462 | @end enumerate 463 | 464 | @page 465 | @heading ADDENDUM: How to use this License for your documents 466 | 467 | To use this License in a document you have written, include a copy of 468 | the License in the document and put the following copyright and 469 | license notices just after the title page: 470 | 471 | @smallexample 472 | @group 473 | Copyright (C) @var{year} @var{your name}. 474 | Permission is granted to copy, distribute and/or modify this document 475 | under the terms of the GNU Free Documentation License, Version 1.3 476 | or any later version published by the Free Software Foundation; 477 | with no Invariant Sections, no Front-Cover Texts, and no Back-Cover 478 | Texts. A copy of the license is included in the section entitled ``GNU 479 | Free Documentation License''. 480 | @end group 481 | @end smallexample 482 | 483 | If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts, 484 | replace the ``with@dots{}Texts.''@: line with this: 485 | 486 | @smallexample 487 | @group 488 | with the Invariant Sections being @var{list their titles}, with 489 | the Front-Cover Texts being @var{list}, and with the Back-Cover Texts 490 | being @var{list}. 491 | @end group 492 | @end smallexample 493 | 494 | If you have Invariant Sections without Cover Texts, or some other 495 | combination of the three, merge those two alternatives to suit the 496 | situation. 497 | 498 | If your document contains nontrivial examples of program code, we 499 | recommend releasing these examples in parallel under your choice of 500 | free software license, such as the GNU General Public License, 501 | to permit their use in free software. 502 | 503 | @c Local Variables: 504 | @c ispell-local-pdict: "ispell-dict" 505 | @c End: 506 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | GNU GENERAL PUBLIC LICENSE 2 | Version 3, 29 June 2007 3 | 4 | Copyright (C) 2007 Free Software Foundation, Inc. 5 | Everyone is permitted to copy and distribute verbatim copies 6 | of this license document, but changing it is not allowed. 7 | 8 | Preamble 9 | 10 | The GNU General Public License is a free, copyleft license for 11 | software and other kinds of works. 12 | 13 | The licenses for most software and other practical works are designed 14 | to take away your freedom to share and change the works. By contrast, 15 | the GNU General Public License is intended to guarantee your freedom to 16 | share and change all versions of a program--to make sure it remains free 17 | software for all its users. We, the Free Software Foundation, use the 18 | GNU General Public License for most of our software; it applies also to 19 | any other work released this way by its authors. You can apply it to 20 | your programs, too. 21 | 22 | When we speak of free software, we are referring to freedom, not 23 | price. Our General Public Licenses are designed to make sure that you 24 | have the freedom to distribute copies of free software (and charge for 25 | them if you wish), that you receive source code or can get it if you 26 | want it, that you can change the software or use pieces of it in new 27 | free programs, and that you know you can do these things. 28 | 29 | To protect your rights, we need to prevent others from denying you 30 | these rights or asking you to surrender the rights. Therefore, you have 31 | certain responsibilities if you distribute copies of the software, or if 32 | you modify it: responsibilities to respect the freedom of others. 33 | 34 | For example, if you distribute copies of such a program, whether 35 | gratis or for a fee, you must pass on to the recipients the same 36 | freedoms that you received. You must make sure that they, too, receive 37 | or can get the source code. And you must show them these terms so they 38 | know their rights. 39 | 40 | Developers that use the GNU GPL protect your rights with two steps: 41 | (1) assert copyright on the software, and (2) offer you this License 42 | giving you legal permission to copy, distribute and/or modify it. 43 | 44 | For the developers' and authors' protection, the GPL clearly explains 45 | that there is no warranty for this free software. For both users' and 46 | authors' sake, the GPL requires that modified versions be marked as 47 | changed, so that their problems will not be attributed erroneously to 48 | authors of previous versions. 49 | 50 | Some devices are designed to deny users access to install or run 51 | modified versions of the software inside them, although the manufacturer 52 | can do so. This is fundamentally incompatible with the aim of 53 | protecting users' freedom to change the software. The systematic 54 | pattern of such abuse occurs in the area of products for individuals to 55 | use, which is precisely where it is most unacceptable. Therefore, we 56 | have designed this version of the GPL to prohibit the practice for those 57 | products. If such problems arise substantially in other domains, we 58 | stand ready to extend this provision to those domains in future versions 59 | of the GPL, as needed to protect the freedom of users. 60 | 61 | Finally, every program is threatened constantly by software patents. 62 | States should not allow patents to restrict development and use of 63 | software on general-purpose computers, but in those that do, we wish to 64 | avoid the special danger that patents applied to a free program could 65 | make it effectively proprietary. To prevent this, the GPL assures that 66 | patents cannot be used to render the program non-free. 67 | 68 | The precise terms and conditions for copying, distribution and 69 | modification follow. 70 | 71 | TERMS AND CONDITIONS 72 | 73 | 0. Definitions. 74 | 75 | "This License" refers to version 3 of the GNU General Public License. 76 | 77 | "Copyright" also means copyright-like laws that apply to other kinds of 78 | works, such as semiconductor masks. 79 | 80 | "The Program" refers to any copyrightable work licensed under this 81 | License. Each licensee is addressed as "you". "Licensees" and 82 | "recipients" may be individuals or organizations. 83 | 84 | To "modify" a work means to copy from or adapt all or part of the work 85 | in a fashion requiring copyright permission, other than the making of an 86 | exact copy. The resulting work is called a "modified version" of the 87 | earlier work or a work "based on" the earlier work. 88 | 89 | A "covered work" means either the unmodified Program or a work based 90 | on the Program. 91 | 92 | To "propagate" a work means to do anything with it that, without 93 | permission, would make you directly or secondarily liable for 94 | infringement under applicable copyright law, except executing it on a 95 | computer or modifying a private copy. Propagation includes copying, 96 | distribution (with or without modification), making available to the 97 | public, and in some countries other activities as well. 98 | 99 | To "convey" a work means any kind of propagation that enables other 100 | parties to make or receive copies. Mere interaction with a user through 101 | a computer network, with no transfer of a copy, is not conveying. 102 | 103 | An interactive user interface displays "Appropriate Legal Notices" 104 | to the extent that it includes a convenient and prominently visible 105 | feature that (1) displays an appropriate copyright notice, and (2) 106 | tells the user that there is no warranty for the work (except to the 107 | extent that warranties are provided), that licensees may convey the 108 | work under this License, and how to view a copy of this License. If 109 | the interface presents a list of user commands or options, such as a 110 | menu, a prominent item in the list meets this criterion. 111 | 112 | 1. Source Code. 113 | 114 | The "source code" for a work means the preferred form of the work 115 | for making modifications to it. "Object code" means any non-source 116 | form of a work. 117 | 118 | A "Standard Interface" means an interface that either is an official 119 | standard defined by a recognized standards body, or, in the case of 120 | interfaces specified for a particular programming language, one that 121 | is widely used among developers working in that language. 122 | 123 | The "System Libraries" of an executable work include anything, other 124 | than the work as a whole, that (a) is included in the normal form of 125 | packaging a Major Component, but which is not part of that Major 126 | Component, and (b) serves only to enable use of the work with that 127 | Major Component, or to implement a Standard Interface for which an 128 | implementation is available to the public in source code form. A 129 | "Major Component", in this context, means a major essential component 130 | (kernel, window system, and so on) of the specific operating system 131 | (if any) on which the executable work runs, or a compiler used to 132 | produce the work, or an object code interpreter used to run it. 133 | 134 | The "Corresponding Source" for a work in object code form means all 135 | the source code needed to generate, install, and (for an executable 136 | work) run the object code and to modify the work, including scripts to 137 | control those activities. However, it does not include the work's 138 | System Libraries, or general-purpose tools or generally available free 139 | programs which are used unmodified in performing those activities but 140 | which are not part of the work. For example, Corresponding Source 141 | includes interface definition files associated with source files for 142 | the work, and the source code for shared libraries and dynamically 143 | linked subprograms that the work is specifically designed to require, 144 | such as by intimate data communication or control flow between those 145 | subprograms and other parts of the work. 146 | 147 | The Corresponding Source need not include anything that users 148 | can regenerate automatically from other parts of the Corresponding 149 | Source. 150 | 151 | The Corresponding Source for a work in source code form is that 152 | same work. 153 | 154 | 2. Basic Permissions. 155 | 156 | All rights granted under this License are granted for the term of 157 | copyright on the Program, and are irrevocable provided the stated 158 | conditions are met. This License explicitly affirms your unlimited 159 | permission to run the unmodified Program. The output from running a 160 | covered work is covered by this License only if the output, given its 161 | content, constitutes a covered work. This License acknowledges your 162 | rights of fair use or other equivalent, as provided by copyright law. 163 | 164 | You may make, run and propagate covered works that you do not 165 | convey, without conditions so long as your license otherwise remains 166 | in force. You may convey covered works to others for the sole purpose 167 | of having them make modifications exclusively for you, or provide you 168 | with facilities for running those works, provided that you comply with 169 | the terms of this License in conveying all material for which you do 170 | not control copyright. Those thus making or running the covered works 171 | for you must do so exclusively on your behalf, under your direction 172 | and control, on terms that prohibit them from making any copies of 173 | your copyrighted material outside their relationship with you. 174 | 175 | Conveying under any other circumstances is permitted solely under 176 | the conditions stated below. Sublicensing is not allowed; section 10 177 | makes it unnecessary. 178 | 179 | 3. Protecting Users' Legal Rights From Anti-Circumvention Law. 180 | 181 | No covered work shall be deemed part of an effective technological 182 | measure under any applicable law fulfilling obligations under article 183 | 11 of the WIPO copyright treaty adopted on 20 December 1996, or 184 | similar laws prohibiting or restricting circumvention of such 185 | measures. 186 | 187 | When you convey a covered work, you waive any legal power to forbid 188 | circumvention of technological measures to the extent such circumvention 189 | is effected by exercising rights under this License with respect to 190 | the covered work, and you disclaim any intention to limit operation or 191 | modification of the work as a means of enforcing, against the work's 192 | users, your or third parties' legal rights to forbid circumvention of 193 | technological measures. 194 | 195 | 4. Conveying Verbatim Copies. 196 | 197 | You may convey verbatim copies of the Program's source code as you 198 | receive it, in any medium, provided that you conspicuously and 199 | appropriately publish on each copy an appropriate copyright notice; 200 | keep intact all notices stating that this License and any 201 | non-permissive terms added in accord with section 7 apply to the code; 202 | keep intact all notices of the absence of any warranty; and give all 203 | recipients a copy of this License along with the Program. 204 | 205 | You may charge any price or no price for each copy that you convey, 206 | and you may offer support or warranty protection for a fee. 207 | 208 | 5. Conveying Modified Source Versions. 209 | 210 | You may convey a work based on the Program, or the modifications to 211 | produce it from the Program, in the form of source code under the 212 | terms of section 4, provided that you also meet all of these conditions: 213 | 214 | a) The work must carry prominent notices stating that you modified 215 | it, and giving a relevant date. 216 | 217 | b) The work must carry prominent notices stating that it is 218 | released under this License and any conditions added under section 219 | 7. This requirement modifies the requirement in section 4 to 220 | "keep intact all notices". 221 | 222 | c) You must license the entire work, as a whole, under this 223 | License to anyone who comes into possession of a copy. This 224 | License will therefore apply, along with any applicable section 7 225 | additional terms, to the whole of the work, and all its parts, 226 | regardless of how they are packaged. This License gives no 227 | permission to license the work in any other way, but it does not 228 | invalidate such permission if you have separately received it. 229 | 230 | d) If the work has interactive user interfaces, each must display 231 | Appropriate Legal Notices; however, if the Program has interactive 232 | interfaces that do not display Appropriate Legal Notices, your 233 | work need not make them do so. 234 | 235 | A compilation of a covered work with other separate and independent 236 | works, which are not by their nature extensions of the covered work, 237 | and which are not combined with it such as to form a larger program, 238 | in or on a volume of a storage or distribution medium, is called an 239 | "aggregate" if the compilation and its resulting copyright are not 240 | used to limit the access or legal rights of the compilation's users 241 | beyond what the individual works permit. Inclusion of a covered work 242 | in an aggregate does not cause this License to apply to the other 243 | parts of the aggregate. 244 | 245 | 6. Conveying Non-Source Forms. 246 | 247 | You may convey a covered work in object code form under the terms 248 | of sections 4 and 5, provided that you also convey the 249 | machine-readable Corresponding Source under the terms of this License, 250 | in one of these ways: 251 | 252 | a) Convey the object code in, or embodied in, a physical product 253 | (including a physical distribution medium), accompanied by the 254 | Corresponding Source fixed on a durable physical medium 255 | customarily used for software interchange. 256 | 257 | b) Convey the object code in, or embodied in, a physical product 258 | (including a physical distribution medium), accompanied by a 259 | written offer, valid for at least three years and valid for as 260 | long as you offer spare parts or customer support for that product 261 | model, to give anyone who possesses the object code either (1) a 262 | copy of the Corresponding Source for all the software in the 263 | product that is covered by this License, on a durable physical 264 | medium customarily used for software interchange, for a price no 265 | more than your reasonable cost of physically performing this 266 | conveying of source, or (2) access to copy the 267 | Corresponding Source from a network server at no charge. 268 | 269 | c) Convey individual copies of the object code with a copy of the 270 | written offer to provide the Corresponding Source. This 271 | alternative is allowed only occasionally and noncommercially, and 272 | only if you received the object code with such an offer, in accord 273 | with subsection 6b. 274 | 275 | d) Convey the object code by offering access from a designated 276 | place (gratis or for a charge), and offer equivalent access to the 277 | Corresponding Source in the same way through the same place at no 278 | further charge. You need not require recipients to copy the 279 | Corresponding Source along with the object code. If the place to 280 | copy the object code is a network server, the Corresponding Source 281 | may be on a different server (operated by you or a third party) 282 | that supports equivalent copying facilities, provided you maintain 283 | clear directions next to the object code saying where to find the 284 | Corresponding Source. Regardless of what server hosts the 285 | Corresponding Source, you remain obligated to ensure that it is 286 | available for as long as needed to satisfy these requirements. 287 | 288 | e) Convey the object code using peer-to-peer transmission, provided 289 | you inform other peers where the object code and Corresponding 290 | Source of the work are being offered to the general public at no 291 | charge under subsection 6d. 292 | 293 | A separable portion of the object code, whose source code is excluded 294 | from the Corresponding Source as a System Library, need not be 295 | included in conveying the object code work. 296 | 297 | A "User Product" is either (1) a "consumer product", which means any 298 | tangible personal property which is normally used for personal, family, 299 | or household purposes, or (2) anything designed or sold for incorporation 300 | into a dwelling. In determining whether a product is a consumer product, 301 | doubtful cases shall be resolved in favor of coverage. For a particular 302 | product received by a particular user, "normally used" refers to a 303 | typical or common use of that class of product, regardless of the status 304 | of the particular user or of the way in which the particular user 305 | actually uses, or expects or is expected to use, the product. A product 306 | is a consumer product regardless of whether the product has substantial 307 | commercial, industrial or non-consumer uses, unless such uses represent 308 | the only significant mode of use of the product. 309 | 310 | "Installation Information" for a User Product means any methods, 311 | procedures, authorization keys, or other information required to install 312 | and execute modified versions of a covered work in that User Product from 313 | a modified version of its Corresponding Source. The information must 314 | suffice to ensure that the continued functioning of the modified object 315 | code is in no case prevented or interfered with solely because 316 | modification has been made. 317 | 318 | If you convey an object code work under this section in, or with, or 319 | specifically for use in, a User Product, and the conveying occurs as 320 | part of a transaction in which the right of possession and use of the 321 | User Product is transferred to the recipient in perpetuity or for a 322 | fixed term (regardless of how the transaction is characterized), the 323 | Corresponding Source conveyed under this section must be accompanied 324 | by the Installation Information. But this requirement does not apply 325 | if neither you nor any third party retains the ability to install 326 | modified object code on the User Product (for example, the work has 327 | been installed in ROM). 328 | 329 | The requirement to provide Installation Information does not include a 330 | requirement to continue to provide support service, warranty, or updates 331 | for a work that has been modified or installed by the recipient, or for 332 | the User Product in which it has been modified or installed. Access to a 333 | network may be denied when the modification itself materially and 334 | adversely affects the operation of the network or violates the rules and 335 | protocols for communication across the network. 336 | 337 | Corresponding Source conveyed, and Installation Information provided, 338 | in accord with this section must be in a format that is publicly 339 | documented (and with an implementation available to the public in 340 | source code form), and must require no special password or key for 341 | unpacking, reading or copying. 342 | 343 | 7. Additional Terms. 344 | 345 | "Additional permissions" are terms that supplement the terms of this 346 | License by making exceptions from one or more of its conditions. 347 | Additional permissions that are applicable to the entire Program shall 348 | be treated as though they were included in this License, to the extent 349 | that they are valid under applicable law. If additional permissions 350 | apply only to part of the Program, that part may be used separately 351 | under those permissions, but the entire Program remains governed by 352 | this License without regard to the additional permissions. 353 | 354 | When you convey a copy of a covered work, you may at your option 355 | remove any additional permissions from that copy, or from any part of 356 | it. (Additional permissions may be written to require their own 357 | removal in certain cases when you modify the work.) You may place 358 | additional permissions on material, added by you to a covered work, 359 | for which you have or can give appropriate copyright permission. 360 | 361 | Notwithstanding any other provision of this License, for material you 362 | add to a covered work, you may (if authorized by the copyright holders of 363 | that material) supplement the terms of this License with terms: 364 | 365 | a) Disclaiming warranty or limiting liability differently from the 366 | terms of sections 15 and 16 of this License; or 367 | 368 | b) Requiring preservation of specified reasonable legal notices or 369 | author attributions in that material or in the Appropriate Legal 370 | Notices displayed by works containing it; or 371 | 372 | c) Prohibiting misrepresentation of the origin of that material, or 373 | requiring that modified versions of such material be marked in 374 | reasonable ways as different from the original version; or 375 | 376 | d) Limiting the use for publicity purposes of names of licensors or 377 | authors of the material; or 378 | 379 | e) Declining to grant rights under trademark law for use of some 380 | trade names, trademarks, or service marks; or 381 | 382 | f) Requiring indemnification of licensors and authors of that 383 | material by anyone who conveys the material (or modified versions of 384 | it) with contractual assumptions of liability to the recipient, for 385 | any liability that these contractual assumptions directly impose on 386 | those licensors and authors. 387 | 388 | All other non-permissive additional terms are considered "further 389 | restrictions" within the meaning of section 10. If the Program as you 390 | received it, or any part of it, contains a notice stating that it is 391 | governed by this License along with a term that is a further 392 | restriction, you may remove that term. If a license document contains 393 | a further restriction but permits relicensing or conveying under this 394 | License, you may add to a covered work material governed by the terms 395 | of that license document, provided that the further restriction does 396 | not survive such relicensing or conveying. 397 | 398 | If you add terms to a covered work in accord with this section, you 399 | must place, in the relevant source files, a statement of the 400 | additional terms that apply to those files, or a notice indicating 401 | where to find the applicable terms. 402 | 403 | Additional terms, permissive or non-permissive, may be stated in the 404 | form of a separately written license, or stated as exceptions; 405 | the above requirements apply either way. 406 | 407 | 8. Termination. 408 | 409 | You may not propagate or modify a covered work except as expressly 410 | provided under this License. Any attempt otherwise to propagate or 411 | modify it is void, and will automatically terminate your rights under 412 | this License (including any patent licenses granted under the third 413 | paragraph of section 11). 414 | 415 | However, if you cease all violation of this License, then your 416 | license from a particular copyright holder is reinstated (a) 417 | provisionally, unless and until the copyright holder explicitly and 418 | finally terminates your license, and (b) permanently, if the copyright 419 | holder fails to notify you of the violation by some reasonable means 420 | prior to 60 days after the cessation. 421 | 422 | Moreover, your license from a particular copyright holder is 423 | reinstated permanently if the copyright holder notifies you of the 424 | violation by some reasonable means, this is the first time you have 425 | received notice of violation of this License (for any work) from that 426 | copyright holder, and you cure the violation prior to 30 days after 427 | your receipt of the notice. 428 | 429 | Termination of your rights under this section does not terminate the 430 | licenses of parties who have received copies or rights from you under 431 | this License. If your rights have been terminated and not permanently 432 | reinstated, you do not qualify to receive new licenses for the same 433 | material under section 10. 434 | 435 | 9. Acceptance Not Required for Having Copies. 436 | 437 | You are not required to accept this License in order to receive or 438 | run a copy of the Program. Ancillary propagation of a covered work 439 | occurring solely as a consequence of using peer-to-peer transmission 440 | to receive a copy likewise does not require acceptance. However, 441 | nothing other than this License grants you permission to propagate or 442 | modify any covered work. These actions infringe copyright if you do 443 | not accept this License. Therefore, by modifying or propagating a 444 | covered work, you indicate your acceptance of this License to do so. 445 | 446 | 10. Automatic Licensing of Downstream Recipients. 447 | 448 | Each time you convey a covered work, the recipient automatically 449 | receives a license from the original licensors, to run, modify and 450 | propagate that work, subject to this License. You are not responsible 451 | for enforcing compliance by third parties with this License. 452 | 453 | An "entity transaction" is a transaction transferring control of an 454 | organization, or substantially all assets of one, or subdividing an 455 | organization, or merging organizations. If propagation of a covered 456 | work results from an entity transaction, each party to that 457 | transaction who receives a copy of the work also receives whatever 458 | licenses to the work the party's predecessor in interest had or could 459 | give under the previous paragraph, plus a right to possession of the 460 | Corresponding Source of the work from the predecessor in interest, if 461 | the predecessor has it or can get it with reasonable efforts. 462 | 463 | You may not impose any further restrictions on the exercise of the 464 | rights granted or affirmed under this License. For example, you may 465 | not impose a license fee, royalty, or other charge for exercise of 466 | rights granted under this License, and you may not initiate litigation 467 | (including a cross-claim or counterclaim in a lawsuit) alleging that 468 | any patent claim is infringed by making, using, selling, offering for 469 | sale, or importing the Program or any portion of it. 470 | 471 | 11. Patents. 472 | 473 | A "contributor" is a copyright holder who authorizes use under this 474 | License of the Program or a work on which the Program is based. The 475 | work thus licensed is called the contributor's "contributor version". 476 | 477 | A contributor's "essential patent claims" are all patent claims 478 | owned or controlled by the contributor, whether already acquired or 479 | hereafter acquired, that would be infringed by some manner, permitted 480 | by this License, of making, using, or selling its contributor version, 481 | but do not include claims that would be infringed only as a 482 | consequence of further modification of the contributor version. For 483 | purposes of this definition, "control" includes the right to grant 484 | patent sublicenses in a manner consistent with the requirements of 485 | this License. 486 | 487 | Each contributor grants you a non-exclusive, worldwide, royalty-free 488 | patent license under the contributor's essential patent claims, to 489 | make, use, sell, offer for sale, import and otherwise run, modify and 490 | propagate the contents of its contributor version. 491 | 492 | In the following three paragraphs, a "patent license" is any express 493 | agreement or commitment, however denominated, not to enforce a patent 494 | (such as an express permission to practice a patent or covenant not to 495 | sue for patent infringement). To "grant" such a patent license to a 496 | party means to make such an agreement or commitment not to enforce a 497 | patent against the party. 498 | 499 | If you convey a covered work, knowingly relying on a patent license, 500 | and the Corresponding Source of the work is not available for anyone 501 | to copy, free of charge and under the terms of this License, through a 502 | publicly available network server or other readily accessible means, 503 | then you must either (1) cause the Corresponding Source to be so 504 | available, or (2) arrange to deprive yourself of the benefit of the 505 | patent license for this particular work, or (3) arrange, in a manner 506 | consistent with the requirements of this License, to extend the patent 507 | license to downstream recipients. "Knowingly relying" means you have 508 | actual knowledge that, but for the patent license, your conveying the 509 | covered work in a country, or your recipient's use of the covered work 510 | in a country, would infringe one or more identifiable patents in that 511 | country that you have reason to believe are valid. 512 | 513 | If, pursuant to or in connection with a single transaction or 514 | arrangement, you convey, or propagate by procuring conveyance of, a 515 | covered work, and grant a patent license to some of the parties 516 | receiving the covered work authorizing them to use, propagate, modify 517 | or convey a specific copy of the covered work, then the patent license 518 | you grant is automatically extended to all recipients of the covered 519 | work and works based on it. 520 | 521 | A patent license is "discriminatory" if it does not include within 522 | the scope of its coverage, prohibits the exercise of, or is 523 | conditioned on the non-exercise of one or more of the rights that are 524 | specifically granted under this License. You may not convey a covered 525 | work if you are a party to an arrangement with a third party that is 526 | in the business of distributing software, under which you make payment 527 | to the third party based on the extent of your activity of conveying 528 | the work, and under which the third party grants, to any of the 529 | parties who would receive the covered work from you, a discriminatory 530 | patent license (a) in connection with copies of the covered work 531 | conveyed by you (or copies made from those copies), or (b) primarily 532 | for and in connection with specific products or compilations that 533 | contain the covered work, unless you entered into that arrangement, 534 | or that patent license was granted, prior to 28 March 2007. 535 | 536 | Nothing in this License shall be construed as excluding or limiting 537 | any implied license or other defenses to infringement that may 538 | otherwise be available to you under applicable patent law. 539 | 540 | 12. No Surrender of Others' Freedom. 541 | 542 | If conditions are imposed on you (whether by court order, agreement or 543 | otherwise) that contradict the conditions of this License, they do not 544 | excuse you from the conditions of this License. If you cannot convey a 545 | covered work so as to satisfy simultaneously your obligations under this 546 | License and any other pertinent obligations, then as a consequence you may 547 | not convey it at all. For example, if you agree to terms that obligate you 548 | to collect a royalty for further conveying from those to whom you convey 549 | the Program, the only way you could satisfy both those terms and this 550 | License would be to refrain entirely from conveying the Program. 551 | 552 | 13. Use with the GNU Affero General Public License. 553 | 554 | Notwithstanding any other provision of this License, you have 555 | permission to link or combine any covered work with a work licensed 556 | under version 3 of the GNU Affero General Public License into a single 557 | combined work, and to convey the resulting work. The terms of this 558 | License will continue to apply to the part which is the covered work, 559 | but the special requirements of the GNU Affero General Public License, 560 | section 13, concerning interaction through a network will apply to the 561 | combination as such. 562 | 563 | 14. Revised Versions of this License. 564 | 565 | The Free Software Foundation may publish revised and/or new versions of 566 | the GNU General Public License from time to time. Such new versions will 567 | be similar in spirit to the present version, but may differ in detail to 568 | address new problems or concerns. 569 | 570 | Each version is given a distinguishing version number. If the 571 | Program specifies that a certain numbered version of the GNU General 572 | Public License "or any later version" applies to it, you have the 573 | option of following the terms and conditions either of that numbered 574 | version or of any later version published by the Free Software 575 | Foundation. If the Program does not specify a version number of the 576 | GNU General Public License, you may choose any version ever published 577 | by the Free Software Foundation. 578 | 579 | If the Program specifies that a proxy can decide which future 580 | versions of the GNU General Public License can be used, that proxy's 581 | public statement of acceptance of a version permanently authorizes you 582 | to choose that version for the Program. 583 | 584 | Later license versions may give you additional or different 585 | permissions. However, no additional obligations are imposed on any 586 | author or copyright holder as a result of your choosing to follow a 587 | later version. 588 | 589 | 15. Disclaimer of Warranty. 590 | 591 | THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY 592 | APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT 593 | HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY 594 | OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, 595 | THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 596 | PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM 597 | IS WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF 598 | ALL NECESSARY SERVICING, REPAIR OR CORRECTION. 599 | 600 | 16. Limitation of Liability. 601 | 602 | IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING 603 | WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR CONVEYS 604 | THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY 605 | GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE 606 | USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF 607 | DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD 608 | PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS), 609 | EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF 610 | SUCH DAMAGES. 611 | 612 | 17. Interpretation of Sections 15 and 16. 613 | 614 | If the disclaimer of warranty and limitation of liability provided 615 | above cannot be given local legal effect according to their terms, 616 | reviewing courts shall apply local law that most closely approximates 617 | an absolute waiver of all civil liability in connection with the 618 | Program, unless a warranty or assumption of liability accompanies a 619 | copy of the Program in return for a fee. 620 | 621 | END OF TERMS AND CONDITIONS 622 | 623 | How to Apply These Terms to Your New Programs 624 | 625 | If you develop a new program, and you want it to be of the greatest 626 | possible use to the public, the best way to achieve this is to make it 627 | free software which everyone can redistribute and change under these terms. 628 | 629 | To do so, attach the following notices to the program. It is safest 630 | to attach them to the start of each source file to most effectively 631 | state the exclusion of warranty; and each file should have at least 632 | the "copyright" line and a pointer to where the full notice is found. 633 | 634 | 635 | Copyright (C) 636 | 637 | This program is free software: you can redistribute it and/or modify 638 | it under the terms of the GNU General Public License as published by 639 | the Free Software Foundation, either version 3 of the License, or 640 | (at your option) any later version. 641 | 642 | This program is distributed in the hope that it will be useful, 643 | but WITHOUT ANY WARRANTY; without even the implied warranty of 644 | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 645 | GNU General Public License for more details. 646 | 647 | You should have received a copy of the GNU General Public License 648 | along with this program. If not, see . 649 | 650 | Also add information on how to contact you by electronic and paper mail. 651 | 652 | If the program does terminal interaction, make it output a short 653 | notice like this when it starts in an interactive mode: 654 | 655 | Copyright (C) 656 | This program comes with ABSOLUTELY NO WARRANTY; for details type `show w'. 657 | This is free software, and you are welcome to redistribute it 658 | under certain conditions; type `show c' for details. 659 | 660 | The hypothetical commands `show w' and `show c' should show the appropriate 661 | parts of the General Public License. Of course, your program's commands 662 | might be different; for a GUI interface, you would use an "about box". 663 | 664 | You should also get your employer (if you work as a programmer) or school, 665 | if any, to sign a "copyright disclaimer" for the program, if necessary. 666 | For more information on this, and how to apply and follow the GNU GPL, see 667 | . 668 | 669 | The GNU General Public License does not permit incorporating your program 670 | into proprietary programs. If your program is a subroutine library, you 671 | may consider it more useful to permit linking proprietary applications with 672 | the library. If this is what you want to do, use the GNU Lesser General 673 | Public License instead of this License. But first, please read 674 | . 675 | -------------------------------------------------------------------------------- /docs/org-remark.org: -------------------------------------------------------------------------------- 1 | #+title: Org-remark User Manual 2 | #+author: Noboru Ota 3 | #+macro: version 1.3.x 4 | #+macro: modified 01 February 2024 5 | #+language: en 6 | #+export_file_name: org-remark.texi 7 | #+texinfo_dir_category: Emacs 8 | #+texinfo_dir_title: Org-remark: (org-remark) 9 | #+texinfo_dir_desc: Highlight and annotate any text file 10 | #+texinfo: @paragraphindent asis 11 | #+options: toc:nil ':t 12 | 13 | This manual is for Org-remark version {{{version}}}. The new features introduced with version {{{version}}} are currently only available [[https://elpa.gnu.org/devel/org-remark.html][GNU-devel ELPA]] until the new version is released to [[https://elpa.gnu.org/packages/org-remark.html][GNU-ELPA]]. 14 | 15 | Last updated: {{{modified}}}. 16 | 17 | Org-remark lets you highlight and annotate text files, websites (EWW), EPUB books (nov.el) and Info documentation (Info-mode). 18 | 19 | #+texinfo: @insertcopying 20 | 21 | * COPYING 22 | :PROPERTIES: 23 | :COPYING: t 24 | :END: 25 | 26 | Copyright \copy 2021-2023 Free Software Foundation, Inc. 27 | 28 | #+begin_quote 29 | Permission is granted to copy, distribute and/or modify this document 30 | under the terms of the GNU Free Documentation License, Version 1.3 or 31 | any later version published by the Free Software Foundation; with no 32 | Invariant Sections, with the Front-Cover Texts being “A GNU Manual,” and 33 | with the Back-Cover Texts as in (a) below. A copy of the license is 34 | included in the section entitled “GNU Free Documentation License.” 35 | 36 | (a) The FSF’s Back-Cover Text is: “You have the freedom to copy and 37 | modify this GNU manual.” 38 | #+end_quote 39 | 40 | * Installation 41 | :PROPERTIES: 42 | :CUSTOM_ID: installation 43 | :END: 44 | 45 | This package is available on: 46 | 47 | - [[https://elpa.gnu.org/packages/org-remark.html][GNU-ELPA]] (releases only; equivalent to MELPA-Stable) 48 | - [[https://elpa.gnu.org/devel/org-remark.html][GNU-devel ELPA]] (unreleased main branch; equivalent to MELPA) 49 | 50 | GNU ELPA should be already set up in your Emacs by default. If you wish to add GNU-devel ELPA, simply add its URL to ~package-archives~ like this: 51 | 52 | #+BEGIN_SRC elisp 53 | (add-to-list 'package-archives 54 | '("gnu-devel" . "https://elpa.gnu.org/devel/") :append) 55 | #+END_SRC 56 | 57 | ** Basic Setup 58 | 59 | After installation, we suggest you put the setup below in your configuration. 60 | 61 | #+name: basic-setup 62 | #+begin_src emacs-lisp 63 | (org-remark-global-tracking-mode +1) 64 | 65 | ;; Optional if you would like to highlight websites via eww-mode 66 | (with-eval-after-load 'eww 67 | (org-remark-eww-mode +1)) 68 | 69 | ;; Optional if you would like to highlight EPUB books via nov.el 70 | (with-eval-after-load 'nov 71 | (org-remark-nov-mode +1)) 72 | 73 | ;; Optional if you would like to highlight Info documentation via Info-mode 74 | (with-eval-after-load 'info 75 | (org-remark-info-mode +1)) 76 | #+end_src 77 | 78 | ~org-remark-global-tracking-mode~ automatically turns on ~org-remark-mode~ when you open a file, website via EWW, EPUB book via nov.el, or other supported buffer that has a marginal notes file associated with it. This is useful to keep the location of your highlights correct across Emacs sessions after you shutdown Emacs. 79 | 80 | Unless you explicitly load ~org~ during Emacs initialization, we suggest to defer loading ~org-remark~ (thus there is no ~(require 'org-remark)~ in the example above). This is because it will also pull in ~org~, which can slow down initialization. You can control the timing of loading ~org-remark~ by autoloading some commands in a similar way with the example keybindings below. 81 | 82 | Below are example keybindings you might like to consider: 83 | 84 | #+begin_src emacs-lisp 85 | ;; Key-bind `org-remark-mark' to global-map so that you can call it 86 | ;; globally before the library is loaded. 87 | 88 | (define-key global-map (kbd "C-c n m") #'org-remark-mark) 89 | (define-key global-map (kbd "C-c n l") #'org-remark-mark-line) ; new in v1.3 90 | 91 | ;; The rest of keybidings are done only on loading `org-remark' 92 | (with-eval-after-load 'org-remark 93 | (define-key org-remark-mode-map (kbd "C-c n o") #'org-remark-open) 94 | (define-key org-remark-mode-map (kbd "C-c n ]") #'org-remark-view-next) 95 | (define-key org-remark-mode-map (kbd "C-c n [") #'org-remark-view-prev) 96 | (define-key org-remark-mode-map (kbd "C-c n r") #'org-remark-remove) 97 | (define-key org-remark-mode-map (kbd "C-c n d") #'org-remark-delete)) 98 | #+end_src 99 | 100 | ** Setup with ~use-package~ 101 | 102 | Alternatively, you can use ~use-package~ to set up Org-remark. The example provided below should be equivalent to the setup described above. 103 | 104 | #+name: setup-with-use-package 105 | #+begin_src emacs-lisp 106 | (use-package org-remark-global-tracking 107 | ;; It is recommended that `org-remark-global-tracking-mode' be 108 | ;; enabled when Emacs initializes. You can set it in 109 | ;; `after-init-hook'. 110 | :hook after-init 111 | :config 112 | ;; Selectively keep or comment out the following if you want to use 113 | ;; extensions for Info-mode, EWW, and NOV.el (EPUB) respectively. 114 | (use-package org-remark-info :after info :config (org-remark-info-mode +1)) 115 | (use-package org-remark-eww :after eww :config (org-remark-eww-mode +1)) 116 | (use-package org-remark-nov :after nov :config (org-remark-nov-mode +1))) 117 | 118 | (use-package org-remark 119 | :bind (;; :bind keyword also implicitly defers org-remark itself. 120 | ;; Keybindings before :map is set for global-map. Adjust the keybinds 121 | ;; as you see fit. 122 | ("C-c n m" . org-remark-mark) 123 | ("C-c n l" . org-remark-mark-line) 124 | :map org-remark-mode-map 125 | ("C-c n o" . org-remark-open) 126 | ("C-c n ]" . org-remark-view-next) 127 | ("C-c n [" . org-remark-view-prev) 128 | ("C-c n r" . org-remark-remove) 129 | ("C-c n d" . org-remark-delete))) 130 | #+end_src 131 | 132 | * Getting Started 133 | :PROPERTIES: 134 | :CUSTOM_ID: getting-started 135 | :END: 136 | 137 | ** Highlighting and Annotating 138 | 139 | #+findex: org-remark-mark 140 | #+findex: org-remark-mark-line 141 | #+findex: org-remark-open 142 | #+findex: org-remark-view 143 | #+cindex: Marginal notes file 144 | #+cindex: line-highlight 145 | #+cindex: range-highlight 146 | #+vindex: org-remark-line-margin-side 147 | #+vindex: org-remark-notes-display-buffer-action 148 | 149 | Once you have installed and set it up ([[#installation][Installation]]), Org-remark is simple to use. Select a part of text and call ~M-x org-remark-mark~ to highlight it. You will see the selected text gets highlighted. This is a range-highlight. With the new version 1.3, you can also highlight a whole line in addition to a range of text by calling ~org-remark-mark-line~. Visually, instead of adding a highlight to the line, it will add a mark on the margin of the buffer (the left margin is the default and you can customize it with ~org-remark-line-margin-side~). This is a line-highlight. Both the range- and line-highlights behave the same way except for how they appear in the buffer you are editing or viewing. You can mix them in the same buffer as you see fit for your purposes. 150 | 151 | The menu bar item "Org-remark" is available when you turn on ~org-remark-mode~. It helps you discover Org-remark's main commands. If you use Emacs version 28 or newer, a context menu is also available by right-clicking your mouse. Turn on the Emacs built-in ~context-menu-mode~ to enable the context menu. 152 | 153 | To display the marginal notes for the highlight you have just marked, place your cursor on the highlight and call ~M-x org-remark-open~ or ~M-x org-remark-view~. This will create a new buffer to the left of the current buffer you are editing. You can customize where the marginal notes buffer is to be placed (see the documentation of customizing variable ~org-remark-notes-display-buffer-action~). 154 | 155 | The ~open~ command takes the cursor to the marginal notes buffer for you to edit notes; the ~view~ command keeps the cursor in the current buffer only to display the marginal notes. Both commands narrow the *marginal notes file* to the entry for the highlight under the cursor. The marginal notes file is a normal Org file. Edit your notes just as you would do with any other Org files and save the buffer. 156 | 157 | ** Navigating from One Highlight to Another 158 | 159 | #+findex: org-remark-view-next 160 | #+findex: org-remark-view-prev 161 | #+cindex: Menu in the menu bar 162 | #+cindex: Context menu 163 | 164 | After you have added a couple of highlights in the text, you can move through the highlights easily. Use ~org-remark-view-next~ and ~org-remark-view-prev~ to browse the marginal notes as you move from one highlight to another. They display the marginal notes on the side-window by default. Or use ~org-remark-next~ and ~org-remark-prev~ if you simply want to move to the next/previous highlight without displaying marginal notes for them. 165 | 166 | To make navigation easy, you can use define the same "prefix key" to Org-remark commands like this: 167 | 168 | - ~C-c n o~: ~org-remark-open~ 169 | - ~C-c n ]~: ~org-remark-view-next~ 170 | - ~C-c n [~: ~org-remark-view-prev~ 171 | - ~C-c n r~: ~org-remark-remove~ 172 | - ~C-c n d~: ~org-remark-delete~ 173 | 174 | The ~C-c n~ part is the prefix key common to all of them. If you set the keybindings like this, you can use ~C-c n ]~ once to view the next highlight and keep pressing a single key ~]~ or ~[~ to browse through the next/previous highlights. After you have reached the one you like to act on, press ~o~ to open it, ~r~ or ~d~ to remove/delete it. 175 | 176 | ** Create Your Own Highlighter Pens 177 | 178 | #+cindex: Custom highlighter pens 179 | 180 | Org-remark has a default highlighter pen function, and comes with a set of two additional pens by default: 181 | 182 | - ~org-remark-mark~ :: default highlighter pen 183 | - ~org-remark-mark-line~ :: default line-highlighter pen, which adds a mark on the margin instead of a range of text 184 | - ~org-remark-mark-yellow~ :: yellow highlight with "important" category in the marginal notes entry 185 | - ~org-remark-mark-red-line~ :: wavy red underline with "review" category in the marginal notes entry and "Review this" in tool-tips 186 | 187 | Org-remark lets you create your own custom pen functions with ~org-remark-create~. Use the yellow and red line pens as examples, and create your own. For how to do it, [[#create-custom-pens][How to Create Custom Highlighter Pens]]. 188 | 189 | This is all you need to get started. For more detail, refer to the rest of this user manual, especially [[#usage][Usage]] and [[#customizing][Customizing]] sections. There is more to the commands introduced in this section and more ways in which you can customize Org-remark. 190 | 191 | ** Highlight and Annotate Websites 192 | 193 | #+cindex: Highlighting websites with EWW 194 | #+findex: org-remark-eww-mode 195 | 196 | ~org-remark-eww-mode~ lets you highlight and annotate websites just like text files. It is a global minor mode. It does not require any additional configuration. All you need is to turn it on, visit a website with ~eww-mode~, and select text and highlight it. Refer to the example of a basic setup given in [[#installation][Installation]]. Org-remark can attempt to automatically adjust the position of highlights when a websites get edited. Learn more about the feature in [[#auto-adjust][What is Automatic Adjustment of Highlight Positions?]] 197 | 198 | ** Highlight and Annotate EPUB Books 199 | 200 | #+cindex: Highlighting EPUB Books with nov.el 201 | #+findex: org-remark-nov-mode 202 | 203 | ~org-remark-nov-mode~ lets you highlight and annotate EPUB books just like text files. It is a global minor mode. It does not require any additional configuration. All you need is to turn it on, open a EPUB book with ~nov-mode~, and select text and highlight it. Refer to the example of a basic setup given in [[#installation][Installation]]. If you read books with tables, it is useful to learn about the feature that automatically adjust the highlight positions: [[#auto-adjust][What is Automatic Adjustment of Highlight Positions?]] 204 | 205 | ** Highlight and Annotate Info documentation in ~Info-mode~ 206 | 207 | #+cindex: Highlighting Info documentation with Info-mode 208 | #+findex: org-remark-info-mode 209 | 210 | ~org-remark-info-mode~ lets you highlight and annotate Info documentation just like text files. It is a global minor mode. It does not require any additional configuration. All you need is to turn it on, open an Info node with ~Info-mode~, and select text and highlight it. Refer to the example of a basic setup given in [[#installation][Installation]]. 211 | 212 | * Usage, Features, Concepts 213 | :PROPERTIES: 214 | :CUSTOM_ID: usage 215 | :END: 216 | 217 | ** How to Create Custom Highlighter Pens 218 | :PROPERTIES: 219 | :CUSTOM_ID: create-custom-pens 220 | :END: 221 | 222 | #+cindex: Custom highlighter pens 223 | #+cindex: Org-remark properties for highlights 224 | #+findex: org-remark-mark 225 | #+findex: org-remark-mark-yellow 226 | #+findex: org-remark-mark-red-line 227 | #+findex: org-remark-create 228 | 229 | ~org-remark-create~ is a macro that lets you create your own custom pen functions. Org-remark comes with two additional pens that are created by default. Use them as examples to learn how to create your own. 230 | 231 | #+begin_src elisp 232 | (org-remark-create "red-line" 233 | '(:underline (:color "dark red" :style wave)) 234 | '(CATEGORY "review" help-echo "Review this")) 235 | (org-remark-create "yellow" 236 | '(:underline "gold" :background "lemon chiffon") 237 | '(CATEGORY "important")) 238 | #+end_src 239 | 240 | - Macro: ~org-remark-create~ label &optional face properties :: 241 | Create and register new highlighter pen functions. The newly created pen function will be registered to variable ~org-remark-available-pens~. It is used by ~org-remark-change~ as a selection list. 242 | 243 | ~LABEL~ is the name of the highlighter and mandatory. The function will be named ~org-remark-mark-LABEL~. 244 | 245 | The highlighter pen function will apply ~FACE~ to the selected region. ~FACE~ can be an anonymous face. When ~FACE~ is nil, this macro uses the default face ~org-remark-highlighter~. 246 | 247 | ~PROPERTIES~ is a plist of pairs of a symbol and value. Each highlighted text region will have a corresponding Org headline in the notes file, and it can have additional properties in the property drawer from the highlighter pen. To do this, prefix property names with "=org-remark-=" or use "=CATEGORY=". 248 | 249 | As of version 1.3, you can use ~org-remark-create~ to create a new line-highlighter pen. Use the ~PROPERTIES~ parameter like the example below to specify ~org-remark-type~ to be ~line~. This tells Org-remark to create a line-highlighter pen function instead of a default range-highlighter one. The ~LABEL~ does not need to include the string "line", but it is recommended for consistency with the default command ~org-remark-mark-line~. 250 | 251 | #+begin_src emacs-lisp 252 | ;; This creates a custom command named org-remark-mark-line-alt with 253 | ;; face diff-hunk-header 254 | (org-remark-create "line-alt" 255 | 'diff-hunk-header 256 | '(org-remark-type line)) 257 | #+end_src 258 | 259 | #+ATTR_TEXINFO: :tag NOTE 260 | #+begin_quote 261 | Don't use =category= (all lowercase, symbol) as a property -- it's a special one for text properties. If you use it, the value also need to be a symbol; otherwise, you will get an error. You can use =CATEGORY= (all uppercase, symbol), which will result in adding =CATEGORY= with the value in the property drawer in marginal notes Org files. 262 | #+end_quote 263 | 264 | ** How to Automatically Turn On Highlights after Re-starting Emacs 265 | 266 | #+findex: org-remark-global-tracking-mode 267 | #+findex: org-remark-mode 268 | 269 | It is recommended that ~org-remark-global-tracking-mode~ be turned on as part of your Emacs initialization. This should be done before you start adding highlights in any file. 270 | 271 | Once you have added highlights to some files, quit Emacs, and re-start it, active ~org-remark-global-tracking-mode~ will automatically turn on ~org-remark-mode~ and load the highlights from your previous sessions for the files being globally tracked. 272 | 273 | Without this global minor mode, you would need to remember to activate ~org-remark-mode~ for each file where you add highlights and annotation. This is often unpractical. 274 | 275 | ** How to Manage Marginal Notes 276 | :PROPERTIES: 277 | :DESCRIPTION: Where Org-remark stores highlights and how to control it 278 | :END: 279 | 280 | *** Marginal Notes File 281 | #+cindex: Marginal notes file 282 | #+cindex: Org-remark properties for highlights 283 | 284 | When you mark a part of text with a highlighter pen function, Org-remark will automatically create a *marginal notes file*. By default, it will be named ~marginalia.org~ and created in the same directory as the file you are editing ([[#change-marginal-notes-filename][How to Change Where Marginal Notes File is Saved]] [[#customizing][;Customizing]], ~org-remark-notes-file-name~). 285 | 286 | The important thing to note is that Org-remark uses following properties in the property drawer of the headline to remember the highlights: 287 | 288 | - :org-remark-beg: 289 | - :org-remark-end: 290 | - :org-remark-id: 291 | - :org-remark-label: 292 | 293 | Essentially, the marginal notes file is a database in the plain text with using Org mode. As a plain text database, you can easily edit these properties manually if necessary. You can directly edit the marginal notes file as a normal Org file. 294 | 295 | The marginal notes file stores highlights and notes like this below; it is designed to organize highlights and notes for multiple files and multiple highlights (You are free to change the default headline titles Org-remark automatically inserts. Refer to section [[#organize-headlines][Organize Headlines in Marginal Notes Buffer in Your Way]]). 296 | 297 | #+begin_src org 298 | ,* File 1 299 | ,** Highlight 1 in File 1 300 | ,** Highlight 2 in File 1 301 | [...] 302 | ,* File 2 303 | ,** Highlight 1 in File 2 304 | [...] 305 | #+end_src 306 | 307 | You can leave the marginal notes file as it is without writing any notes. In this case, the entries in marginal notes file simply save the locations of your highlighted text. After you quit Emacs, re-start it, and visit the same source file, Org-remark uses this information to highlight the text again. 308 | 309 | In addition to the properties above that Org-remark reserves for itself, you can add your own custom properties and ~CATEGORY~ property. Use "org-remark-" as the prefix to the property names (or "CATEGORY", which is the only exception), and Org-remark put them to the property drawer of highlight's headline entry in the marginal notes buffer. Define the custom properties in your own custom pen functions (for how to create your own pens, [[#create-custom-pens][How to Create Custom Highlighter Pens]]). 310 | 311 | *** Organize Headlines in Marginal Notes Buffer in Your Way 312 | :PROPERTIES: 313 | :CUSTOM_ID: organize-headlines 314 | :END: 315 | 316 | #+vindex: org-remark-line-heading-title-max-length 317 | #+vindex: org-remark-line-ellipsis 318 | 319 | When you highlight a range of text or a line, Org-remark creates a corresponding headline in the marginal notes buffer with using Org mode. By default, the headline's title is either the selected text for the range-highlight or the first 40 characters of the line for the line-highlight. For the latter, if the string is longer than the maximum characters, it will be truncated and replaced by an ellipsis "…". Both the 40 character maximum length and the ellipsis can be customized with customizing variables ~org-remark-line-heading-title-max-length~ and ~org-remark-line-ellipsis~ respectively. 320 | 321 | These are only default initial headline titles and you are free to change them as you see fit. For example, you may add a line-highlight to the line where you define a function in an Emacs Lisp script file. The initial title of the corresponding headline in the marginal notes buffer will be something like this below. 322 | 323 | #+begin_example 324 | ,** (defun name-of-the-function (arg)...) 325 | :PROPERTIES:... 326 | I will revisit this function later. 327 | #+end_example 328 | 329 | It may make sense to change this to something like this, especially if you would prefer to organize marginal notes as ~TODO~ items so as to show the headlines in your agenda. 330 | 331 | #+begin_example 332 | ,** TODO review name-of-the-function 333 | :PROPERTIES:... 334 | I will revisit this function later. 335 | #+end_example 336 | 337 | *** =*marginal-notes*= Buffer 338 | #+cindex: *marginal notes* buffer 339 | #+cindex: Echo text / Tool tip on the Highlight 340 | 341 | When you display the marginal notes with ~org-remark-view~ or ~org-remark-open~ for a given highlight, Org-remark creates a cloned indirect buffer visiting the marginal notes file. By default, it is a dedicated side-window opened to the left part of the current frame, and it is named =*marginal notes*=. You can change the behavior of ~display-buffer~ function and the name of the buffer ([[#customizing][Customizing]]). 342 | 343 | Org-remark displays the marginal notes buffer narrowed to the highlight the cursor is on. 344 | 345 | After all the properties, you can freely write your notes for the highlight. Once you save the notes buffer, an excerpt of the text (currently up to 200 characters) gets updated back onto the highlight in the source buffer. You can hover your mouse over the highlight to see the excerpt displayed in the echo area (bottom of the screen) of Emacs. If you have ~tooltip-mode~ mode turned on, the excerpt is displayed as a took tip for the highlight. 346 | 347 | *** How to Change Where Marginal Notes File is Saved 348 | :PROPERTIES: 349 | :CUSTOM_ID: change-marginal-notes-filename 350 | :END: 351 | 352 | #+vindex: org-remark-notes-file-name 353 | 354 | The location of the marginal notes file is specified by user option ~org-remark-notes-file-name~ and its default is "marginalia.org". This means the marginal notes file will reside in the same directory as the source files as a separate file. 355 | 356 | If you use the ~customize~ command to customize ~org-remark-notes-file-name~, you will have an option to choose a =File= or =Function= (customization group ~org-remark~). The default is =File= with the default "marginal.org" as noted above. Use a string to specify the single file name; you can specify a relative path like the default or an absolute path. 357 | 358 | If you would like to dynamically change the location based on the file and various different conditions, select the function as an option. The default function is ~org-remark-notes-file-name-function~. It adds =-notes.org= as a suffix to the source file's name without the extension. For example, for a file named =my-source-file.txt=, Org-remark will store highlights in =my-source-file-notes.org=. You can create your own function and use it. 359 | 360 | Some examples and use cases are listed below: 361 | 362 | - Store Marginal Notes in the Source File :: 363 | In order to use the source file also as the marginal notes file (storing the notes in the source file), you can set the built-in function ~buffer-file-name~ as the value of ~org-remark-notes-file-name~. Note that you will need to ensure that the source files are an Org file. 364 | 365 | - Create a marginal notes file for each source file and store all of them in a specific location :: 366 | Create a custom function that returns an absolute file name per source file, and set ~org-remark-notes-file-name~ to the function name. It might look like this: 367 | 368 | #+begin_src elisp 369 | (defun my/function () 370 | (concat "~/path/to/note-files/" 371 | (file-name-base (org-remark-notes-file-name-function)) 372 | ".org")) 373 | 374 | (setq org-remark-notes-file-name 375 | #'my/function) 376 | #+end_src 377 | 378 | *** How to Use Relative or Absolute File Names for Links in Marginal Notes File 379 | #+cindex: Relative or absolute file names pointing back at source files in marginal notes 380 | #+vindex: org-remark-source-file-name 381 | 382 | The marginal notes file stores the file name pointing back at source files. For example, a marginal notes entry for File1.txt might look like this example below. 383 | 384 | #+begin_src org 385 | ,* File 1 386 | :PROPERTIES: 387 | :org-remark-file: path/to/File1.txt 388 | :END: 389 | ,** Highlight 1 in File 1 390 | :PROPERTIES: 391 | :[...other-properties]: 392 | :org-remark-link: [[file:path/to/File1.txt::14]] 393 | :END: 394 | #+end_src 395 | 396 | The level-1 headline named "File 1" records the file name of the source file =path/to/File1.txt=. Similarly, the level-2 headline named "Highlight 1 in File 1" stores the link pointing back at the source file and the line number of the highlight. 397 | 398 | As you can see, both file names use a relative file name from the marginal notes file. This is the default setting of ~org-remark-source-file-name~. 399 | 400 | You can customize the variable to use absolute file names, or to use a function of your choice. The function is called with a single argument: the absolute file name of source file. The ~default-directory~ is temporarily set to the directory where the marginal notes file resides. If you choose to use relative file names, the relative path is computed from ~default-directory~. 401 | 402 | ** How to Remove and Delete Highlights 403 | #+findex: org-remark-remove 404 | #+findex: org-remark-delete 405 | #+vindex: org-remark-notes-auto-delete 406 | 407 | You can remove the highlight under the cursor with command ~org-remark-remove~. This command does not delete the corresponding entry in the marginal notes file. This is intentional; Org-remark is conservative when it deletes anything that the user might have edited. 408 | 409 | If you wish to delete the entry and the highlight at the same time, pass a universal argument to `org-remark-remove` (e.g. by adding ~C-u~ before ~M-x org-remark-remove~) or use ~org-remark-delete~. ~org-remark-delete~ is identical with adding ~C-u~ to ~org-remark-remove~. 410 | 411 | The delete function will prompt for confirmation if it detects any notes present in the corresponding entry for the highlight in question in the marginal notes buffer. 412 | 413 | #+ATTR_TEXINFO: :tag NOTE 414 | #+begin_quote 415 | Note that you can undo the deletion or removal *in the marginal notes buffer* -- not in the source buffer where you mark text with a highlighter. Technically, highlights are overlays and are therefore not part of the undo tree in the source buffer. 416 | #+end_quote 417 | 418 | As of version 1.3, you can use a new optional feature, automatic deletion. When the feature is enabled, Org-remark will automatically delete the highlight's headline when you delete text that includes a highlight, provided there is no marginal notes for it. If marginal notes are present for the highlight's headline, Org-remark only removes the highlight, deleting the properties from the highlight headline -- same operation as ~org-remark-remove~. Your marginal notes will be kept intact. In either case, Org-remark does not ask for your confirmation. 419 | 420 | You can enable it with the new user option ~org-remark-notes-auto-delete~ like this example below. 421 | 422 | #+begin_src emacs-lisp 423 | (setopt org-remark-notes-auto-delete :auto-delete) 424 | #+end_src 425 | 426 | Furthermore, with v1.3, if you pass a universal argument to ~org-remark-delete~ (e.g. ~C-u M-x org-remark-delete~) you can manually get Org-remark to do automatic deletion for the highlight at point. You can also pass double universal arguments to ~org-remark-remove~ (e.g. ~C-u C-u M-x org-remark-remove~) for the same operation. This should make sense because passing a single universal argument to ~org-remark-remove~ is the same as ~org-remark-delete~. Refer to the documentation of the customizing variable ~org-remark-notes-auto-delete,~ the functions ~org-remark-remove~ and ~org-remark-delete~. 427 | 428 | ** What is Automatic Adjustment of Highlight Positions? 429 | :PROPERTIES: 430 | :CUSTOM_ID: auto-adjust 431 | :END: 432 | #+cindex: Org-remark automatically adjusts positions of highlights 433 | #+vindex: org-remark-icon-position-adjusted 434 | #+vindex: org-remark-highlighter-warning 435 | 436 | Org-remark by default attempts to automatically adjust the position of highlights when they are loaded. This is useful especially for EPUB books read by nov.el. It renders tables in different sizes depending on the available space of the window to maximize their readability. 437 | 438 | This is a good feature for reading; however, it also changes the positions of subsequent text elements depending on the window size when the page is rendered. It can result in dislocating the positions of highlights, different from they are originally created. 439 | 440 | Org-remark attempts to automatically corrects the highlights dislocated. This is a general feature so Org-remark attempts to correct minor edits to websites (for EWW). 441 | 442 | More technically, it works as follows. 443 | 444 | 1. When you create a new highlight, Org-remark records the original text highlighted in the Org property named "~org-remark-original-text~". 445 | 446 | 2. Next time when you open a new file (EPUB book as an example), Org-remark loads the highlights from the notes Org buffer. 447 | 448 | 3. For each highlight, it compares the currently highlighted text with the value of ~org-remark-original-text~ property. 449 | 450 | 4. If they are the same, Org-remark does nothing. 451 | 452 | 5. If different, Org-remark by default looks for the same text string +- two paragraphs. When it finds the *first* matching text string, it automatically moves the highlight to the matched text string. 453 | 454 | 6. Org-remark adds an icon to the auto-adjusted highlight to make it clear that the position of highlight has been adjusted. 455 | 456 | 7. This adjustment is temporary. If you prefer to change the position permanently, you can do so by manually changing the ~org-remark-beg~ and ~org-remark-end~ properties in the notes buffer and save. You can also choose to alter the value of ~org-remark-original-text~ if you have adjusted the range of highlighted text. 457 | 458 | You can customize the icon itself and its face with the following customizing variables: 459 | 460 | - Option: ~org-remark-icon-position-adjusted~ 461 | - Face: ~org-remark-highlighter-warning~ 462 | 463 | ** How to Set Org-remark to Use SVG Icons 464 | :PROPERTIES: 465 | :CUSTOM_ID: icon 466 | :END: 467 | 468 | As of v1.2, highlights can display an icon. With this option, you can customize Org-remark to visually indicate that marginal notes exist for them instead of the default ASCII string "(*)", or to indicate that the Org-remark has automatically adjusted the highlight position (default ASCII string "(d)"; refer to [[#auto-adjust][What is Automatic Adjustment of Highlight Positions?]]). 469 | 470 | There are mainly two ways to set up SVG icons. 471 | 472 | 1. Use the new built-in `icons` library available as of Emacs version 29.1 473 | 2. Create a custom function and use a third-party library such as [[https://github.com/rougier/svg-lib][~svg-lib~]] by Nicolas Rougier 474 | 475 | Below is a quick guide on the first option to use the built-in library 476 | 477 | 1. Get or create an SVG icon 478 | 2. Put the downloaded SVG file somewhere in your local 479 | 3. Use define-icon macro to create an icon with the SVG file 480 | 481 | First, create or download an icon as an ~.svg~ file. For example, [[https://boxicons.com/][Boxicons]] has a collection of SVG icons, which [[https://boxicons.com/usage#license][are provided under The MIT License]]. Second, place the SVG file in your local directory, e.g. ~~/.config/emacs/.cache/svg/bx-pen.svg~. And finally, use ~define-icon~ to define the icon in your configuration like this example below. 482 | 483 | #+begin_src emacs-lisp 484 | (define-icon annotation nil 485 | '((image "~/.config/emacs/.cache/svg/bx-pen.svg" 486 | :height (0.8 . em))) 487 | "Notes svg icon for Org-remark" 488 | :version 29.1) 489 | #+end_src 490 | 491 | Now the icon has been defined, you can set it to customizing variable ~org-remark-icon-notes~ like so: 492 | 493 | #+begin_src emacs-lisp 494 | ;; This example uses `setopt' that is made available as of 29.1. `setq' works too. 495 | (setopt org-remark-icon-notes (icon-string 'annotation)) 496 | #+end_src 497 | 498 | If you have a buffer with highlights already open, use ~revert-buffer~ to reload the highlights. You should see the icon you have defined instead of the default “(*)” string. 499 | 500 | ** Other Commands 501 | #+findex: org-remark-toggle 502 | #+findex: org-remark-change 503 | #+findex: org-remark-next 504 | #+findex: org-remark-prev 505 | 506 | - Command ~org-remark-toggle~ :: 507 | Toggle showing/hiding of highlights in current buffer. 508 | If you would like to hide/show the highlights in the current buffer, it is recommended to use this command instead of ~org-remark-mode~. This command only affects the display of the highlights and their locations are still kept tracked. Toggling off ~org-remark-mode~ stops this tracking completely, which will likely result in inconsistency between the marginal notes file and the current source buffer. 509 | 510 | - Command ~org-remark-change~ :: 511 | Change the highlight at point to one by another pen. This command will show you a list of available pens to choose from. 512 | 513 | To navigate through highlights in the current buffer, you can use ~org-remark-view-next~ / ~org-remark-view-prev~ or the following pair of commands. The former moves your cursor and displays the marginal notes buffer; the latter only moves your cursor. 514 | 515 | - Command ~org-remark-next~ :: 516 | Move to the next highlight, if any. 517 | If there is none below the point but there is a highlight in the buffer, cycle back to the first one. 518 | After the point has moved to the next highlight, this command lets you move further by re-entering only the last letter like this example: =C-n ] ] ] ] ]= (assuming this command is bound to C-n ]) 519 | 520 | - Command ~org-remark-prev~ :: 521 | Move to the previous highlight, if any. 522 | 523 | * Customizing 524 | :PROPERTIES: 525 | :CUSTOM_ID: customizing 526 | :END: 527 | 528 | #+vindex: org-remark-highlighter 529 | #+vindex: org-remark-create-default-pen-set 530 | #+vindex: org-remark-notes-file-name 531 | #+vindex: org-remark-notes-display-buffer-action 532 | #+vindex: org-remark-notes-buffer-name 533 | #+vindex: org-remark-source-file-name 534 | #+vindex: org-remark-use-org-id 535 | #+vindex: org-remark-open-hook 536 | #+vindex: org-remark-icon-notes 537 | #+vindex: org-remark-icon-position-adjusted 538 | #+vindex: org-remark-highlights-after-load-functions 539 | #+vindex: org-remark-highlighter-warning 540 | 541 | Org-remark's user options are available in the customization group ~org-remark~. 542 | 543 | - Face: ~org-remark-highlighter~ :: 544 | Default face for ~org-remark-mark~ 545 | 546 | - Option: ~org-remark-create-default-pen-set~ :: 547 | When non-nil, Org-remark creates default pen set. Set to nil if you prefer for it not to. 548 | 549 | - Option: ~org-remark-notes-file-name~ :: 550 | Name of the file where we store highlights and marginal notes. It can be either a string or function. 551 | If it is a string, it should be a file name to the marginal notes file. The default is =marginalia.org=. The default will result in one marginal notes file per directory. Ensure that it is an Org file. 552 | If it is a function, the default function is ~org-remark-notes-file-name-function~. It returns a file name like this: =FILE-notes.org= by adding =-notes.org= as a suffix to the file name without the extension. 553 | 554 | - Option: ~org-remark-notes-display-buffer-action~ :: 555 | Buffer display action that Org-remark uses to open marginal notes buffer. 556 | 557 | - Option: ~org-remark-notes-buffer-name~ :: 558 | Buffer name of the marginal notes buffer. ~org-remark-open~ and ~org-remark-visit~ create an indirect clone buffer with this name. 559 | 560 | - Option: ~org-remark-source-file-name~ :: 561 | Function that returns the file name to point back at the source file. 562 | The function is called with a single argument: the absolute file name of source file. The =default-directory= is temporarily set to the directory where the marginal notes file resides. 563 | This means that when the =Relative file name= option is selected, the source file name recorded in the marginal notes file will be relative to it. 564 | 565 | - Option: ~org-remark-use-org-id~ :: 566 | When non-nil, Org-remark adds an Org-ID link to marginal notes. The link points at the relevant Org-ID in the source file. Org-remark does not create this ID, which needs to be added manually or some other function to either the headline or file. 567 | 568 | - Option: ~org-remark-icon-notes~ :: 569 | It's the icon used to indicate that a given highlight has its associated notes entry. The default is a combination of ASCII characters to be compatible with terminal and others. If it is preferred, you can set an emoji to it. The author has not experienced well with icon fonts and other means of displaying graphic elements. The face of the icon becomes the same as the highlight, thus it does not have its own face definition. 570 | 571 | By setting it to ~nil~, you can disable the icon altogether. 572 | 573 | ~org-remark-toggle~ also toggles the icon along with the highlight 574 | 575 | - Option: ~org-remark-icon-position-adjusted~ : 576 | It's the icon used to indicate that the position of a given highlight has been automatically adjusted by Org-remark. The default is a combination of ASCII characters to be compatible with terminal and others. If it is preferred, you can set an emoji to it. The author has not experienced well with icon fonts and other means of displaying graphic elements. 577 | 578 | By setting it to ~nil~, you can disable the icon altogether. 579 | 580 | ~org-remark-toggle~ also toggles the icon along with the highlight 581 | 582 | - Face: ~org-remark-highlighter-warning~ :: 583 | This face is used by the icon to indicate that the position of a given highlight has been adjusted. To know more about the feature itself, refer to [[#auto-adjust][What is Automatic Adjustment of Highlight Positions?]]. 584 | 585 | - Option: ~org-remark-open-hook~ :: 586 | Hook run when a note buffer is opened/visited. It gets run with no additional argument but the current buffer will become the note buffer. 587 | 588 | - Option ~org-remark-highlights-after-load-functions~ :: 589 | Abnormal hook run after Org-remark loads the highlights from the note org buffer. It is run with OVERLAYS and NOTES-BUF as arguments. OVERLAYS are highlights. It is run with the source buffer as current buffer. This hook is used by the automatic adjustment feature. To know more about the feature itself, refer to [[#auto-adjust][What is Automatic Adjustment of Highlight Positions?]]. 590 | 591 | 592 | ** Customizing Line Highlights 593 | 594 | #+vindex: org-remark-line-highlighter 595 | #+vindex: org-remark-line-icon 596 | #+vindex: org-remark-line-minimum-margin-width 597 | #+vindex: org-remark-line-margin-padding 598 | #+vindex: org-remark-line-margin-side 599 | #+vindex: org-remark-line-heading-title-max-length 600 | #+vindex: org-remark-line-ellipsis 601 | 602 | These are user options for line highlights available as of v1.3. They are listed in customizing group ~org-remark-line~. 603 | 604 | - Face: ~org-remark-line-highlighter~ :: 605 | Face for the default line highlighter pen. 606 | 607 | - Option: ~org-remark-line-icon~ :: 608 | Glyph displayed on the margin to indicate the line-highlight. You can set an SVG icon to it. Refer to [[#icon][How to Set Org-remark to Use SVG Icons]]. 609 | 610 | - Option: ~org-remark-line-minimum-margin-width~ :: 611 | Margin width in a natural number. It can be a single number or a cons cell of two. When it is a single number, both the left and right margin widths will be the 612 | same. When this customizing variable is a cons cell, the format is as follows: (LEFT-MARGIN-WIDTH . RIGHT-MARGIN-WIDTH). 613 | 614 | - Option: ~org-remark-line-margin-padding~ :: 615 | Padding between the main text area the glyph/icon on the margin. 616 | 617 | - Option: ~org-remark-line-margin-side~ :: 618 | The side of margin to display line highlights. 619 | Left or Right can be chosen. 620 | 621 | - Option: ~org-remark-line-heading-title-max-length~ :: 622 | Maximum length of string included as the highlight title. 623 | 624 | - Option ~org-remark-line-ellipsis~ :: 625 | Ellipsis used when the highlight title is longer than maximum. 626 | The maximum is set in ~org-remark-line-heading-title-max-length~. 627 | 628 | * Known Limitations 629 | 630 | - No export together with the source file :: There is no out-of-the-box feature to export marginal notes together with the source file. Nevertheless, the marginal notes is a normal Org file, thus if the source file is also an Org file, you could use the built-in =include= feature, for example, to include relevant parts of the marginal notes into the export output. 631 | 632 | - Copy & pasting loses highlights :: Overlays are not part of the kill; thus cannot be yanked. 633 | 634 | - Undo highlight does not undo it :: Overlays are not part of the undo list; you cannot undo highlighting. Use ~org-remark-remove~ or ~org-remark-delete~ commands instead. 635 | 636 | - Moving source files and marginal notes files :: Moving your files and remark file to another directory does not update the source paths and file names stored in the marginal notes file. One way to keep the links between the source files and marginal notes files is to use relative file names with ~org-remark-source-file-name~ (default). 637 | 638 | - With ~org-remark-eww-mode~ highlights can get displaced :: This happens when the website is edited and its content changes outside Emacs -- of course this is normal for websites. Currently there is no way to fix the location of highlights. 639 | 640 | * Credits 641 | 642 | To create this package, I was inspired by the following packages. I did not copy any part of them, but borrowed some ideas from them -- e.g. saving the margin notes in a separate file. 643 | 644 | - [[https://github.com/jkitchin/ov-highlight][Ov-highlight]] :: John Kitchin's (author of Org-ref). Great UX for markers with hydra. Saves the marker info and comments directly within the Org file as Base64 encoded string. It uses overlays with using ~ov~ package. 645 | 646 | - [[https://github.com/bastibe/annotate.el][Annotate.el]] :: Bastian Bechtold's (author of Org-journal). Unique display of annotations right next to (or on top of) the text. It seems to be designed for very short annotations, and perhaps for code review (programming practice); I have seen recent issues reported when used with variable-pitch fonts (prose). 647 | 648 | - [[https://github.com/tkf/org-mode/blob/master/contrib/lisp/org-annotate-file.el][Org-annotate-file]] :: Part of Org's contrib library. It seems to be designed to annotate a whole file in a separate Org file, rather than specific text items. 649 | 650 | - [[https://github.com/IdoMagal/ipa.el][InPlaceAnnotations (ipa-mode)]] :: It looks similar to Annotate.el above. 651 | 652 | - Transient navigation feature :: To implement the transient navigation feature, I liberally copied the relevant code from a wonderful Emacs package, [[https://github.com/rnkn/binder/blob/24d55db236fea2b405d4bdc69b4c33d0f066059c/binder.el#L658-L665][Binder]] by Paul W. Rankin (GitHub user [[https://github.com/rnkn][rnkn]]). 653 | 654 | * Contributing & Feedback 655 | 656 | Create issues, discussion, and/or pull requests in the GitHub repository. All welcome. 657 | 658 | Org-remark is planned to be submitted to GNU ELPA and thus copyrighted by the [[http://fsf.org][Free Software Foundation]] (FSF). This means that anyone who is making a substantive code contribution will need to "assign the copyright for your contributions to the FSF so that they can be included in GNU Emacs" ([[https://orgmode.org/contribute.html#copyright][Org Mode website]]). 659 | 660 | Thank you. 661 | 662 | * Index - Features 663 | :PROPERTIES: 664 | :CUSTOM_ID: cindex 665 | :APPENDIX: t 666 | :INDEX: cp 667 | :DESCRIPTION: Key concepts & features 668 | :END: 669 | 670 | * Index - Commands 671 | :PROPERTIES: 672 | :APPENDIX: t 673 | :INDEX: fn 674 | :DESCRIPTION: Interactive functions 675 | :END: 676 | 677 | * Index - User Options 678 | :PROPERTIES: 679 | :APPENDIX: t 680 | :INDEX: vr 681 | :DESCRIPTION: Customizable variables & faces 682 | :END: 683 | 684 | * GNU Free Documentation License 685 | :PROPERTIES: 686 | :appendix: t 687 | :END: 688 | 689 | #+texinfo: @include fdl.texi 690 | 691 | # Local Variables: 692 | # time-stamp-start: "modified +\\\\?" 693 | # End: 694 | --------------------------------------------------------------------------------