[elpa] externals/org-remark eedfeb4fa6: docs: Update user manual

[ELPA Syncer]

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

    docs: Update user manual
---
 demo/marginalia.org |  9 +++++++++
 docs/org-remark.org | 44 ++++++++++++++++++++++++++++++++++----------
 org-remark.el       |  4 ++--
 3 files changed, 45 insertions(+), 12 deletions(-)

diff --git a/demo/marginalia.org b/demo/marginalia.org
index 4b13b2cc84..0d7b2093c2 100644
--- a/demo/marginalia.org
+++ b/demo/marginalia.org
@@ -116,3 +116,12 @@ Annotation for the 19th centry.
 :CATEGORY: exam
 :org-remark-link: [[file:~/src/org-remark/demo/demo.txt::10]]
 :END:
+
+** international
+:PROPERTIES:
+:org-remark-beg: 264
+:org-remark-end: 251
+:org-remark-id: 7a312b27
+:org-remark-label: nil
+:org-remark-link: [[file:demo.txt::14]]
+:END:
diff --git a/docs/org-remark.org b/docs/org-remark.org
index d7570b1b90..df21cfe264 100644
--- a/docs/org-remark.org
+++ b/docs/org-remark.org
@@ -206,19 +206,19 @@ The important thing to note is that Org-remark uses 
following properties in the
 
 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.
 
-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. 
+The marginal notes file stores highlights and notes like this below; it is 
designed to organize highlights anpd notes for multiple files and multiple 
highlights.
 
 #+begin_src org
-,* File 1
-,** Highlight 1 in File 1
-,** Highlight 2 in File 1
-    [...]
-,* File 2
-,** Highlight 1 in File 2
-    [...]
+  ,* File 1
+  ,** Highlight 1 in File 1
+  ,** Highlight 2 in File 1
+  [...]
+  ,* File 2
+  ,** Highlight 1 in File 2
+  [...]
 #+end_src
 
-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 main 
file, Org-remark uses this information to highlight the text again. 
+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 main 
file, Org-remark uses this information to highlight the text again.
 
 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 [...]
 
@@ -238,6 +238,30 @@ 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
+#+cindex: Relative or absolute file names pointing back at source files in 
marginal notes
+#+vindex: org-remark-source-file-name
+
+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.
+
+#+begin_src org
+  ,* File 1
+  :PROPERTIES:
+  :org-remark-file: path/to/File1.txt
+  :END:
+  ,** Highlight 1 in File 1
+  :PROPERTIES:
+  :[...other-properties]:
+  :org-remark-link: [[file:path/to/File1.txt::14]]
+  :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.
+
+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~.
+
+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~.
+
 ** How to Remove and Delete Highlights
 #+findex: org-remark-remove
 #+findex: org-remark-delete
@@ -289,7 +313,7 @@ To navigate through highlights in the current buffer, you 
can use ~org-remark-vi
 
 #+vindex: org-remark-highlighter
 #+vindex: org-remark-create-default-pen-set
-#+vindex: org-remark-notes-file-path
+#+vindex: org-remark-notes-file-name
 #+vindex: org-remark-notes-display-buffer-action
 #+vindex: org-remark-notes-buffer-name
 #+vindex: org-remark-use-org-id
diff --git a/org-remark.el b/org-remark.el
index 9aec19f49e..28254b10be 100644
--- a/org-remark.el
+++ b/org-remark.el
@@ -4,7 +4,7 @@
 
 ;; Author: Noboru Ota <me@nobiot.com>
 ;; URL: https://github.com/nobiot/org-remark
-;; Version: 1.0.0
+;; Version: 1.0.1
 ;; Created: 22 December 2020
 ;; Last modified: 12 February 2022
 ;; Package-Requires: ((emacs "27.1") (org "9.4"))
@@ -88,7 +88,7 @@ buffer with this name."
  'org-remark-source-path-function 'org-remark-source-file-name "0.2.0")
 
 (defcustom org-remark-source-file-name #'file-relative-name
-  "Function that return the file name to point back at the source file.
+  "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