[elpa] externals/org-remark f713a3846b: docs: User manual to mention marginal notes saved in the same file

[ELPA Syncer]

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

    docs: User manual to mention marginal notes saved in the same file
---
 docs/org-remark.org | 65 ++++++++++++++++++++++++++++++++++++-----------------
 1 file changed, 45 insertions(+), 20 deletions(-)

diff --git a/docs/org-remark.org b/docs/org-remark.org
index d31ce7902a..1f6426daa7 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 0.2.x
-#+macro: modified 31 January 2022
+#+macro: modified 05 February 2022
 #+language: en
 #+export_file_name: org-remark.texi
 #+texinfo_dir_category: Emacs
@@ -173,7 +173,7 @@ This is all you need to get started. For more detail, refer 
to the rest of this
 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.
 #+end_quote
 
-** Automatically Turn on Highlights after Re-starting Emacs
+** How to Automatically Turn On Highlights after Re-starting Emacs
 
 #+findex: org-remark-global-tracking-mode
 #+findex: org-remark-mode
@@ -183,11 +183,14 @@ It is recommended that ~org-remark-global-tracking-mode~ 
be turned on as part of
 
 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.
 
-When activated, ~org-remark-global-tracking-mode~ will also start remembering 
and tracking the files to which you add highlights and annotations. When you 
quit Emacs, it will save the tracked files in a file in your Emacs config 
directory (~user-emacs-directory~). By default, this file is named 
~.org-remark-tracking~ ([[#customizing][Customizing]]).
-
 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.
 
-** Marginal Notes File
+** How to Manage Marginal Notes
+:PROPERTIES:
+:DESCRIPTION: Where Org-remark stores highlights and how to control it
+:END:
+
+*** Marginal Notes File
 
 #+cindex: Marginal notes file
 #+cindex: Org-remark properties for highlights
@@ -201,13 +204,25 @@ The important thing to note is that Org-remark uses 
following properties in the
 - :org-remark-id:
 - :org-remark-label:
 
-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.
+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.
 
-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 
also 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. 
+
+#+begin_src org
+,* 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. 
 
 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
+*** =*marginal-notes*= Buffer
 
 #+cindex: *marginal notes* buffer
 
@@ -215,21 +230,17 @@ When you display the marginal notes with 
~org-remark-view~ or ~org-remark-open~
 
 Org-remark displays the marginal notes buffer narrowed to the highlight the 
cursor is on.
 
-** Other Commands
+*** How to Store Marginal Notes in the Source File
 
-#+findex: org-remark-toggle
-#+findex: org-remark-change
-#+findex: org-remark-remove
-#+findex: org-remark-delete
-#+findex: org-remark-next
-#+findex: org-remark-prev
+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.
 
-- Command ~org-remark-toggle~ ::
-  Toggle showing/hiding of highlights in current buffer.
-  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 main buffer.
+~org-remark-notes-file-name~ also takes a function as a value, so you have a 
wide range of customizability. In ~customize~, the default function to be used 
is ~org-remark-notes-file-name-function~, which adds =-notes.org= as a suffix 
to the source file's name without the extension. For example, for 
=my-main-file.txt= Org-remark will create and store highlights in  
=my-main-file-notes.org=.
 
-- Command ~org-remark-change~ ::
-  Change the highlight at point to one by another pen. This command will show 
you a list of available pens to choose from.
+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 Remove and Delete Highlights
+#+findex: org-remark-remove
+#+findex: org-remark-delete
 
 - Command ~org-remark-remove~ ::
   Remove the highlight at point.
@@ -241,6 +252,20 @@ Org-remark displays the marginal notes buffer narrowed to 
the highlight the curs
   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'.
 
+** Other Commands
+
+#+findex: org-remark-toggle
+#+findex: org-remark-change
+#+findex: org-remark-next
+#+findex: org-remark-prev
+
+- Command ~org-remark-toggle~ ::
+  Toggle showing/hiding of highlights in current buffer.
+  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 main buffer.
+
+- Command ~org-remark-change~ ::
+  Change the highlight at point to one by another pen. This command will show 
you a list of available pens to choose from.
+
 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.
 
 - Command ~org-remark-next~ ::