docs:

Author: meedstrom

README.org

@@ -1,8 +1,7 @@
-#+TITLE: org-node
 #+AUTHOR: Martin Edström
 #+EMAIL: meedstrom91@gmail.com
 #+STARTUP: content
-* What's all this
+* org-node
 #+HTML: <a href="https://repology.org/project/emacs%3Aorg-node/versions"> <img src="https://repology.org/badge/vertical-allrepos/emacs%3Aorg-node.svg" alt="Packaging status" align="right"> </a>
 
 I like [[https://github.com/org-roam/org-roam][org-roam]] but found it too slow, so I made [[https://github.com/meedstrom/quickroam][quickroam]].  And that idea spun off into this package, a standalone thing.  It may also be easier to pick up than org-roam.
@@ -82,8 +81,8 @@ A comparison of three systems that all permit relying on org-id and don't lock y
 
 Go to the manual and close this tab.
 
-- in Emacs: [[info:org-node]]
 - in a web browser: [[https://github.com/meedstrom/org-node/blob/main/org-node.org]]
+- or in Emacs after installation: [[info:org-node]]
 
 * Advice: Start with a paper Zettelkasten
 
@@ -102,4 +101,4 @@ If you are currently in the EU, you can order the pictured paper slips and box h
 
 Once these products arrive, take them and a pen with you to the local cafe, if it's a quiet noontime hour (otherwise a library, better in the afternoon).
 
-Have a warm coffee, lean back, and read https://zettelkasten.de/introduction/.
+Then have a warm coffee, lean back, and read https://zettelkasten.de/introduction/.

TODO.org

@@ -12,14 +12,31 @@
 
 * Other
 
+- https://github.com/meedstrom/org-node/issues/172
+
+- https://github.com/meedstrom/org-node/issues/171
+
+- https://github.com/meedstrom/org-node/issues/168
+
+- https://github.com/meedstrom/org-node/issues/161
+
+- https://github.com/meedstrom/org-node/issues/151
+
+- https://github.com/meedstrom/org-node/issues/143
+
+- https://github.com/meedstrom/org-node/issues/130
+
+- https://github.com/meedstrom/org-node/issues/62
+
 - A workflow to allow *untitled nodes*
 
   - [X] Create node without needing to type a title
   - [X] =org-node-grep=
   - [ ] Let =org-node-grep= create new nodes
   - [ ] (Rewrite =org-node-grep= so it does not need Consult)
   - [ ] Subroutine for *identifying a node by a grep result*, which could be used to insert/extract/capture/refile while only ever completing against grep results
-  - [ ] See that issue about untitled notes https://github.com/meedstrom/org-node/issues XXX
+  - [ ] See that issue about untitled notes https://github.com/meedstrom/org-node/issues/112
+
     Figure out the helper commands you'd want for embedding human-generated IDs in headings/titles.
 
 - Let =org-node-grep= obey =org-node-filter-fn=

org-node.org

@@ -8,7 +8,7 @@
 
 This is the manual for org-node.  The [[https://github.com/meedstrom/org-node][README]] is separate, but you should not need it anymore.
 
-* Installation
+** Installation
 
 Assuming your package manager gets recipes from [[https://melpa.org/#/getting-started][MELPA]], add the following initfile snippet.
 
@@ -52,12 +52,12 @@ If you're coming here from *org-roam*, try this instead:
   (setq org-node-file-timestamp-format "%Y%m%d%H%M%S-"))
 #+end_src
 
-** An update broke things?
+*** An update broke things?
 
 See at the end of this readme: [[#appendix-ii-how-to-rollback][How to rollback]]
 
 
-* Quick start
+** Quick start
 
 If you're new to these concepts, fear not.  The main things for day-to-day operation are two commands:
 
@@ -72,108 +72,113 @@ To see a list of all commands, enter an Org buffer and type ~M-o n <f1>~.
 
 To browse config options, type ~M-x customize-group RET org-node RET~ (or ~M-o n x o~).
 
-* Backlinks
+** Backlinks
 
 Backlinks are the butter on the bread that is your notes.  If you've ever seen a "What links here" section on some webpage, that's exactly what it is.
 
 You do not have to create backlinks yourself, they are autogenerated.  The following sections outline two basic ways this can work.
 
-** Backlink solution 1: displayed in a separate window
-*** Option 1A: Reuse the org-roam buffer
+*** Backlink solution 1: displayed in a separate window
+- Solution 1A: Reuse the org-roam buffer ::
 
-You can use the org-roam buffer without the rest of org-roam!  Enable the following mode, then to learn how to invoke the buffer, see [[info:org-roam#The Org-roam Buffer]] or [[https://www.orgroam.com/manual.html#The-Org_002droam-Buffer][online website]].
+  You can use the org-roam buffer without the rest of org-roam!  Enable the following mode.
 
-#+begin_src elisp
-(org-node-roam-accelerator-mode)
-#+end_src
+  Then to learn how to invoke the buffer, see their documentation at [[info:org-roam#The Org-roam Buffer]] or [[https://www.orgroam.com/manual.html#The-Org_002droam-Buffer][online website]].
 
-*** Option 1B: Use the org-node-context buffer
+  #+begin_src elisp
+  (org-node-roam-accelerator-mode)
+  #+end_src
 
-Org-node ships a rewrite of the org-roam buffer, in the included extension org-node-context.el.
 
-Try the command =org-node-context-dwim= (~M-o n b~).
+- Solution 1B: Use the org-node-context buffer ::
 
-If you like it, consider binding it to an easily typed key, such as =M-o M-b=.  Or you can let it keep itself updated, reflecting where point is at all times, by enabling this mode:
+  Org-node ships a rewrite of the org-roam buffer, in the included extension org-node-context.el.
+
+  Try the command =org-node-context-dwim= (~M-o n b~).
+
+  If you like it, consider binding it to an easily typed key, such as =M-o M-b=.  Or you can let it keep itself updated, reflecting where point is at all times, by enabling this mode:
+
+  #+begin_src elisp
+  ;; Tip: if you're like org-node's author and constantly lose your window
+  ;; configuration, the Emacs 30 command `toggle-window-dedicated' (C-x w d)
+  ;; can help, or simply invoking `org-node-context-dwim' a lot.
+  ;; The latter strategy tends to make this mode superfluous.
+  (org-node-context-follow-mode)
+  #+end_src
 
-#+begin_src elisp
-;; Tip: if you're like org-node's author and constantly lose your window
-;; configuration, the Emacs 30 command `toggle-window-dedicated' (C-x w d)
-;; can help, or simply invoking `org-node-context-dwim' a lot.
-;; The latter strategy tends to make this mode superfluous.
-(org-node-context-follow-mode)
-#+end_src
 
-** Backlink solution 2: Print inside the file
+*** Backlink solution 2: Print inside the file
 I rarely have the screen space to display a backlink buffer.  Because it needs my active involvement to keep visible, I go long periods seeing no backlinks.
 
 A complementary solution, which can also stand alone, is to have the backlinks /written into/ the file, on an Org property line or in a drawer.
 
-The included extension org-node-backlink.el helps you with that.
+To be clear, this solution never generates new IDs (and neither would Solution 1).  That's your own business.  This only adds/edits =:BACKLINKS:= properties or drawers.
 
-NOTE: To be clear, this global minor mode never generates new IDs (and neither would Option 1).  That's your own business.  This only adds/edits =:BACKLINKS:= properties or drawers, and only gives it backlinks corresponding to links where the original site already has or inherits some ID.
+#+BEGIN_QUOTE
+[!NOTE]
+A difference between org-node-context (solution 1) and org-node-backlink-mode (solution 2) is that the latter only shows backlinks corresponding to links where the original site /already has or inherits some ID/.  The former additionally shows backlinks to places that have no ID at all (since v3.14).
+#+END_QUOTE
 
-Contrast with org-node-context buffers, which since v3.14 additionally show backlinks to places where the origin has no ID at all.  That is not possible for org-node-backlink-mode.
+- Solution 2A: Automatic =:BACKLINKS:= property line ::
 
-*** Option 2A: Automatic =:BACKLINKS:= property line
+  Add to initfiles:
 
-Add to initfiles:
+  #+begin_src elisp
+  (setq org-node-backlink-do-drawers nil)
+  (org-node-backlink-mode)
+  #+end_src
 
-#+begin_src elisp
-(setq org-node-backlink-do-drawers nil)
-(org-node-backlink-mode)
-#+end_src
+  For a first-time run, type ~M-x org-node-backlink-mass-update-props~.  (Don't worry if you change your mind; undo with ~M-x org-node-backlink-mass-delete-props~.)
 
-For a first-time run, type ~M-x org-node-backlink-mass-update-props~.  (Don't worry if you change your mind; undo with ~M-x org-node-backlink-mass-delete-props~.)
 
-*** Option 2B: Automatic =:BACKLINKS:...:END:= drawer
+- Solution 2B: Automatic =:BACKLINKS:...:END:= drawer ::
 
-Same as Option 2A, but uses a multiline drawer.
+  Same as Solution 2A, but uses a multiline drawer.
 
-Add to initfiles:
+  Add to initfiles:
 
-#+begin_src elisp
-(setq org-node-backlink-do-drawers t)
-(org-node-backlink-mode)
-#+end_src
+  #+begin_src elisp
+  (setq org-node-backlink-do-drawers t)
+  (org-node-backlink-mode)
+  #+end_src
 
-For a first-time run, type ~M-x org-node-backlink-mass-update-drawers~.  (Don't worry if you change your mind; undo with ~M-x org-node-mass-delete-drawers~.)
+  For a first-time run, type ~M-x org-node-backlink-mass-update-drawers~.  (Don't worry if you change your mind; undo with ~M-x org-node-mass-delete-drawers~.)
 
 
-*** Option 2C: Semi-automatic =:BACKLINKS:...:END:= drawer
+- Solution 2C: Semi-automatic =:BACKLINKS:...:END:= drawer ::
 
-If you were previously using [[https://github.com/toshism/org-super-links][org-super-links]], you can continue letting it manage its drawers, and leave org-node out of the matter.
+  If you were previously using [[https://github.com/toshism/org-super-links][org-super-links]], you can continue letting it manage its drawers, and leave org-node out of the matter.
 
-Do not enable `org-node-backlink-mode` at all, just add to initfiles:
+  Do not enable `org-node-backlink-mode` at all, just add to initfiles:
 
-#+begin_src elisp
-(add-hook 'org-node-insert-link-hook
-          #'org-super-links-convert-link-to-super)
-#+end_src
+  #+begin_src elisp
+  (add-hook 'org-node-insert-link-hook
+            #'org-super-links-convert-link-to-super)
+  #+end_src
 
-You may find these tools useful:
+  You may find these tools useful:
 
-- 1. You can list any dead forward-links to fix them manually:
+  - 1. You can list any dead forward-links to fix them manually:
 
-  ~M-x org-node-list-dead-links~
+    ~M-x org-node-list-dead-links~
 
-- 2. You can add all missing backlinks in bulk:
+  - 2. You can add all missing backlinks in bulk:
 
-  ~M-x org-node-backlink-mass-update-drawers~
+    ~M-x org-node-backlink-mass-update-drawers~
 
-The second command may be useful as a starting point if you're new to org-super-links, pre-populating the notes you already have.
+  The second command may be useful as a starting point if you're new to org-super-links, pre-populating the notes you already have.
 
-However, when you have pre-existing drawers... *make a full backup* before trying it!
+  However, when you have pre-existing drawers... *make a full backup* before trying it!
 
-Org-node has a different usage in mind than org-super-links.  You may be accustomed to having old manually formatted and sorted drawers.
+  Org-node has a different usage in mind than org-super-links.  You may be accustomed to having old manually formatted and sorted drawers.
 
-Running aforementioned command *may re-sort your backlinks and re-format their appearance into something you don't want*; double-check the following options:
+  Running aforementioned command *may re-sort your backlinks and re-format their appearance into something you don't want*; double-check the following options:
 
-- =org-node-backlink-drawer-sorter=
-- =org-node-backlink-drawer-formatter=
+  - =org-node-backlink-drawer-sorter=
+  - =org-node-backlink-drawer-formatter=
 
-Finally, lines that contain no Org link such as =[[id:1234][Title]]= are *deleted*, which would mean *destroying any other info within.*  Same if a backlink is stale and no longer valid.
+  Finally, lines that contain no Org link such as =[[id:1234][Title]]= are *deleted*, which would mean *destroying any other info within.*  Same if a backlink is stale and no longer valid.
 
-* Misc
 ** Org-capture
 
 You may have heard that org-roam has a set of meta-capture templates: the =org-roam-capture-templates=.
@@ -461,8 +466,8 @@ You don't need software for that basic idea, only to make it extra convenient to
 
 Thus, fundamentally, any "journal" or "dailies" software are just operating on a sorted series to navigate through.  A node sequence.  You could have sequences for, let's say, historical events, Star Trek episodes, your school curriculum...
 
-* Appendix
-** Appendix I: Rosetta stone
+** Appendix
+*** Appendix I: Rosetta stone
 
 API cheatsheet between org-roam and org-node.
 
@@ -498,7 +503,7 @@ API cheatsheet between org-roam and org-node.
 | Get =ROAM_EXCLUDE=                        |                                 | =(org-mem-entry-property "ROAM_EXCLUDE" NODE)= |
 | Ensure fresh data                       | =(org-roam-db-sync)=              | =(org-node-cache-ensure t t)=                  |
 
-** Appendix II: How to rollback
+*** Appendix II: How to rollback
 :PROPERTIES:
 :CUSTOM_ID: appendix-ii-how-to-rollback
 :END:
@@ -549,15 +554,15 @@ With [[https://github.com/radian-software/straight.el][Straight]]:
   :straight (org-node :type git :host github :repo "meedstrom/org-node"
                       :branch "v1.6"))
 #+end_src
-** Appendix III: Random tips
-
+*** Appendix III: Random tips
+**** Fix export to HTML
 Org-roam shipped the optional =(require 'org-roam-export)=, a patch to fix =id:= links in HTML export.
 
 Good news, upstream fixed the root of the issue in 5e9953fa0!  Update Org to 9.7+ (comes with Emacs 30), then set this.
 
 : (setq org-html-prefer-user-labels t)
 
-** Appendix IV: What are =ROAM_REFS=?
+*** Appendix IV: What are =ROAM_REFS=?
 :PROPERTIES:
 :CUSTOM_ID: appendix-iv-what-are-roam_refs
 :END:
@@ -587,10 +592,10 @@ For performance reasons, not just any string of text is accepted -- it must have
 
 Org-roam calls such backlinks /reflinks/.  In my view, adding a new word for such a similar concept just increases the air of mystery.  That's why in org-node's context buffer, they're just called "ref backlinks" -- as opposed to "ID backlinks".
 
-*** What's it actually used for?
+**** What's it actually used for?
 
 People often use it to write notes about a specific web-page or PDF file, and call it a ref-node for that resource.
 
-*** Citations
+**** Citations
 
 As a special case, citation keys such as "@ioannidis2005" also work in =ROAM_REFS=, corresponding to Org citations like =[cite:@ioannidis2005]=.