[elpa] externals/org-remark 6562bb0c89: docs: update user manual and doc strings

[ELPA Syncer]

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

    docs: update user manual and doc strings
---
 NEWS                          |  6 ++++++
 docs/org-remark.org           | 49 ++++++++++++++++++++-----------------------
 org-remark-global-tracking.el |  7 ++++---
 org-remark.el                 |  6 +++---
 4 files changed, 36 insertions(+), 32 deletions(-)

diff --git a/NEWS b/NEWS
index 256c198551..9059f3bcc0 100644
--- a/NEWS
+++ b/NEWS
@@ -1,3 +1,9 @@
+Current version
+  - Update user manual and doc strings in source
+
+Version 1.0.1
+  - Update user manual
+
 Version 1.0.0
   - chg: align with GNU convention: path -> file name
 
diff --git a/docs/org-remark.org b/docs/org-remark.org
index df21cfe264..d6a24287d1 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.0.x
-#+macro: modified 12 February 2022
+#+macro: modified 13 February 2022
 #+language: en
 #+export_file_name: org-remark.texi
 #+texinfo_dir_category: Emacs
@@ -115,7 +115,7 @@ To make navigation easy, you can use define the same 
"prefix key" to Org-remark
 - ~C-c n r~: ~org-remark-remove~
 - ~C-c n d~: ~org-remark-delete~
 
-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, or ~r~/~d~ to remove/delete it.
+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.
 
 ** Create Your Own Highlighter Pens
 
@@ -123,11 +123,11 @@ 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~        :: default highlighter pen
 - ~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
+- ~org-remark-mark-red-line~   :: wavy red underline with "review" category in 
the marginal notes entry and "Review this" in tool-tips
 
-Org-remark let 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]].
+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]].
 
 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.
 
@@ -177,7 +177,6 @@ Don't use =category= (all lowercase, symbol) as a property 
-- it's a special one
 
 #+findex: org-remark-global-tracking-mode
 #+findex: org-remark-mode
-#+vindex: org-remark-tracking-file
 
 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.
 
@@ -238,7 +237,7 @@ The location of the marginal notes file is specified by 
user option ~org-remark-
 
 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.
 
-*** How to Use Relative or Absolute Path for Links in Marginal Notes File
+*** How to Use Relative or Absolute File Names for Links in Marginal Notes File
 #+cindex: Relative or absolute file names pointing back at source files in 
marginal notes
 #+vindex: org-remark-source-file-name
 
@@ -256,7 +255,7 @@ The marginal notes file stores the file name pointing back 
at source files. For
   :END:
 #+end_src
 
-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 a the source file and the line number of 
the highlight.
+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.
 
 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~.
 
@@ -316,8 +315,8 @@ To navigate through highlights in the current buffer, you 
can use ~org-remark-vi
 #+vindex: org-remark-notes-file-name
 #+vindex: org-remark-notes-display-buffer-action
 #+vindex: org-remark-notes-buffer-name
+#+vindex: org-remark-source-file-name
 #+vindex: org-remark-use-org-id
-#+vindex: org-remark-tracking-file
 
 Org-remark's user options are available in the customization group 
~org-remark~.
 
@@ -327,25 +326,25 @@ Org-remark's user options are available in the 
customization group ~org-remark~.
 - Option: ~org-remark-create-default-pen-set~ ::
   When non-nil, Org-remark creates default pen set. Set to nil if you prefer 
for it not to.
 
-- Option: ~org-remark-notes-file-path~ ::
-  Define the file path to store the location of highlights and write 
annotations.
-  The default is one file per directory. Ensure that it is an Org file.
+- Option: ~org-remark-notes-file-name~ ::
+  Name of the file where we store highlights and marginal notes. It can be 
either a string or function.
+  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.
+  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.
 
 - Option: ~org-remark-notes-display-buffer-action~ ::
