[elpa] externals/org-remark cdcab9e294 73/75: docs: v1.3

[ELPA Syncer]

branch: externals/org-remark
commit cdcab9e294174e1b77ea56c71e847e5734bf8f70
Author: Noboru Ota <me@nobiot.com>
Commit: Noboru Ota <me@nobiot.com>

    docs: v1.3
---
 README-elpa         |   6 +-
 README.org          |   2 +-
 docs/org-remark.org | 192 ++++++++++++++++++++++++++++++++++++++++++++++------
 org-remark-line.el  |  55 +++++++++------
 org-remark.el       |  25 ++++---
 5 files changed, 223 insertions(+), 57 deletions(-)

diff --git a/README-elpa b/README-elpa
index 9a639b7ec5..a86998ea22 100644
--- a/README-elpa
+++ b/README-elpa
@@ -37,7 +37,8 @@ _________________
   For customization, refer to the customization group `org-remark' or
   user manual: [online] or Info node `(org-remark) Customizing'. A
   [separate online article] has been written to guide you on how to
-  customize an icon (to be incorporated into the user manual later).
+  customize an icon (also part of the user manual. Evaluate (info
+  "(or-gremark) How to Set Org-remark to Use SVG Icons").
 
   An [introductory video] (8 minutes) and [V1.1.0 release introduction]
   (12 minutes) are available on YouTube.
@@ -91,8 +92,7 @@ _________________
   This package is available on:
 
   - [GNU-ELPA] (releases only; equivalent to MELPA-Stable)
-  - [GNU-devel ELPA] (unreleased development branch; equivalent to
-    MELPA)
+  - [GNU-devel ELPA] (unreleased main branch; equivalent to MELPA)
 
   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'
diff --git a/README.org b/README.org
index 0ee9bb0f36..f3e69bc3c5 100644
--- a/README.org
+++ b/README.org
@@ -20,7 +20,7 @@ For installation and minimum configuration, refer to 
[[#installation][Installati
 
 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'.
 
-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 (to 
be incorporated into the user manual later).
+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").
 
 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.
 
diff --git a/docs/org-remark.org b/docs/org-remark.org
index 7c8bb15f90..0b1110b5ca 100644
--- a/docs/org-remark.org
+++ b/docs/org-remark.org
@@ -1,7 +1,7 @@
 #+title: Org-remark User Manual
 #+author: Noboru Ota <me@nobiot.com>
-#+macro: version 1.2.x
-#+macro: modified 20 August 2023
+#+macro: version 1.3.x
+#+macro: modified 06 October 2023
 #+language: en
 #+export_file_name: org-remark.texi
 #+texinfo_dir_category: Emacs
@@ -10,11 +10,11 @@
 #+texinfo: @paragraphindent asis
 #+options: toc:nil ':t
 
-This manual is for Org-remark version {{{version}}}. Some new features are 
mentioned in this manual that are currently in development; these are mentioned 
clearly as such.
+This manual is for Org-remark version {{{version}}}. The new features 
introduced with version {{{version}}} are currently only avaiable 
[[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]].
 
 Last updated: {{{modified}}}.
 
-Org-remark lets you highlight and annotate text files and websites (EWW).
+Org-remark lets you highlight and annotate text files, websites (EWW), EPUB 
books (nov.el) and Info documentation (Info-mode).
 
 #+texinfo: @insertcopying
 
@@ -23,7 +23,7 @@ Org-remark lets you highlight and annotate text files and 
websites (EWW).
 :COPYING: t
 :END:
 
-Copyright \copy 2021-2022  Free Software Foundation, Inc.
+Copyright \copy 2021-2023  Free Software Foundation, Inc.
 
 #+begin_quote
 Permission is granted to copy, distribute and/or modify this document
@@ -45,7 +45,7 @@ modify this GNU manual.”
 This package is available on:
 
 - [[https://elpa.gnu.org/packages/org-remark.html][GNU-ELPA]] (releases only; 
equivalent to MELPA-Stable)
-- [[https://elpa.gnu.org/devel/org-remark.html][GNU-devel ELPA]] (unreleased 
development branch; equivalent to MELPA)
+- [[https://elpa.gnu.org/devel/org-remark.html][GNU-devel ELPA]] (unreleased 
main branch; equivalent to MELPA)
 
 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:
 
@@ -54,6 +54,8 @@ GNU ELPA should be already set up in your Emacs by default. 
If you wish to add G
                '("gnu-devel" . "https://elpa.gnu.org/devel/";) :append)
 #+END_SRC
 
+** Basic Setup
+
 After installation, we suggest you put the setup below in your configuration.
 
 #+name: basic-setup
@@ -94,6 +96,35 @@ Below are example keybindings you might like to consider:
     (define-key org-remark-mode-map (kbd "C-c n d") #'org-remark-delete))
 #+end_src
 
+** Setup with ~use-pacakge~
+
+Alternatively, you can use ~use-package~ to set up Org-remark. The example 
provided below should be equivalent to the setup described above.
+
+#+name: setup-with-use-package
+#+begin_src emacs-lisp
+  (use-package org-remark
+    :bind (;; :bind keyword also implicitly defers org-remark itself.
+           ;; Keybindings before :map is set for global-map.
+           ("C-c n m" . org-remark-mark)
+           :map org-remark-mode-map
+           ("C-c n o" . org-remark-open)
+           ("C-c n ]" . org-remark-view-next)
+           ("C-c n [" . org-remark-view-prev)
+           ("C-c n r" . org-remark-remove)
+           ("C-c n d" . org-remark-delete))
+    ;; Alternative way to enable `org-remark-global-tracking-mode' in
+    ;; `after-init-hook'.
+    ;; :hook (after-init . org-remark-global-tracking-mode)
+    :init
+    ;; It is recommended that `org-remark-global-tracking-mode' be
+    ;; enabled when Emacs initializes. Alternatively, you can put it to
+    ;; `:after-init-hook' to load it after Emacs has been initialized.
+    (org-remark-global-tracking-mode +1)
+    (use-package org-remark-info :after info :config (org-remark-info-mode +1))
+    (use-package org-remark-eww  :after eww  :config (org-remark-eww-mode +1))
+    (use-package org-remark-nov  :after nov  :config (org-remark-nov-mode +1)))
+#+end_src
+
 * Getting Started
 :PROPERTIES:
 :CUSTOM_ID: getting-started
@@ -102,15 +133,22 @@ Below are example keybindings you might like to consider:
 ** Highlighting and Annotating
 
 #+findex: org-remark-mark
+#+findex: org-remark-mark-line
 #+findex: org-remark-open
 #+findex: org-remark-view
 #+cindex: Marginal notes file
+#+cindex: line-highlight
+#+cindex: range-highlight
+#+vindex: org-remark-line-margin-side
+#+vindex: org-remark-notes-display-buffer-action
 
-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.
+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 [...]
 
 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.
 
-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 display a new buffer to the left of the current 
buffer you are editing. The ~open~ command takes the cursor to the marginal 
notes buffer for you to edit notes; whereas 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 entr [...]
+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~).
+
+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.
 
 ** Navigating from One Highlight to Another
 
@@ -138,6 +176,7 @@ The ~C-c n~ part is the prefix key common to all of them. 
If you set the keybind
 Org-remark has a default highlighter pen function, and comes with a set of two 
additional pens by default:
 
 - ~org-remark-mark~        :: default highlighter pen
+- ~org-remark-mark-line~ :: default line-highlighter pen, which adds a mark on 
the margin instead of a range of text
 - ~org-remark-mark-yellow~    :: yellow highlight with "important" category in 
the marginal notes entry
 - ~org-remark-mark-red-line~   :: wavy red underline with "review" category in 
the marginal notes entry and "Review this" in tool-tips
 
@@ -197,11 +236,20 @@ This is all you need to get started. For more detail, 
refer to the rest of this
 - Macro: ~org-remark-create~ label &optional face properties ::
   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.
 
-  LABEL is the name of the highlighter and mandatory.  The function will be 
named ~org-remark-mark-LABEL~.
+  ~LABEL~ is the name of the highlighter and mandatory.  The function will be 
named ~org-remark-mark-LABEL~.
+
+  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~.
 
-  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~.
+  ~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=".
 
-  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=".
+As of version 1.3, you can use ~org-remark-create~ to create a new 
line-highlighter pen. Use the ~PROPERTIES~ parameter like this example below to 
specify ~org-remark-type~ to be ~line~. This tells Org-remark that the 
highlighter pen function creates a line-highlight instead of a default 
range-highlight. The ~LABEL~ does not need to include "line" in it, but it is 
recommended for consistency with the default command ~org-remark-mark-line~.
+
+#+begin_src emacs-lisp
+  ;; This creates a custom command named org-remark-line-alt.
+  (org-remark-create "line-alt"
+                   'diff-hunk-header
+                   '(org-remark-type line))
+#+end_src
 
 #+ATTR_TEXINFO: :tag NOTE
 #+begin_quote
@@ -225,7 +273,6 @@ Without this global minor mode, you would need to remember 
to activate ~org-rema
 :END:
 
 *** Marginal Notes File
-
 #+cindex: Marginal notes file
 #+cindex: Org-remark properties for highlights
 
@@ -256,8 +303,29 @@ You can leave the marginal notes file as it is without 
writing any notes. In thi
 
 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 Highligh [...]
 
-*** =*marginal-notes*= Buffer
+*** Organize Headlines in Marginal Notes Buffer in Your Way
+#+vindex: org-remark-line-heading-title-max-length
+#+vindex: org-remark-line-ellipsis
 
+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 (longer line will be 
truncated and replaced by an ellipsis "…" -- both the 40 character limit and 
the ellipsis string can be customized with customizing variables 
~org-remark-line-heading-title-max-length~ and ~org-remark-line-e [...]
+
+These are only default initial headline titles -- you are free to change them 
as you see fit. For example, you may add a line-highlight to an Elisp script 
file on the line you define a function. The initial title of the corresponding 
headline in the marginal notes buffer will be something like this below.
+
+#+begin_example
+,** (defun name-of-the-function (arg)...)
+ :PROPERTIES:...
+ I will revisit this function later.
+#+end_example
+
+It may make sense to change this to something like this, especially if you 
would rather organize these as ~TODO~ items so as to appear in your agenda.
+
+#+begin_example
+,** TODO review fun name-of-the-function
+ :PROPERTIES:...
+ I will revisit this function later.
+#+end_example
+
+*** =*marginal-notes*= Buffer
 #+cindex: *marginal notes* buffer
 #+cindex: Echo text / Tool tip on the Highlight
 
@@ -325,22 +393,28 @@ You can customize the variable to use absolute file 
names, or to use a function
 ** How to Remove and Delete Highlights
 #+findex: org-remark-remove
 #+findex: org-remark-delete
+#+vindex: org-remark-notes-auto-delete
 
-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-roam is conservative when it 
deletes anything that the user might have edited.
+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-roam is conservative when it 
deletes anything that the user might have edited.
 
 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~.
 
 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.
 
-- Command ~org-remark-remove~ ::
-  Remove the highlight at point.
-  It will remove the highlight and the properties from the marginal notes 
file, but will keep the headline and annotations. This is to ensure to keep any 
notes you might have written intact.
-  You can let this command DELETE the entire heading subtree for the highlight 
along with the annotations you have written, by passing a universal argument 
with ~C-u~. If you have done so by error, you could still ~undo~ it in the 
marginal notes buffer, but not from within the current buffer as adding and 
removing overlays are not part of the undo tree.
+#+ATTR_TEXINFO: :tag NOTE
+#+begin_quote
+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.
+#+end_quote
+
+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.  [...]
+
+You can enable it with the new user option ~org-remark-notes-auto-delete~ like 
this example below.
+
+#+begin_src emacs-lisp
+  (setopt org-remark-notes-auto-delete :auto-delete)
+#+end_src
 
-- Command ~org-remark-delete~ ::
-  Delete the highlight at POINT and marginal notes for it.
-  This function will prompt for confirmation if there is any notes present in 
the marginal notes buffer.  When the marginal notes buffer is not displayed in 
the current frame, it will be temporarily displayed together with the prompt 
for the user to see the notes.
-  If there is no notes, this function will not prompt for confirmation and 
will remove the highlight and deletes the entry in the marginal notes buffer. 
This command is identical with passing a universal argument to 
`org-remark-remove'.
+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  [...]
 
 ** What is Automatic Adjustment of Highlight Positions?
 :PROPERTIES:
@@ -377,6 +451,43 @@ You can customize the icon itself and its face with the 
following customizing va
 - Option: ~org-remark-icon-position-adjusted~
 - Face: ~org-remark-highlighter-warning~
 
+** How to Set Org-remark to Use SVG Icons
+:PROPERTIES:
+:CUSTOM_ID: icon
+:END:
+
+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-roam has 
automatically adjusted the highlight position (default ASCII string "(d)"; 
refer to [[#auto-adjust][What is Automatic Adjustment of Highlight 
Positions?]]).
+
+There are mainly two ways to set up SVG icons.
+
+1. Use the new built-in `icons` library available as of Emacs version 29.1
+2. Create a custom function and use a third-party library such as 
[[https://github.com/rougier/svg-lib][~svg-lib~]] by Nicolas Rougier
+
+Below is a quick guide on the first option to use the built-in library
+
+1. Get or create an SVG icon
+2. Put the downloaded SVG file somewhere in your local
+3. Use define-icon macro to create an icon with the SVG file
+
+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.
+
+#+begin_src emacs-lisp
+  (define-icon annotation nil
+  '((image "~/.config/emacs/.cache/svg/bx-pen.svg"
+           :height (0.8 . em)))
+  "Notes svg icon for Org-remark"
+  :version 29.1)
+#+end_src
+
+Now the icon has been defined, you can set it to customizing variable 
~org-remark-icon-notes~  like so:
+
+#+begin_src emacs-lisp
+  ;; This example uses `setopt' that is made available as of 29.1. `setq' 
works too.
+  (setopt org-remark-icon-notes (icon-string 'annotation))
+#+end_src
+
+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.
+
 ** Other Commands
 #+findex: org-remark-toggle
 #+findex: org-remark-change
@@ -468,6 +579,43 @@ Org-remark's user options are available in the 
customization group ~org-remark~.
 - Option ~org-remark-highlights-after-load-functions~ ::
   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?]].
 
+
+** Customizing Line Highlights
+
+#+vindex: org-remark-line-highlighter
+#+vindex: org-remark-line-icon
+#+vindex: org-remark-line-minimum-margin-width
+#+vindex: org-remark-line-margin-padding
+#+vindex: org-remark-line-margin-side
+#+vindex: org-remark-line-heading-title-max-length
+#+vindex: org-remark-line-ellipsis
+
+These are user options for line highlights available as of v1.3. They are 
listed in customizing group ~org-remark-line~.
+
+- Face: ~org-remark-line-highlighter~ ::
+  Face for the default line highlighter pen.
+
+- Option: ~org-remark-line-icon~ ::
+  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]].
+
+- Option: ~org-remark-line-minimum-margin-width~ ::
+  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
+same. When this customizing variable is a cons cell, the format is as follows: 
(LEFT-MARGIN-WIDTH . RIGHT-MARGIN-WIDTH).
+
+- Option: ~org-remark-line-margin-padding~ ::
+  Padding between the main text area the glyph/icon on the margin.
+
+- Option: ~org-remark-line-margin-side~ ::
+  The side of margin to display line highlights.
+Left or Right can be chosen.
+
+- Option: ~org-remark-line-heading-title-max-length~ ::
+  Maximum length of string included as the highlight title.
+
+- Option ~org-remark-line-ellipsis~ ::
+  Ellipsis used when the highlight title is longer than maximum.
+The maximum is set in ~org-remark-line-heading-title-max-length~.
+
 * Known Limitations
 
 - 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.
diff --git a/org-remark-line.el b/org-remark-line.el
index 9a01af7c88..c8b4661f03 100644
--- a/org-remark-line.el
+++ b/org-remark-line.el
@@ -5,7 +5,7 @@
 ;; Author: Noboru Ota <me@nobiot.com>
 ;; URL: https://github.com/nobiot/org-remark
 ;; Created: 01 August 2023
-;; Last modified: 30 September 2023
+;; Last modified: 05 October 2023
 ;; Package-Requires: ((emacs "27.1") (org "9.4"))
 ;; Keywords: org-mode, annotation, note-taking, marginal-notes, wp
 
@@ -31,7 +31,7 @@
 (require 'org-remark)
 
 (defgroup org-remark-line nil
-  "Enable`org-remark' to highlight and annotate whole lines. "
+  "Enable`org-remark' to highlight and annotate whole lines."
   :group 'org-remark
   :prefix "org-remark-line"
   :link '(url-link :tag "GitHub" "https://github.com/nobiot/org-remark";))
@@ -62,13 +62,13 @@ is as follows: (LEFT-MARGIN-WIDTH . RIGHT-MARGIN-WIDTH)."
           (cons :tag "Left and right margin widths" natnum natnum)))
 
 (defcustom org-remark-line-margin-padding 1
-  "Padding between the main text area the glyph/icon on the margin"
+  "Padding between the main text area the glyph/icon on the margin."
   :local t
   :type 'natnum)
 
 (defcustom org-remark-line-margin-side 'left-margin
   "The side of margin to display line highlights.
-Left or rigth can be chosen."
+Left or right can be chosen."
   :local t
   :type '(radio
           (const :tag "Left margin" left-margin)
@@ -94,10 +94,10 @@ The maximum is set in 
`org-remark-line-heading-title-max-length'."
   "Face for the default line highlighter pen.")
 
 (defvar-local org-remark-line-minimum-left-margin-width nil
-  "Computed minimum left-margin width.")
+  "Computed minimum `left-margin' width.")
 
 (defvar-local org-remark-line-minimum-right-margin-width nil
-  "Computed minimum right-margin width.")
+  "Computed minimum `right-margin' width.")
 
 (defvar-local org-remark-line-margins-original '()
   "Original window margin width values.
@@ -151,8 +151,9 @@ in cons cell (or nil) before function
 ;; Default line-highlighter pen
 
 ;;;###autoload
-(defun org-remark-mark-line (&args _)
-  "Dummy function definition to let autoload work.
+(defun org-remark-mark-line (_beg _end &optional _id _mode)
+  "Apply face to the region selected by BEG and END.
+Dummy function definition to let autoload work.
 The actual implementation is added when this library is loaded
 and macro `org-remark-create' creates the actual function.")
 
@@ -161,9 +162,9 @@ and macro `org-remark-create' creates the actual function.")
                    `(org-remark-type line))
 
 (defun org-remark-line-set-window-margins (&optional window)
-  "Set the margins of current window that displays current buffer.
+  "Set the margins of WINDOW or window that displays current buffer.
 Return a cons of the form (LEFT-WIDTH . RIGHT-WIDTH). If a
-marginal area does not exist, its width will be returned as nil."
+marginal area does not exist, return nil."
   (let ((window (or window (get-buffer-window))))
     (when (and (windowp window) (not (window-minibuffer-p window)))
       (cl-destructuring-bind (left-width . right-width) (window-margins)
@@ -228,11 +229,12 @@ This happens only when HIGHLIGHT is a line-highlight."
           (number-to-string (org-current-line (overlay-start highlight))))))
 
 (cl-defmethod org-remark-beg-end ((_org-remark-type (eql 'line)))
+  "Return beg and end for ORG-REMARK-TYPE line."
     (let ((bol (org-remark-line-pos-bol (point))))
       (list bol bol)))
 
 (defun org-remark-line-make-spacer-overlay (pos)
-  "Return a spacer overlay."
+  "Return a spacer overlay at POS."
   (let* ((left-margin (or (car (window-margins)) left-margin-width))
          ;;(right-margin (or (cdr (window-margins)) right-margin-width))
          (string-length (length org-remark-line-icon))
@@ -255,7 +257,8 @@ This happens only when HIGHLIGHT is a line-highlight."
     spacer-ov))
 
 (defun org-remark-line-highlights-redraw (&optional window)
-  "Redraw line-highlights to adjust the spaces/padding."
+  "Redraw line-highlights to adjust the spaces/padding.
+When WINDOW is nil, this function gets window that current buffer is 
displayed."
   (let ((window (or window (get-buffer-window))))
     (when (and (windowp window) (not (window-minibuffer-p window)))
       (org-with-wide-buffer
@@ -276,6 +279,7 @@ This happens only when HIGHLIGHT is a line-highlight."
              (org-remark-highlights-sort))))))))
 
 (defun org-remark-line-highlight-propertize (ov icon-string)
+  "Propertize ICON-STRING and add it to OV."
   ;; If the icon-string has a display properties, assume it is an icon image
   (let ((display-prop (get-text-property 0 'display icon-string)))
     (cond (display-prop ; svg-based icon
@@ -299,8 +303,10 @@ This happens only when HIGHLIGHT is a line-highlight."
           (t (ignore)))))
 
 (cl-defmethod org-remark-highlight-make-overlay (beg end face 
(_org-remark-type (eql 'line)))
-  "Make and return a highlight overlay for line-highlight.
-Return nil when no window is created for current buffer."
+  "Make and return a highlight overlay in BEG END for line-highlight.
+This function adds FACE to line icon string. If FACE is nil, this
+function uses default `org-remark-line-highlighter'. Return nil
+when no window is created for current buffer."
   (when (get-buffer-window)
     (unless org-remark-line-mode (org-remark-line-mode +1))
     (let* ((face (or face 'org-remark-line-highlighter))
@@ -328,7 +334,14 @@ Return nil when no window is created for current buffer."
                 highlights)))
 
 (defun org-remark-line-highlight-modified (ov after-p beg _end &optional 
_length)
-  "Move the overlay to follow the point when ENTER in the line."
+  "Move spacers and lighlight OV to follow the point.
+Without this function, the line-highlighter mark does not move
+when the user press RET to add a newline at the beginning of the
+line-highlight. This is unintuitive for the user.
+
+This function is meant to be added to insert-in-front-hooks of
+the overlay that represents line-highlight. It must be called
+AFTER-P is non-nil and move BEG to one position forward."
   (when after-p
     (save-excursion (goto-char beg)
                     (when (looking-at "\n")
@@ -341,7 +354,7 @@ Return nil when no window is created for current buffer."
                           (move-overlay (pop spacers) (1+ beg) (1+ beg))))))))
 
 (cl-defmethod org-remark-highlight-headline-text (ov (_org-remark-type (eql 
'line)))
-  "Return the first N characters of the highlighted line.
+  "Return the first N characters of the highlighted line OV.
 N is customized with `org-remark-line-heading-title-max-length'.
 If the line starts with any space or tab, they will be trimmed.
 If the line (after trimming) is shorter than N, then this
@@ -365,7 +378,7 @@ loading highlights)."
                 org-remark-line-ellipsis)))))
 
 (cl-defmethod org-remark-highlights-adjust-positions-p ((_org-remark-type (eql 
'line)))
-  "
+  "Return t if adjust-positions feature is relevant.
 For line-highlights, adjust-positions is not relevant."
   nil)
 
@@ -389,14 +402,14 @@ end of overlay being identical."
         (move-overlay ov ov-line-bol ov-line-bol)))))
 
 (cl-defmethod org-remark-icon-overlay-put (ov icon-string (_org-remark-type 
(eql 'line)))
-  "Add icons to OV.
-  Each overlay is a highlight.
-Return nil when no window is created for current buffer."
+  "Add ICON-STRING to OV.
+Each overlay is a highlight. Return nil when no window is created
+for current buffer."
   (when (get-buffer-window)
     (org-remark-line-highlight-propertize ov icon-string)))
 
 (cl-defmethod org-remark-icon-highlight-get-face (highlight (_org-remark-type 
(eql 'line)))
-  "Return the face of the line-highilght in a margin."
+  "Return the face of HIGHLIGHT in margin for line-highlight."
   (let* ((before-string (overlay-get highlight 'before-string))
          (face (get-text-property 0 'face before-string)))
     ;; When the highlight already is an SVG icon, face is in the display
diff --git a/org-remark.el b/org-remark.el
index 53c682fb40..4f02700215 100644
--- a/org-remark.el
+++ b/org-remark.el
@@ -6,7 +6,7 @@
 ;; URL: https://github.com/nobiot/org-remark
 ;; Version: 1.2.1
 ;; Created: 22 December 2020
-;; Last modified: 09 September 2023
+;; Last modified: 05 October 2023
 ;; Package-Requires: ((emacs "27.1") (org "9.4"))
 ;; Keywords: org-mode, annotation, note-taking, marginal-notes, wp,
 
@@ -108,8 +108,8 @@ you can set this customizing variable to 
\\=':auto-delete\\='.
 With this option, Org-remark will delete the entire entry when it
 contains no notes without a prompt asking for confirmation. This
 is the same behavior as passing a single `universal-argument'
-(\\[universal-argument]) to`org-remark-delete' or double `universal-argument'
-(\\[universal-argument] \\[universal-argument]) to `org-remark-remove'."
+\(\\[universal-argument]) to`org-remark-delete' or double `universal-argument'
+\(\\[universal-argument] \\[universal-argument]) to `org-remark-remove'."
   :type '(radio
           (const :tag "Keep entries (default)" nil)
           (const :tag "Delete entries automatically when no notes exist"
@@ -912,13 +912,14 @@ Optionally ID can be passed to find the exact ID match."
 ;;   buffer.
 
 (cl-defgeneric org-remark-highlight-make-overlay (_beg _end _face 
_org-remark-type)
-  "Make overlay and return it
+  "Make overlay and return it.
 Put FACE and other necessary properties to the highlight OV"
   (ignore))
 
 (cl-defmethod org-remark-highlight-make-overlay (beg end face
                                                      (_org-remark-type (eql 
nil)))
-  "Put FACE and other necessary properties to the highlight OV.
+  "Make overlay BEG END and add FACE to it.
+If FACE is nil, this function uses defaul face `org-remark-highlighter'.
 This is a method for highlights of default ORG-REMARK-TYPE, that
 is for a character range."
   (let ((ov (make-overlay beg end nil :front-advance)))
@@ -1157,10 +1158,12 @@ buffer for automatic sync."
     ;;; Return notes-props
     notes-props))
 
-(cl-defgeneric org-remark-highlight-headline-text (_ov _org-remark-type))
+(cl-defgeneric org-remark-highlight-headline-text (_ov _org-remark-type)
+  "Return title text of highlight.")
 
 (cl-defmethod org-remark-highlight-headline-text (ov (_org-remark-type (eql 
nil)))
-  "Assume it is called within `org-with-wide-buffer' of the source."
+  "Return title text of highlight OV of default type.
+Assume it is called within `org-with-wide-buffer' of the source."
   (replace-regexp-in-string
    "\n" " "
    (buffer-substring-no-properties (overlay-start ov) (overlay-end ov))))
@@ -1172,7 +1175,7 @@ that represents the current highlight being worked on. The
 function is run with source buffer as the current buffer.")
 
 (defun org-remark-highlight-collect-other-props (highlight)
-  "
+  "Return other properties for HIGHLIGHT.
 Assume to be run in the source buffer."
   (let ((props nil))
     (dolist (fn org-remark-highlight-other-props-functions props)
@@ -1635,7 +1638,7 @@ highlight is a property list in the following properties:
            highlights))))))
 
 (defun org-remark-highlights-delay-load (window)
-  "Delay load until window for current buffer is created."
+  "Delay load until WINDOW for current buffer is created."
   (when (windowp window)
     (remove-hook 'window-state-change-functions
                  #'org-remark-highlights-delay-load 'local)
@@ -1841,6 +1844,7 @@ The current buffer is source buffer."
   t)
 
 (cl-defgeneric org-remark-highlights-housekeep-per-type (_ov _org-remark-type)
+  "Housekeep highlights per type."
   (ignore))
 
 (defun org-remark-highlights-adjust-positions (overlays _notes-buf)
@@ -1868,7 +1872,7 @@ extensions."
          ov highlight-text)))))
 
 (cl-defgeneric org-remark-highlights-adjust-positions-p (_org-remark-type)
-  "Return t if adjust-positions feature is relevant
+  "Return t if adjust-positions feature is relevant.
 Default is t and evaluated per ORG-REMARK-TYPE."
   t)
 
@@ -1889,6 +1893,7 @@ If FILENAME is nil, return nil."
       (funcall org-remark-source-file-name filename))))
 
 (cl-defgeneric org-remark-beg-end (_org-remark-type)
+  "Return beg and end for default ORG-REMARK-TYPE."
   (org-remark-region-or-word))
 
 (defun org-remark-region-or-word ()