[elpa] externals/org-remark 0c7fd2d711 143/173: docs: README for Org-remark, update user manual and css

[ELPA Syncer]

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

    docs: README for Org-remark, update user manual and css
---
 README.org                 | 321 +++++++--------------------------------------
 docs/org-remark-manual.org |  74 ++++++-----
 docs/resources/manual.css  |   1 +
 3 files changed, 90 insertions(+), 306 deletions(-)

diff --git a/README.org b/README.org
index 4b8e6b86d2..61009a906a 100644
--- a/README.org
+++ b/README.org
@@ -1,314 +1,95 @@
 [[file:https://img.shields.io/badge/License-GPLv3-blue.svg]]
 
-#+TITLE: Org-remark
+#+title: README: Org-remark
 
-#+PROPERTY: LOGGING nil
-
-# Note: I use the readme template that alphapapa shares on his GitHub repo 
<https://github.com/alphapapa/emacs-package-dev-handbook#template>. It works 
with the org-make-toc <https://github.com/alphapapa/org-make-toc> package, 
which automatically updates the table of contents.
-
-<<<<<<< HEAD
 * ❦❦❦ IMPORTANT NOTICE ❦❦❦
 
-[This notice written on 3 January 2022]
+[This notice written on 18 January 2022]
 
 Happy 2022!
 
-I am finalizing the the name of the package and GitHub repo. See 
[[https://github.com/nobiot/org-marginalia/pull/10][PR #10]]. It's probably 
going to be "*Org-remark*". The =dev/name-change= branch contains all the 
changes pertaining to the name change along some additional features -- most 
notably, different highlighter pen colors and capability to let you create 
different pens (an idea borrowed from John Kitchin's 
[[https://github.com/jkitchin/ov-highlight][Ov-highlight]]).
+I have changed the name of the project and package to "*Org-remark*" from 
Org-marginalia. 
 
-There will be some minor breaking changes, which I am going through right now 
in my own machine. I will document the ways to bridge the breakages; nothing 
really major and I'm also trying to make the new version as backward compatible 
as possible from my lessons learnt.
+If you are using Org-marginalia now, there are breaking changes. This package 
includes the feature that automatically converts the old Org-marginalia data 
into the new Org-remark data. Add ~org-remark-convert-legacy~ feature like this:
 
-After the change, I will propose the package to be added to ELPA.
+#+begin_src elisp
+  (require 'org-remark-convert-legacy)
+#+end_src
 
-I would appreciate any feedback or comment via 
[[https://github.com/nobiot/org-marginalia/pull/10][PR #10]], Org-roam 
discourse, or direct email (probably not Slack or Reddit as I'm really not 
present on these media).
+This feature is designed to work automatically and transparently to you, 
meaning you should not have to do anything, as long as you did not customize 
~org-marginala-notes-file-path~. If you did, you also need to customize 
~org-remark-notes-file-path~. You can also manually do data conversion if you 
wish. For more detail, refer to the docstring of function 
~org-remark-convert-legacy-data~. 
 
 * Intorduction
 
-Org-marginalia lets you highlight text, and write margin notes (marginalia) 
for any text file in a separate Org file. 
+Org-remark lets you highlight and annotate any text file with using Org mode.
+
+A complete [[https://nobiot.github.io/org-remark/][user manual]] is available 
online (Info file will be added when Org-remark is added to ELPA/MELPA).
+
+For installation and minimum configuration, refer to 
[[#installation][Installation]] below or the corresponding section in the user 
manual.
+
+[[https://nobiot.github.io/org-remark/#getting-started][Getting Started]] in 
the user manual will get you started in 5 minutes.
 
 [[./resources/images/2020-12-24T101116_Title.png]]
-*Figure 1*. Left: Org-mode with text enlarged; Right marginalia file with the 
inline image display on
+*Figure 1*. Left: Org-mode with text enlarged; Right marginal notes with the 
inline image display on
 
 * Screenshots
 
 Refer to the screenshots below for a teaser of  what it can do.
 
+#+begin_quote
+The screen shots are from the old Org-marginalia. They are still relevant but 
new screen shots are on their way.
+#+end_quote
+
 [[./resources/images/2020-12-22T141331-OM-screen-shot-01.png]]
-*Figure 2*. Left: main note with some text highlighted in green; Right: margin 
notes in a marginalia file
+*Figure 2*. Left: main note with some text highlighted in green; Right: 
marginal notes in a marginalia file
 
 [[./resources/images/2021-08-17T220032.png]]
-*Figure 3*. Left: =org-roam-buffer= showing backlinks from the marginal notes; 
Right: main Org note. Org-marinalia can automatically add links with Org-ID 
from marginal notes back to the main file. This works well with Org-roam's 
backlink (V2)
+*Figure 3*. Left: ~org-roam-buffer~ showing backlinks from the marginal notes; 
Right: main Org note. Org-remark can automatically add links with Org-ID from 
marginal notes back to the main file. This works well with Org-roam's backlinks
 
 [[./resources/images/2020-12-22T141331-OM-screen-shot-03.png]]
-*Figure 4*. Main note can be any text files. Left: an ~.el~ file with a 
highlight; Right: marginalia file
-
-* News
-
-** New Features
-
-- Auto-activation of Org-marginalia Mode when Opening Files with Marginal 
Notes ::
-  A new global minor mode =org-marginalia-global-tracking-mode= has been 
introduced as of 0.0.6. It saves and tracks files that have marginal notes. 
When it is active, visiting a file being tracked automatically turns on 
=org-marginalia-mode=, loading highlights previously saved in the marginalia 
file.
-  The files being tracked are saved in =org-marginalia-tracking-file=, which 
you can customize. The default file is named =.org-marginalia-tracking= in your 
Emacs configuration directory (=user-emacs-directory=).
-
-- Support for Org ID and Org-roam ::
-  This is only applicable when the main source note is an Org file.
-  As of 0.0.6, seamless workflow with Org-roam has been added by generating ID 
links automatically.
-  If user option =org-marginalia-use-org-id= is non-nil (default) and Org ID 
is available in the main note, Org-marginalia will create a link back to the 
source note with using an Org-ID link instead of a normal file link.
-  Org-marginalia looks at property inheritance for ID properties. When the 
immediate headline where a highlight belongs does not have an ID, the ID of a 
higher headline or file property is used when available. When none is 
available, Org-marginalia falls back to a normal file link.
-  When a new marginalia file is created and =org-marginalia-use-org-id= is
-non-nil, Org-marginalia will add an ID property to the file level. This is 
mainly to support Org-roam's backlink feature for marginalia files.
-
-** Removing limitations
-
-- Use of Overlays, no longer Text-Properties ::
-  This makes easier to add a highlighter overlay on top of text regions that 
already have faces (e.g. syntax-highlighted part of source code).
-
-- Now turning off minor mode will turn off the highlights ::
-  It is still recommended to use =org-marginalia-toggle= to temporarily 
hide/show highlights. This is because turning off =org-marginalia-mode= will 
stop tracking of the locations of highlights in the current buffer. **Any** 
(however minor) change will likely result in mismatching the locations of saved 
highlights and the current buffer's text content.
-
-* Contents                                                         :noexport:
-:PROPERTIES:
-:TOC:      :include siblings
-:END:
-:CONTENTS:
-- [[#installation][Installation]]
-- [[#usage][Usage]]
-- [[#customizing][Customizing]]
-- [[#known-limitations][Known Limitations]]
-- [[#changelog][Changelog]]
-- [[#credits][Credits]]
-- [[#feedback][Feedback]]
-- [[#license][License]]
-- [[#local-variables][Local Variables]]
-- [[#org-remark][org-remark]]
-  - [[#defun][defun]]
-:END:
+*Figure 4*. Main note can be any text files. Left: an ~.el~ file with a 
highlight; Right: marginal notes file
 
 * Installation
 :PROPERTIES:
-:TOC:      :depth 0
+:CUSTOM_ID: installation
 :END:
-** Manual
-This package is not available on MELPA. Manual installation is required.
-
-Ensure to have Org Mode 9.4 or later (tested on 9.4.2). This package uses 
~org-collect-keywords~, which does not exist in an earlier version.
-
-Store both of the =.el= files in the repo in your load-path, and put this in 
your init file:
-
-#+BEGIN_SRC emacs-lisp
-  (add-to-list 'load-path "~/local-repos/org-marginalia/")
-  (require 'org-marginalia-global-tracking)
-  (require 'org-marginalia)
-#+END_SRC
-
-By loading =org-marginalia=, it will also pull in Org mode. You might like to 
defer loading of Org as it might take long time. As of version 0.0.6, you can 
do so with loading only =org-marginalia-global-tracking=, which does not load 
=org= automatically.
-
-For example, I use this in my init file. 
-
-#+begin_src emacs-lisp
-  ;; Set `load-path'
-  (add-to-list 'load-path "~/local-repos/org-marginalia")
-
-  ;; Load only `org-marginalia-global-tracking'
-  ;; and turn it on for automatic loading of highlights
-  ;; for the files tracked
-  (load-library "org-marginalia-global-tracking")
-  (org-marginalia-global-tracking-mode 1)
-
-  ;; Set keybindings `org-marginalia-mark' is bound to global-map so that you 
can
-  ;; call it globally before the library is loaded.  In order to make
-  ;; `org-marginalia-mark' and `org-marginalia-mode' callable, use `autoload'.
-  ;; When this package is available in MELPA, `autoload' should not be 
required.
-  (autoload #'org-marginalia-mark "org-marginalia" nil t)
-  (autoload #'org-marginalia-mode "org-marginalia" nil t)
-  (define-key global-map (kbd "C-c m") #'org-marginalia-mark)
-  ;; The rest of keybidings are done only on loading `org-marginalia'
-  (with-eval-after-load 'org-marginalia
-    (define-key org-marginalia-mode-map (kbd "C-c n o") #'org-marginalia-open)
-    (define-key org-marginalia-mode-map (kbd "C-c n ]") #'org-marginalia-next)
-    (define-key org-marginalia-mode-map (kbd "C-c n [") #'org-marginalia-prev)
-    (define-key org-marginalia-mode-map (kbd "C-c n r") 
#'org-marginalia-remove))
-#+end_src
-  
-* Usage
-:PROPERTIES:
-:TOC:      :depth 0
-:END:
-** Commands
-
-- =org-marginalia-global-tracking-mode= ::
-A global minor mode to save and track files that have marginal notes.
-When active, visiting a file being tracked automatically turns on 
=org-marginalia-mode=, which loads highlights previously saved in the 
marginalia file.
-
-The files being tracked are saved in =org-marginalia-tracking-file=, which you 
can customize. The default file is named =.org-marginalia-tracking= in your 
Emacs configuration directory (=user-emacs-directory=).
-
-- =org-marginalia-mode= ::
-Org-marginalia is a local minor mode. Toggle it on/off with using 
=org-marginalia-mode=. On activating, it loads your saved highlights from the 
marginalia file (defined by =org-marginalia-notes-file-path=), and enables 
automatic saving of highlights. The automatic saving is achieved via function 
=org-marginalia-save= added to =after-save-hook=.
-
-- =org-marginalia-mark= ::
-Select a region of text, and call =org-marginalia-mark= to highlight the 
region. It will generate a new ID, and start tracking the location -- so you 
can edit text around the highlighted text. Do not cut, copy and paste as the 
highlight will disappear (you can immediately =undo= to recover the text region 
along the highlights). To create a new marginal note entry in the marginalia 
file, save the buffer.
-
-- =org-marginalia-save= ::
-By default, Org-marginalia automatically creates or updates corresponding 
entries in the marginalia file with location and text of highlights on saving 
the buffer. Nevertheless, you can manually call =org-marginalia-save= to do so 
(automatic process also call this command).
 
-If user option =org-marginalia-use-org-id= is non-nil, Org-marginalia will
-create a link back to the source note with using an Org-ID link instead of a
-normal file link.
+This package is not available on ELPA or MELPA yet. Manual installation is 
required.
 
-When a new marginalia file is created and =org-marginalia-use-org-id= is
-non-nil, Org-marginalia will add an ID property to the file level. This is 
mainly to support Org-roam's backlink feature for marginalia files.
-
-- =org-marginalia-open= ::
-Move your cursor on the highlighted text, and call =org-marginalia-open= to 
open the relevant margin notes in a separate window. Your cursor will move to 
the marginalia buffer narrowed to the relevant margin notes entry. You can edit 
the marginalia buffer as a normal Org buffer. Once you have done editing, you 
may simply save and close the it (kill it or close the window) as per your 
normal workflow. Technically, the marginalia buffer is a cloned indirect buffer 
of the marginalia file. 
-
-- =org-marginalia-load= ::
-This command visits the marginalia file and loads the saved highlights onto 
the current buffer. If there is no margin notes for it, it will output a 
message in the echo. Highlights tracked locally by Org-marginalia cannot 
persist when you kill the buffer, or quit Emacs. When you re-launch Emacs, 
ensure to turn on =org-marginalia-mode= to load the highlights. Loading is 
automatically done when you activate the minor mode.
-
-- =org-marginalia-remove= ::
-This command removes the highlight at point. It will remove the highlight, and 
remove the properties from the marginalia, but will keep the headline and notes 
in tact.
-
-You can pass a universal argument (=C-u= by default). If this is the case, the 
command additionally deletes the entire heading subtree, along with the notes 
you have written, for the highlight.
-
-- =org-marginalia-next= ::
-Move to the next highlight if any. If there is none below the cursor, and 
there is a highlight above, loop back to the top one.
-If the point has moved to the next highlight, this function enables transient 
map with `set-transient-map'. You don't have to press the keybinding prefix 
again to move further to the next. That is, you can do a key sequence like this:
-
-   =C-c n ] ] ] ]=
-
-If you have the same prefix for `org-marginalia-prev', you can combine it in
-the sequence like so:
-
-  =C-c n ] ] [ [=
-  This lets your cursor back to where you started (next next prev prev)
-
-- =org-marginalia-prev= ::
-Move to the previous highlight if any. If there is none above the cursor, and 
there is a highlight below, loop back to the bottom one. This function enables 
transient map. See =org-marginalia-next= for detail.
-
-- =org-marginalia-toggle= ::
-Toggle showing/hiding of highlighters in current buffer. It only affects the 
display of the highlighters. When hidden, highlights' locations are still kept 
tracked; thus, upon buffer-save the correct locations are still recorded in the 
marginalia file.
-
-** Keybindings Examples
+Ensure to have Org Mode 9.4 or later (tested on 9.4.2). This package uses 
~org-collect-keywords~, which does not exist in an earlier version.
 
-`Org-marginalia` only provides its mode map, and does not bind any keys to it. 
As an example, you coud do something like this below.
+Store all the =.el= files in the repo in your load-path and put this in your
+init file:
 
 #+begin_src emacs-lisp
-(define-key org-marginalia-mode-map (kbd "C-c n o") #'org-marginalia-open)
-(define-key org-marginalia-mode-map (kbd "C-c m") #'org-marginalia-mark)
-(define-key org-marginalia-mode-map (kbd "C-c n ]") #'org-marginalia-next)
-(define-key org-marginalia-mode-map (kbd "C-c n [") #'org-marginalia-prev)
+  ;; Set `load-path' , load `org-remark-global-tracking', and turn it on for
+  ;; automatic loading of highlights for the files tracked
+  (add-to-list 'load-path "~/local-repos/org-remark")
+  (require 'org-remark-global-tracking)
+  (org-remark-global-tracking-mode +1)
 #+end_src
 
-** Composing Personal Workflow
-
-Currently only "elementary" functions are defined in the package; for example, 
 =mark= , =save=, and =open= are all separate functions. You can string these 
together to compose a more fluid operation to suite your own workflow. A very 
useful set of such chained commands have been suggesetd by holtzermann17 in 
[[https://org-roam.discourse.group/t/prototype-org-marginalia-write-margin-notes-with-org-mode/1080/10][Org-roam's
 Discourse discussion]] (adjusted to reflect the change of the pref [...]
+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. By autoloading some commands in similar ways as the example 
keybindings below, you can control the timing of loading =org-remark=. 
 
-I will try to incorporate these into the package when I have more time to 
focus on it -- I find them useful, but there are some plans I have had, and 
want to think of how I can incoprate these suggestions better with my ideas. 
+Below are example keybindings you might like to consider:
 
 #+begin_src emacs-lisp
-  (defun org-marginalia-make-annotation ()
-    (interactive)
-    (let ((mark-end (region-end)))
-      (org-marginalia-mark (region-beginning) (region-end))
-      (org-marginalia-save)
-      (org-marginalia-open (1- mark-end))
-      (end-of-buffer)))
-
-  (define-key org-marginalia-mode-map (kbd "C-c M")
-    #'org-marginalia-make-annotation)
-
-  (defun org-marginalia-browse-forward ()
-    (interactive)
-    (let ((buf (current-buffer)))
-      (org-marginalia-next) (org-marginalia-open (point))
-      (pop-to-buffer buf nil t)))
-
-  (define-key org-marginalia-mode-map (kbd "C-c n }")
-    #'org-marginalia-browse-forward)
-
-  (defun org-marginalia-browse-backward ()
-    (interactive)
-    (let ((buf (current-buffer)))
-      (org-marginalia-prev) (org-marginalia-open (point))
-      (pop-to-buffer buf nil t)))
-
-  (define-key org-marginalia-mode-map (kbd "C-c n {")
-    #'org-marginalia-browse-backward)
+  ;; Key-bind `org-remark-mark' to global-map so that you can call it globally
+  ;; before the library is loaded.  In order to make `org-remark-mark' and
+  ;; `org-remark-mode' callable, use `autoload'.
+  (autoload #'org-remark-mark "org-remark" nil t)
+  (autoload #'org-remark-mode "org-remark" nil t)
+  (define-key global-map (kbd "C-c n m") #'org-remark-mark)
+
+  ;; The rest of keybidings are done only on loading `org-remark'
+  (with-eval-after-load 'org-remark
+    (define-key org-remark-mode-map (kbd "C-c n o") #'org-remark-open)
+    (define-key org-remark-mode-map (kbd "C-c n ]") #'org-remark-view-next)
+    (define-key org-remark-mode-map (kbd "C-c n [") #'org-remark-view-prev)
+    (define-key org-remark-mode-map (kbd "C-c n r") #'org-remark-remove))
 #+end_src
 
-* Customizing
-
-- You can customize settings in the =org-marginalia= group.
-- Highlight's face can be changed via =org-marginalia-highlighter=
-- Marginalia file is defined by =org-marginalia-notes-file-path=
-- Your files with marginal notes are saved and tracked in
-  =org-marginalia-tracking-file= (when tracking is turned on via the global
-  minor mode =org-marginalia-global-tracking-mode=)
-- You can use Org-ID to create links from marginal notes back to their main
-  notes when =org-marginalia-use-org-id= is on (default is on). This option 
also enables Org-marginalia to add an ID property when a new marginalia file is 
being created. This is to support seamless workflow with 
[[https://orgroam.com][Org-roam]].
-
-* Known Limitations
-
-- 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-marginalia-remove= command instead.
-  
-- Moving source files and marginalia file :: Move your files and marginalia 
file to another directory does not update the source path recorded in the 
marginalia file. It will be confusing. Try not to do this.
-
-* Changelog
-:PROPERTIES:
-:TOC:      :depth 0
-:END:
-
-** 0.0.6
-
-Feature:
-- feat: Add =org-marginalia-global-tracking-mode= with a separate .el file
-- feat: Use Org-ID to create a link from the marginal notes back to the main 
file
-  Add Customizable variable =org-marginalia-use-org-id=; default is =t=
-
-Change:
-- chg: Highlights are now overlay; no longer text-properties
-  
-Improvement to existing functions
-- add: Deactivate mark after highlighting
-- add: org-marginalia-remove can take C-u to delete
-
-Fix & Internal Refactor
-- intrnl: Add housekeeping for =org-marginalia-highlights= variable
-- fix: org-id-uuid is not found
-- fix: Add highlighter face def for terminal
-
-** 0.0.5
-- break: Replace the prefix "om/" in the source code with "org-marginalia"
-- break: Remove default keybindings; add examples in readme instead. Addresses 
[#3](https://github.com/nobiot/org-marginalia/issues/3)
-
-** 0.0.4
-- feat: Add transient navigation to next/prev
-  See [[*Credits][§ Credits]] for the piece of code to achieve the transient 
map I used.
-
-** 0.0.3
-- feat: Add om/toggle for show/hide highlighters
-
-** 0.0.2
-- feat: Add om/next and /prev
-- break: Change om/open-at-point to org-marginalia-open
-- break: Change om/save-all to org-marginalia-save
-
-** 0.0.1
-Initial alpha release. I consider it to be the minimal viable scope. 
-
-* Credits
-
-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.
-
-- [[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.
-  
-- [[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).
-  
-- 
[[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.
-  
-- [[https://github.com/IdoMagal/ipa.el][InPlaceAnnotations (ipa-mode)]] :: It 
looks similar to Annotate.el above.
-  
-- 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]]). 
+* Contributing
+To be added
 
 * Feedback
 
@@ -336,8 +117,6 @@ This work is licensed under a GPLv3 license. For a full 
copy of the licese, refe
 # line-spacing: 4
 # End:
 
-
-
 * org-remark
 :PROPERTIES:
 :org-remark-file: ~/src/org-remark/org-remark.el
diff --git a/docs/org-remark-manual.org b/docs/org-remark-manual.org
index 896f79e756..a7b08c5491 100644
--- a/docs/org-remark-manual.org
+++ b/docs/org-remark-manual.org
@@ -1,7 +1,7 @@
 #+title: Org-remark User Manual
 #+author: Noboru Ota <me@nobiot.com>
-#+macro: version 1.0.x
-#+macro: modified 17 January 2022
+#+macro: version 0.1.x
+#+macro: modified 18 January 2022
 
 #+language: en
 #+export_file_name: org-remark.texi
@@ -53,7 +53,7 @@ This package is not available on ELPA or MELPA yet. Manual 
installation is requi
 
 Ensure to have Org Mode 9.4 or later (tested on 9.4.2). This package uses 
~org-collect-keywords~, which does not exist in an earlier version.
 
-Store all the =.el= files in the repo in your load-path and put this in your
+Store all the ~.el~ files in the repo in your load-path and put this in your
 init file:
 
 #+begin_src emacs-lisp
@@ -64,7 +64,7 @@ init file:
   (org-remark-global-tracking-mode +1)
 #+end_src
 
-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. By autoloading some commands in similar ways as the example 
keybindings below, you can control the timing of loading =org-remark=. 
+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. By autoloading some commands in similar ways as the example 
keybindings below, you can control the timing of loading ~org-remark~. 
 
 Below are example keybindings you might like to consider:
 
@@ -85,6 +85,10 @@ Below are example keybindings you might like to consider:
 #+end_src
 
 * Getting Started
+:PROPERTIES:
+:CUSTOM_ID: getting-started
+:END:
+
 ** Highlighting and Annotating
 
 #+findex: org-remark-mark
@@ -92,9 +96,9 @@ Below are example keybindings you might like to consider:
 #+findex: org-remark-view
 #+cindex: marginal notes file
 
-Once you have installed and set it up (refer to section 
[[#installation][Installation]]), Org-remark is simple to use. Select a part of 
text[fn:1] and call =M-x org-remark-mark= to highlight it. You will see the 
selected text gets highlighted. That's it.
+Once you have installed and set it up (refer to section 
[[#installation][Installation]]), Org-remark is simple to use. Select a part of 
text[fn:1] and call ~M-x org-remark-mark~ to highlight it. You will see the 
selected text gets highlighted. That's it.
 
-To add or 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 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 entry [...]
+To add or 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 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 entry [...]
 
 [fn:1] Set a mark and activate a region in Emacs terminology.
 
@@ -104,16 +108,16 @@ To add or display the marginal notes for the highlight 
you have just marked, pla
 #+findex: org-remark-view-prev
 #+findex: org-remark-remove
 
-After you have added a couple of highlights in the text, you can jump around 
to the next or previous highlights easily. Use =org-remark-view-next= and 
=org-remark-view-prev= to brows the marginal notes as you move from one 
highlight to another. They display the marginal notes on the side-window. Or 
use =org-remark-next= and =org-remark-prev= if you simply move to though 
highlights without displaying marginal notes for them.
+After you have added a couple of highlights in the text, you can jump around 
to the next or previous highlights easily. Use ~org-remark-view-next~ and 
~org-remark-view-prev~ to brows the marginal notes as you move from one 
highlight to another. They display the marginal notes on the side-window. Or 
use ~org-remark-next~ and ~org-remark-prev~ if you simply move to though 
highlights without displaying marginal notes for them.
 
 To make it easy to navigate, you can use the same "prefix key" to Org-remark 
commands, like this:
 
-- =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 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~
 
-The =C-c n= are 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 simply keep using a single key =]= or =[= to browse the next/previous 
highlights. After you have reached the one you like to act on, press =o= to 
open it, or =r= to remove it.
+The ~C-c n~ are 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 simply keep using a single key ~]~ or ~[~ to browse the next/previous 
highlights. After you have reached the one you like to act on, press ~o~ to 
open it, or ~r~ to remove it.
 
 ** Create Your Own Custom Highlighter Pens
 
@@ -123,11 +127,11 @@ The =C-c n= are the prefix key common to all of them. If 
you set the keybindings
 
 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-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~           :: 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 does not stop there; it 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. Refer to [[#create-custom-pens][Create Your Own 
Custom Pens]] for how to do it. 
+Org-remark does not stop there; it 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. Refer to [[#create-custom-pens][Create Your Own 
Custom Pens]] for how to do it. 
 
 This is it. It's all to get you started. For more detail, refer to the rest of 
this user manual, especially the [[#usage][Usage]] and 
[[#customizing][Customizing]] sections. There is more detail to the commands 
introduced in this section and more ways in which you can customize Org-remark. 
 
@@ -148,7 +152,7 @@ This is it. It's all to get you started. For more detail, 
refer to the rest of t
 #+findex: org-remark-mark-red-line
 #+findex: org-remark-create
 
-=org-remark-create= is a macro that lets 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.
+~org-remark-create~ is a macro that lets 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.
 
 #+begin_src elisp
   (org-remark-create "red-line"
@@ -160,14 +164,14 @@ This is it. It's all to get you started. For more detail, 
refer to the rest of t
 #+end_src
 
 - 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.
+  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=.
+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=".
 
 #+ATTR_TEXINFO: :tag NOTE
 #+begin_quote
@@ -180,20 +184,20 @@ Don't use =category= (all lowercase, symbol) as a 
property -- it's a special one
 #+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. 
+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. 
 
-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.
+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=). [[#customizing][By default]], this file is 
named =.org-remark-tracking=.
+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~). [[#customizing][By default]], this file is 
named ~.org-remark-tracking~.
 
-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. 
+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
 
 #+cindex: marginal notes file
 #+cindex: Org-remark properties for highlights
 
-When you mark a part of text with a highlighter pen function, Org-remark will 
automatically create a *marginal notes file*. [[#customizing][By default]], it 
will be named =marginalia.org= and created in the same directory as the file 
you are editing.
+When you mark a part of text with a highlighter pen function, Org-remark will 
automatically create a *marginal notes file*. [[#customizing][By default]], it 
will be named ~marginalia.org~ and created in the same directory as the file 
you are editing.
 
 The important thing to note is that Org-remark uses following properties in 
the property drawer of the headline to remember the highlights:
 
@@ -206,13 +210,13 @@ Essentially, the marginal notes file is a database in the 
plain text with using
 
 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.
 
-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 (refer to [[#create-custom-pens][Create Your Own 
Custom Pens]]). 
+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 (refer to [[#create-custom-pens][Create Your Own 
Custom Pens]]). 
 
-** \*marginal-notes\* Buffer
+** =*marginal-notes*= Buffer
 
 #+cindex: *marginal notes* buffer
 
-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. [[#customizing][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.
+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. [[#customizing][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.
 
 Org-remark displays the marginal notes buffer narrowed to the highlight the 
cursor is on. 
 
@@ -228,10 +232,10 @@ Org-remark displays the marginal notes buffer narrowed to 
the highlight the curs
 #+vindex: org-remark-use-org-id
 #+vindex: org-remark-tracking-file
 
-Org-remark's user options are available in the =org-remark= group.
+Org-remark's user options are available in the ~org-remark~ group.
 
 - Face: org-remark-highlighter ::
-  Default face for =org-remark-mark=
+  Default face for ~org-remark-mark~
 
 - Customizable variable: 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.
@@ -244,12 +248,12 @@ file.
 - Customizable variable: 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
+an action list for ~display-buffer~.  Refer to its documentation
 for more detail and expected elements of the list.
 
 - Customizable variable: org-remark-notes-buffer-name ::
   Define the buffer name of the marginal notes.
-=org-remark-open= creates an indirect clone buffer with this
+~org-remark-open~ creates an indirect clone buffer with this
 name.
 
 - Customizable variable: org-remark-use-org-id ::
@@ -258,13 +262,13 @@ name.
 - Customizable variable: 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.
+saved in ~org-remark-tracking-file~ automatically loads highlights.
 
 * Known Limitations
 
 - 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.
+- 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.
 
diff --git a/docs/resources/manual.css b/docs/resources/manual.css
index 05c8418c48..88e7520229 100644
--- a/docs/resources/manual.css
+++ b/docs/resources/manual.css
@@ -11,6 +11,7 @@ body {
     max-width: 850px;
     line-height: 1.5;
     font-family: sans-serif;
+    font-size: 18px;
 }
 
 h1, h2, h3 {