-  Define how Org-remark opens the notes buffer.
-  The default is to use a dedicated side-window on the left. It is an action 
list for ~display-buffer~. Refer to its documentation for more detail and 
expected elements of the list.
+  Buffer display action that Org-remark uses to open marginal notes buffer.
 
 - Option: ~org-remark-notes-buffer-name~ ::
-  Define the buffer name of the marginal notes.
-  ~org-remark-open~ creates an indirect clone buffer with this name.
+  Buffer name of the marginal notes buffer. ~org-remark-open~ and 
~org-remark-visit~ create an indirect clone buffer with this name.
 
-- Option: ~org-remark-use-org-id~ ::
-  Define if Org-remark use Org-ID to link back to the main note.
+- Option: ~org-remark-source-file-name~ ::
+  Function that returns the file name to point back at the source file.
+  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.
+  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.
 
-- Option: ~org-remark-tracking-file~ ::
-  Define file path to save the files ~org-remark~ tracks.
-  When ~org-remark-global-tracking-mode~ is active, opening a file saved in
- ~org-remark-tracking-file~ automatically loads highlights.
+- Option: ~org-remark-use-org-id~ ::
+  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.
 
 * Known Limitations
 
@@ -353,11 +352,9 @@ Org-remark's user options are available in the 
customization group ~org-remark~.
 
 - Copy & pasting loses highlights :: Overlays are not part of the kill; thus 
cannot be yanked.
 
-- Undo highlight does not undo it :: Overlays are not part of the undo list; 
you cannot undo highlighting. Use ~org-remark-remove~ command instead.
-
-- Moving source files and remark file :: Move your files and remark file to 
another directory does not update the source path recorded in the remark file. 
It will be confusing. Try not to do it.
+- 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.
 
-- Marginal notes file uses absolute path :: Related to the previous 
limitation. The marginal notes file serves as the database for the highlights' 
locations and notes. The linkage back to the main note files are via absolute 
paths.  This means moving files to a different path is likely to break the the 
links.
+- Moving source files and remark file :: 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).
 
 * Credits
 
diff --git a/org-remark-global-tracking.el b/org-remark-global-tracking.el
index 34dbf28d64..c9d5d212ee 100644
--- a/org-remark-global-tracking.el
+++ b/org-remark-global-tracking.el
@@ -5,7 +5,7 @@
 ;; Author: Noboru Ota <me@nobiot.com>
 ;; URL: https://github.com/nobiot/org-remark
 ;; Created: 15 August 2021
-;; Last modified: 05 February 2022
+;; Last modified: 13 February 2022
 ;; Package-Requires: ((emacs "27.1") (org "9.4"))
 ;; Keywords: org-mode, annotation, writing, note-taking, marginal notes
 
@@ -41,8 +41,9 @@
 It can be either a string or function.
 
 If it is a string, it should be a file name to the marginal notes
-file.  The default is \"marginalia.org\".  It will be one marginal
-notes file per directory.  Ensure that it is an Org file.
+file.  The default is \"marginalia.org\".  The default will
+result in one marginal notes file per directory.  Ensure that it
+is an Org file.
 
 If it is a function, the default function is
 `org-remark-notes-file-name-function'.  It returns a file name
diff --git a/org-remark.el b/org-remark.el
index 28254b10be..179bbc4c48 100644
--- a/org-remark.el
+++ b/org-remark.el
@@ -6,7 +6,7 @@
 ;; URL: https://github.com/nobiot/org-remark
 ;; Version: 1.0.1
 ;; Created: 22 December 2020
-;; Last modified: 12 February 2022
+;; Last modified: 13 February 2022
 ;; Package-Requires: ((emacs "27.1") (org "9.4"))
 ;; Keywords: org-mode, annotation, writing, note-taking, marginal-notes
 
@@ -104,8 +104,8 @@ file will be relative to it."
 
 (defcustom org-remark-use-org-id nil
   "When non-nil, Org-remark adds an Org-ID link to marginal notes.
-The link point at the relevant Org-ID in the source file .
-Org-remark does not create an ID, which needs to be added
+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."
   :type 'boolean)