This is org-node.info, produced by makeinfo version 6.8 from
org-node.texi.

INFO-DIR-SECTION Emacs
START-INFO-DIR-ENTRY
* Org-Node: (org-node). Link org-id entries into a network.
END-INFO-DIR-ENTRY


File: org-node.info,  Node: Top,  Next: What's all this,  Up: (dir)

org-node
********

* Menu:

* What's all this::
* Setup::
* Backlinks::
* Misc::
* Appendix::

— The Detailed Node Listing —

What’s all this

* What's a "node"?::
* Benchmarks on my machine::
* Features::

Setup

* Install::
* Quick start::

Install

* An update broke things?::

Backlinks

* Backlink solution 1 displayed in a separate window::
* Backlink solution 2 Print inside the file::

Backlink solution 1: displayed in a separate window

* Option 1A Reuse the org-roam buffer::
* Option 1B Use the org-node-context buffer::

Backlink solution 2: Print inside the file

* Option 2A Automatic BACKLINKS property line::
* Option 2B Automatic ‘BACKLINKS...END’ drawer: Option 2B Automatic BACKLINKSEND drawer.
* Option 2C Semi-automatic ‘BACKLINKS...END’ drawer: Option 2C Semi-automatic BACKLINKSEND drawer.

Misc

* Org-capture::
* Exclude uninteresting nodes::
* Missing completions?::
* Completion-at-point::
* Customize appearance::
* Sort completions::
* Grep::
* Let org-open-at-point detect refs::
* Limitation TRAMP::
* Limitation Unique titles::
* Limitation Org-ref::
* Toolbox::
* Experimental Node sequences::

Sort completions

* Lining up properties::

Experimental: Node sequences

* What are node seqs?::

Appendix

* Appendix I Rosetta stone::
* Appendix II How to rollback::
* Appendix III Random tips::
* Appendix IV What are ROAM_REFS?::

Appendix IV: What are ‘ROAM_REFS’?

* What's it actually used for?::
* Citations::



File: org-node.info,  Node: What's all this,  Next: Setup,  Prev: Top,  Up: Top

1 What’s all this
*****************

I like org-roam (https://github.com/org-roam/org-roam) but found it too
slow, so I made quickroam (https://github.com/meedstrom/quickroam).  And
that idea spun off into this package, a standalone thing.  It may also
be easier to pick up than org-roam.

   • *If you were using org-roam*, there is nothing to migrate.  You can
     use both packages.  It’s the same on-disk format: "notes" are
     identified by their org-id.

     In pursuit of being "just org-id", this package has no equivalent
     setting to ‘org-roam-directory’ – it just looks up what org-mem
     (https://github.com/meedstrom/org-mem) knows, which by default
     includes every file in ‘org-id-locations’ and more.

   • *If you were not using org-roam*, maybe think of it as somewhat
     like org-recent-headings
     (https://github.com/alphapapa/org-recent-headings) tooled-up to the
     extent that you won’t need other methods of browsing, as long as
     you give IDs to all objects of interest.

     If you were the sort of person to prefer ID-links over file links
     or any other type of link, you’re in the right place!  Now you can
     rely on IDs, and—if you want—stop worrying about filenames,
     directories and subtree hierarchies.  As long as you’ve assigned an
     ID to a heading or file, you can find it later.

* Menu:

* What's a "node"?::
* Benchmarks on my machine::
* Features::


File: org-node.info,  Node: What's a "node"?,  Next: Benchmarks on my machine,  Up: What's all this

1.1 What’s a "node"?
====================

My life can be divided into two periods "*before org-roam*" and "*after
org-roam*".  I crossed a kind of gap once I got a good way to link
between my notes.  It’s odd to remember when I just relied on browsing
subtrees and filesystem directories – what a strange way to work!

   I used to lose track of things I had written, under some forgotten
heading in a forgotten file in a forgotten directory.  The org-roam
method let me *find and build on* my own work, instead of recreating it
all the time (https://en.wikipedia.org/wiki/Cryptomnesia).

   At the core, all the "notetaking packages" (orgrr
(https://github.com/rtrppl/orgrr)/zk
(https://github.com/localauthor/zk)/zetteldeft
(https://github.com/EFLS/zetteldeft)/org-roam
(https://github.com/org-roam/org-roam)/denote
(https://github.com/protesilaos/denote)/howm
(https://github.com/kaorahi/howm)/minaduki
(https://github.com/kisaragi-hiu/minaduki)/...) try to help you with
this: make it easy to link between notes and explore them.

   Right off the bat, that imposes two requirements: a method to search
for notes, since you can’t link to something you can’t search for, and a
design-choice about what kinds of things should turn up as search hits.
What’s a "note"?

   Just searching for Org files is too coarse.  Just searching for any
subtree anywhere brings in too much clutter.

   *Here’s what org-roam invented.*  It turns out that if you limit the
search-hits to just those files and subtrees you’ve deigned to assign an
org-id – which roughly maps to _everything you’ve ever thought it was
worth linking to_ – it filters out the noise excellently.

   Once a subtree has an ID you can link to, it’s a "node" because it
has joined the wider graph, the network of linked nodes.  I wish the
English language had more distinct sounds for the words "node" and
"note", but to clarify, I’ll say "ID-node" when the distinction matters
(which it rarely does).


File: org-node.info,  Node: Benchmarks on my machine,  Next: Features,  Prev: What's a "node"?,  Up: What's all this

1.2 Benchmarks on my machine
============================

The original reason that org-node exists.

                                 org-roam   org-node
-------------------------------------------------------
Time to index my 3000 nodes      2m 48s     0m 02s
Time to save file w/ 400 nodes   5–10s      instant
Time to display 20 backlinks     5–10s      instant
Time to open minibuffer          1–3s       instant


File: org-node.info,  Node: Features,  Prev: Benchmarks on my machine,  Up: What's all this

1.3 Features
============

A comparison of three systems that all permit relying on org-id and
don’t lock you into the concept of "one-note-per-file".

Feature                          org-roam   org-node           org-super-links (https://github.com/toshism/org-super-links)
---------------------------------------------------------------------------------------------------------------------------------
Backlinks                        yes        yes                yes
Node search and insert           yes        yes                – (suggests org-ql (https://github.com/alphapapa/org-ql))
Node aliases                     yes        yes                –
Node exclusion                   yes        yes                not applicable
Refile                           yes        yes                –
Rich backlinks buffer            yes        yes                –
Customize how backlinks shown    yes        yes                yes
Reflinks                         yes        yes                –
Ref search                       yes        yes (as aliases)   not applicable
Org 9.5 @citations as refs       yes        yes                not applicable
Support org-ref v3               yes        limited            not applicable
Support org-ref v2               yes        –                  not applicable
Work thru org-roam-capture       yes        yes                ?
Work thru org-capture            –          yes                ?
Daily-nodes                      yes        yes                –
Node sequences                   –          yes                –
Show backlinks in same window    –          yes                yes
Cooperate with org-super-links   –          yes                not applicable
Fix link descriptions            –          yes                –
List dead links                  –          yes                –
Rename file when title changes   –          yes                –
Warn about duplicate titles      –          yes                –
Principled "related-section"     –          yes                yes
Untitled notes                   –          limited            –
org-protocol extension           yes        –                  –
Support ‘roam:’ links            yes        – (wontfix)        –
Can have separate note piles     yes        – (wontfix)        not applicable
Some query-able cache            yes        yes                –
Async cache rebuild              –          yes                not applicable


File: org-node.info,  Node: Setup,  Next: Backlinks,  Prev: What's all this,  Up: Top

2 Setup
*******

* Menu:

* Install::
* Quick start::


File: org-node.info,  Node: Install,  Next: Quick start,  Up: Setup

2.1 Install
===========

Org-node depends on ‘org-mem-updater-mode’ from org-mem
(https://github.com/meedstrom/org-mem).

   Assuming your package manager gets recipes from MELPA
(https://melpa.org/#/getting-started), add the following initfile
snippet.

     (use-package org-mem
       :config
       (org-mem-updater-mode))

     (use-package org-node
       :init
       ;; Optional key bindings
       ;; Tip: Try changing these to just "M-o"!
       (keymap-global-set "M-o n" org-node-global-prefix-map)
       (with-eval-after-load 'org
         (keymap-set org-mode-map "M-o n" org-node-org-prefix-map))
       :config
       (org-node-cache-mode))

   If you’re coming here from *org-roam*, try this instead:

     (use-package org-mem
       :config
       (setq org-mem-watch-dirs
             (list "~/org/")) ;; Your org-roam-directory here
       (org-mem-updater-mode))

     (use-package org-node
       :init
       ;; Optional key bindings
       ;; Tip: Try changing these to just "M-o"!
       (keymap-global-set "M-o n" org-node-global-prefix-map)
       (with-eval-after-load 'org
         (keymap-set org-mode-map "M-o n" org-node-org-prefix-map))
       :config
       (org-node-cache-mode)
       (org-node-roam-accelerator-mode)
       (setq org-node-creation-fn #'org-node-new-via-roam-capture)
       (setq org-node-file-slug-fn #'org-node-slugify-like-roam-default)
       (setq org-node-file-timestamp-format "%Y%m%d%H%M%S-"))

* Menu:

* An update broke things?::


File: org-node.info,  Node: An update broke things?,  Up: Install

2.1.1 An update broke things?
-----------------------------

See How to rollback
(https://github.com/meedstrom/org-node#appendix-ii-how-to-rollback) at
the end of this readme.


File: org-node.info,  Node: Quick start,  Prev: Install,  Up: Setup

2.2 Quick start
===============

If you’re new to these concepts, fear not.  The main things for
day-to-day operation are two commands:

   • ‘org-node-find’ (‘M-o n f’)
   • ‘org-node-insert-link’ (‘M-o n i’)

   Tip: There’s *no separate command* for creating a new node!  Reuse
one of the commands above, and type the name of a node that doesn’t
exist.  Try it and see what happens!

   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’.


File: org-node.info,  Node: Backlinks,  Next: Misc,  Prev: Setup,  Up: Top

3 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.  Imagine seeing that, all the time.  The following sections
outline two general ways to do so.

* Menu:

* Backlink solution 1 displayed in a separate window::
* Backlink solution 2 Print inside the file::


File: org-node.info,  Node: Backlink solution 1 displayed in a separate window,  Next: Backlink solution 2 Print inside the file,  Up: Backlinks

3.1 Backlink solution 1: displayed in a separate window
=======================================================

* Menu:

* Option 1A Reuse the org-roam buffer::
* Option 1B Use the org-node-context buffer::


File: org-node.info,  Node: Option 1A Reuse the org-roam buffer,  Next: Option 1B Use the org-node-context buffer,  Up: Backlink solution 1 displayed in a separate window

3.1.1 Option 1A: Reuse the org-roam buffer
------------------------------------------

You can use the org-roam buffer without the rest of org-roam.  Enable
the following mode, then see org-roam’s documentation
(https://www.orgroam.com/manual.html#The-Org_002droam-Buffer).

     (org-node-roam-accelerator-mode)


File: org-node.info,  Node: Option 1B Use the org-node-context buffer,  Prev: Option 1A Reuse the org-roam buffer,  Up: Backlink solution 1 displayed in a separate window

3.1.2 Option 1B: Use the org-node-context buffer
------------------------------------------------

Org-node ships a rewrite of the org-roam buffer.

   Try the command ‘org-node-context-dwim’ (‘M-o n b’).

   If you like it, consider binding it to a particularly short 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-context-follow-mode)


File: org-node.info,  Node: Backlink solution 2 Print inside the file,  Prev: Backlink solution 1 displayed in a separate window,  Up: Backlinks

3.2 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.

   NOTE: To be clear, this 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.

* Menu:

* Option 2A Automatic BACKLINKS property line::
* Option 2B Automatic ‘BACKLINKS...END’ drawer: Option 2B Automatic BACKLINKSEND drawer.
* Option 2C Semi-automatic ‘BACKLINKS...END’ drawer: Option 2C Semi-automatic BACKLINKSEND drawer.


File: org-node.info,  Node: Option 2A Automatic BACKLINKS property line,  Next: Option 2B Automatic BACKLINKSEND drawer,  Up: Backlink solution 2 Print inside the file

3.2.1 Option 2A: Automatic ‘:BACKLINKS:’ property line
------------------------------------------------------

Add to initfiles:

     (setq org-node-backlink-do-drawers nil)
     (org-node-backlink-mode)

   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’.)


File: org-node.info,  Node: Option 2B Automatic BACKLINKSEND drawer,  Next: Option 2C Semi-automatic BACKLINKSEND drawer,  Prev: Option 2A Automatic BACKLINKS property line,  Up: Backlink solution 2 Print inside the file

3.2.2 Option 2B: Automatic ‘:BACKLINKS:...:END:’ drawer
-------------------------------------------------------

Same as Option 2A, but uses a multiline drawer.

   Add to initfiles:

     (setq org-node-backlink-do-drawers t)
     (org-node-backlink-mode)

   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’.)


File: org-node.info,  Node: Option 2C Semi-automatic BACKLINKSEND drawer,  Prev: Option 2B Automatic BACKLINKSEND drawer,  Up: Backlink solution 2 Print inside the file

3.2.3 Option 2C: Semi-automatic ‘:BACKLINKS:...:END:’ drawer
------------------------------------------------------------

If you were previously using org-super-links
(https://github.com/toshism/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:

     (add-hook 'org-node-insert-link-hook
               #'org-super-links-convert-link-to-super)

   You may find these tools useful:

   • 1.  You can list any dead forward-links to fix them manually:

     ‘M-x org-node-list-dead-links’

   • 2.  You can add all missing backlinks in bulk:

     ‘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.

   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.

   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’

   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.


File: org-node.info,  Node: Misc,  Next: Appendix,  Prev: Backlinks,  Up: Top

4 Misc
******

* Menu:

* Org-capture::
* Exclude uninteresting nodes::
* Missing completions?::
* Completion-at-point::
* Customize appearance::
* Sort completions::
* Grep::
* Let org-open-at-point detect refs::
* Limitation TRAMP::
* Limitation Unique titles::
* Limitation Org-ref::
* Toolbox::
* Experimental Node sequences::


File: org-node.info,  Node: Org-capture,  Next: Exclude uninteresting nodes,  Up: Misc

4.1 Org-capture
===============

You may have heard that org-roam has a set of meta-capture templates:
the ‘org-roam-capture-templates’.

   People who understand the magic of capture templates, they may take
this in stride.  Me, I never felt confident using a second-order
abstraction over an already leaky abstraction.

   Can we just use vanilla org-capture?  That’d be less scary.  The
answer is yes!

   The secret sauce is ‘(function org-node-capture-target)’.  Examples:

     (setq org-capture-templates
           '(("e" "Capture entry into ID node"
              entry (function org-node-capture-target) "* %?")

             ("p" "Capture plain text into ID node"
              plain (function org-node-capture-target) nil
              :empty-lines-after 1)

             ("j" "Jump to ID node"
              plain (function org-node-capture-target) nil
              :prepend t
              :immediate-finish t
              :jump-to-captured t)

             ;; Sometimes handy after `org-node-insert-link', to
             ;; make a stub you plan to fill in later, without
             ;; leaving the current buffer for now
             ("q" "Make quick stub ID node"
              plain (function org-node-capture-target) nil
              :immediate-finish t)))

   With that done, you can optionally configure the everyday commands
‘org-node-find’ & ‘org-node-insert-link’ to outsource to org-capture
when they try to create new nodes:

     (setq org-node-creation-fn #'org-capture)

   That last optional functionality may only confuse you more if I try
to describe it in words – better you give it a spin and see if you like.

   For deeper hacking, see wiki
(https://github.com/meedstrom/org-node/wiki/Capture).


File: org-node.info,  Node: Exclude uninteresting nodes,  Next: Missing completions?,  Prev: Org-capture,  Up: Misc

4.2 Exclude uninteresting nodes
===============================

One user had over a thousand project-nodes, but only just began to do a
knowledge base, and wished to avoid seeing the project nodes.

   This could work by—for example—excluding anything with the Org tag
‘:project:’ or perhaps anything that has a TODO state.  Here’s a way to
exclude both:

     (setq org-node-filter-fn
           (lambda (node)
             (not (or (member "project" (org-mem-tags node))
                      (org-mem-todo-state node)))))

   Or you could go with a whitelist approach, to show only nodes from a
certain directory we’ll call "my-personal-wiki":

     (setq org-node-filter-fn
           (lambda (node)
             (string-search "/my-personal-wiki/" (org-mem-file node))))


File: org-node.info,  Node: Missing completions?,  Next: Completion-at-point,  Prev: Exclude uninteresting nodes,  Up: Misc

4.3 Missing completions?
========================

Since org-mem (https://github.com/meedstrom/org-mem) only looks at saved
files on disk, new notes only "appear" after save.  So it can make for a
smoother experience to enable ‘auto-save-visited-mode’.

   That is also the usage that I test most – I’ve had the following
config for years:

     (setq auto-save-visited-interval 2)
     (auto-save-visited-mode)

   FWIW, org-node used to try to be smarter and also cache notes in
unsaved buffers, but that quickly became difficult to reason about,
especially wrt.  deciding whether to update a backlink or not.


File: org-node.info,  Node: Completion-at-point,  Next: Customize appearance,  Prev: Missing completions?,  Up: Misc

4.4 Completion-at-point
=======================

To complete words at point into known node titles:

     (org-node-complete-at-point-mode)
     (setq org-roam-completion-everywhere nil) ;; Stop org-roam equivalent.


File: org-node.info,  Node: Customize appearance,  Next: Sort completions,  Prev: Completion-at-point,  Up: Misc

4.5 Customize appearance
========================

(Analogue to ‘org-roam-node-display-template’)

   To customize how the nodes look in the minibuffer, configure
‘org-node-affixation-fn’:

     M-x customize-variable RET org-node-affixation-fn

   A related option is ‘org-node-alter-candidates’, which lets you match
against the annotations as well as the title:

     (setq org-node-alter-candidates t)


File: org-node.info,  Node: Sort completions,  Next: Grep,  Prev: Customize appearance,  Up: Misc

4.6 Sort completions
====================

A useful way to sort completions is to base it on a ‘:TIME_MODIFIED:’
property under each of your ID-nodes.

   First, of course, a few nodes must have such a property.  Start
generating them by adding this hook:

     (setq org-node-property-mtime "TIME_MODIFIED")
     (add-hook 'org-node-modification-hook
               #'org-node-update-mtime-property)

   Then to sort the completions:

     (setq org-node-display-sort-fn
           #'org-node-sort-by-mtime-property)

* Menu:

* Lining up properties::


File: org-node.info,  Node: Lining up properties,  Up: Sort completions

4.6.1 Lining up properties
--------------------------

I want to see ‘:TIME_CREATED:’ right above ‘:TIME_MODIFIED:’.

   So I re-sort the entire properties drawer on save:

     (add-hook 'org-node-modification-hook
               (defun my-sort-properties ()
                 (org-back-to-heading-or-point-min)
                 (re-search-forward org-property-drawer-re (org-entry-end-position))
                 (let ((end (pos-bol))
                       (beg (progn (goto-char (match-beginning 0))
                                   (forward-line 1)
                                   (point))))
                   (sort-lines nil beg end)))
               50)
     ;; The above is so the following properties will come in predictable order.
     (setq org-node-property-crtime "TIME_CREATED")
     (setq org-node-property-mtime "TIME_MODIFIED")


File: org-node.info,  Node: Grep,  Next: Let org-open-at-point detect refs,  Prev: Sort completions,  Up: Misc

4.7 Grep
========

If you have Ripgrep installed on the computer, and Consult
(https://github.com/minad/consult) installed on Emacs, you can use this
command to grep across all your Org files at any time.

   • ‘org-node-grep’ (‘M-o n g’)

   This can be a power-tool for mass edits.  Say you want to rename some
Org tag ‘:math:’ to ‘:Math:’ absolutely everywhere.  Then you could
follow a procedure such as:

  1. Use ‘org-node-grep’ and type ‘:math:’
  2. Use ‘embark-export’ (from package Embark
     (https://github.com/oantolin/embark))
  3. Use ‘wgrep-change-to-wgrep-mode’ (from package wgrep
     (https://github.com/mhayashi1120/Emacs-wgrep))
  4. Do a query-replace (‘M-%’) to replace all ‘:math:’ with ‘:Math:’
  5. Type ‘C-c C-c’ to apply the changes


File: org-node.info,  Node: Let org-open-at-point detect refs,  Next: Limitation TRAMP,  Prev: Grep,  Up: Misc

4.8 Let org-open-at-point detect refs
=====================================

(For background, see What are ROAM_REFS?
(https://github.com/meedstrom/org-node#appendix-iv-what-are-roam_refs)
at the end of this README.)

   Say there’s a link to a web URL, and you’ve forgotten you also have a
node listing that exact URL in its ‘ROAM_REFS’ property.

   Wouldn’t it be nice if, clicking on that link, you automatically
visit that node first instead of being sent to the web?  Here you go:

     (add-hook 'org-open-at-point-functions
               #'org-node-try-visit-ref-node)


File: org-node.info,  Node: Limitation TRAMP,  Next: Limitation Unique titles,  Prev: Let org-open-at-point detect refs,  Up: Misc

4.9 Limitation: TRAMP
=====================

Working with files over TRAMP is unsupported, because org-mem works in
parallel subprocesses which do not inherit your TRAMP setup.

   The best way to change this is to file an issue
(https://github.com/meedstrom/org-mem/issues) to show you care :-)


File: org-node.info,  Node: Limitation Unique titles,  Next: Limitation Org-ref,  Prev: Limitation TRAMP,  Up: Misc

4.10 Limitation: Unique titles
==============================

If two ID-nodes exist with the same title, one of them disappears from
minibuffer completions.

   That’s just the nature of completion.  Much can be said for embracing
the uniqueness constraint, and org-node will print messages about
collisions.

   Anyway... there’s a workaround.  Assuming you leave
‘org-node-affixation-fn’ at its default setting, adding this to
initfiles tends to do the trick:

     (setq org-node-alter-candidates t)

   This lets you match against the node outline path and not only the
title, which resolves most conflicts given that the most likely source
of conflict is subheadings in disparate files, that happen to be named
the same.

   NB: for users of ‘org-node-complete-at-point-mode’, this workaround
won’t help those completions.  With some luck you’ll link to the wrong
one of two homonymous nodes, but it’s worth being aware.  (#62
(https://github.com/meedstrom/org-node/issues/62))


File: org-node.info,  Node: Limitation Org-ref,  Next: Toolbox,  Prev: Limitation Unique titles,  Up: Misc

4.11 Limitation: Org-ref
========================

Org-node supports the Org 9.5 @citations, but not fully the aftermarket
org-ref (https://github.com/jkitchin/org-ref) &citations that emulate
LaTeX look-and-feel.

   What works is bracketed Org-ref v3 citations that start with "cite",
e.g.  ‘[[citep:...]]’, ‘[[citealt:...]]’, ‘[[citeauthor:...]]’, since
org-mem-parser.el is able to pick them up for free.

   What doesn’t work is e.g.  ‘[[bibentry:...]]’ since it doesn’t start
with "cite", nor plain ‘citep:...’ since it is not wrapped in brackets.

   If you need more of Org-ref, you have at least two options:

   • Use org-roam - see discussions on boosting its performance here
     (https://org-roam.discourse.group/t/rewriting-org-roam-node-list-for-speed-it-is-not-sqlite/3475/92)
     and here
     (https://org-roam.discourse.group/t/improving-performance-of-node-find-et-al/3326/33)

   • Contribute to org-mem (https://github.com/meedstrom/org-mem), see
     function ‘org-mem-parser--scan-text-until’.


File: org-node.info,  Node: Toolbox,  Next: Experimental Node sequences,  Prev: Limitation Org-ref,  Up: Misc

4.12 Toolbox
============

(Note that you can view this same list of commands in Emacs.  Assuming
that ‘M-o n’ was where you bound ‘org-node-org-prefix-map’, type ‘M-o n
<f1>’.)

   Basic commands:

   • ‘org-node-find’
   • ‘org-node-insert-link’
   • ‘org-node-insert-into-related’
   • ‘org-node-insert-transclusion’
   • ‘org-node-insert-transclusion-as-subtree’
   • ‘org-node-visit-random’
   • ‘org-node-context-dwim’
   • ‘org-node-set-tags’
   • ‘org-node-add-alias’
   • ‘org-node-add-ref’
   • ‘org-node-refile’
        • Does two technically different things: either move a subtree
          into some node it prompts you for, or if you press RET with no
          input, extract the subtree into a new file (similarly to
          ‘org-roam-extract-subtree’)
   • ‘org-node-seq-dispatch’
        • Browse node series – see README
   • ‘org-node-nodeify-entry’
        • Give an ID to the entry at point, and run the hook
          ‘org-node-creation-hook’
   • ‘org-node-grep’
        • (Requires consult (https://github.com/minad/consult)) Grep
          across all known Org files.
   • ‘org-node-card-view’
        • Try it and, uh, see.

   Rarer commands:

   • ‘org-node-rewrite-links-ask’
        • Look for link descriptions that got out of sync with the
          corresponding node title, then prompt at each link to update
          it

   • ‘org-node-rename-file-by-title’
        • Auto-rename the file based on the current ‘#+title’ or first
          heading
             • Can be run manually or placed on ‘after-save-hook’!  When
               run as a hook, it is conservative, doing nothing until
               you configure ‘org-node-renames-allowed-dirs’.
             • *Please note* that if your filenames have datestamp
               prefixes, like org-roam’s default behavior of making
               filenames such as ‘20240831143302-node_title.org’, it is
               important to get ‘org-node-file-timestamp-format’ right
               or it *may clobber a pre-existing datestamp*.

               A message is printed about the rename, but it’s easy to
               miss.

   • ‘org-node-list-dead-links’
        • List links where the destination ID could not be found

   • ‘org-node-lint-all-files’
        • Can help you fix a broken setup: it runs org-lint on all known
          files and generates a report of Org syntax problems, for you
          to correct manually.

          Org-node assumes all files have valid syntax
          (https://github.com/meedstrom/org-node/issues/8#issuecomment-2101316447),
          but many of the reported problems are survivable.

   • ‘org-node-list-reflinks’
        • List all links that aren’t ‘id:’ links.  Also includes
          citations, even though they are technically not links.

   • ‘org-node-list-feedback-arcs’
        • (Requires GNU R, with R packages stringr, readr and igraph)

          Explore feedback arcs
          (https://en.wikipedia.org/wiki/Feedback_arc_set) in your ID
          link network.  Can work as a sort of occasional QA routine
          (https://edstrom.dev/zvjjm/slipbox-workflow#ttqyc).

   • ‘org-node-rename-asset-and-rewrite-links’
        • Interactively rename an asset such as an image file and try to
          update all Org links to them.  Requires wgrep
          (https://github.com/mhayashi1120/Emacs-wgrep).
             • NOTE: It prompts you for a certain root directory, and
               then only looks for links in there, and in sub and
               sub-subdirectories and so on – but won’t find a link
               elsewhere.

               Like if you have Org files under /mnt linking to assets
               in /home, then those links won’t be updated.  Or if you
               choose ~/org/some-subdir as the root directory, then
               links in ~/org/file.org will not update.  So choose ~/org
               as the root even if you are renaming something in a
               subdir.

   Rarer commands for org-node-backlink-mode:

   • ‘org-node-backlink-mass-update-drawers’
   • ‘org-node-backlink-mass-update-props’
   • ‘org-node-backlink-mass-delete-drawers’
   • ‘org-node-backlink-mass-delete-props’
   • ‘org-node-backlink-fix-buffer’


File: org-node.info,  Node: Experimental Node sequences,  Prev: Toolbox,  Up: Misc

4.13 Experimental: Node sequences
=================================

Do you already know about "daily-notes"?  Then get started as follows:

  1. Configure variable ‘org-node-seq-defs’; see wiki
     (https://github.com/meedstrom/org-node/wiki/Configuring-node-sequences)
     for premade examples
  2. Enable ‘(org-node-seq-mode)’
  3. Try the command ‘org-node-seq-dispatch’ (‘M-o n s’)

* Menu:

* What are node seqs?::


File: org-node.info,  Node: What are node seqs?,  Up: Experimental Node sequences

4.13.1 What are node seqs?
--------------------------

It’s easiest to explain node sequences if we use "daily-notes" (aka
"dailies") as an example.

   Org-roam’s idea of a "daily-note" is the same as an org-journal
(https://github.com/bastibe/org-journal) entry: a file/entry where the
title is just today’s date.

   You don’t need software for that basic idea, only to make it extra
convenient to navigate them and jump back and forth in the series.

   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...


File: org-node.info,  Node: Appendix,  Prev: Misc,  Up: Top

5 Appendix
**********

* Menu:

* Appendix I Rosetta stone::
* Appendix II How to rollback::
* Appendix III Random tips::
* Appendix IV What are ROAM_REFS?::


File: org-node.info,  Node: Appendix I Rosetta stone,  Next: Appendix II How to rollback,  Up: Appendix

5.1 Appendix I: Rosetta stone
=============================

API cheatsheet between org-roam and org-node.

Action                                      org-roam                            org-node
---------------------------------------------------------------------------------------------------------------------------------
Get ID near point                           ‘(org-roam-id-at-point)’            ‘(org-entry-get-with-inheritance "ID")’
Get node at point                           ‘(org-roam-node-at-point)’          ‘(org-node-at-point)’
Prompt user to pick a node                  ‘(org-roam-node-read)’              ‘(org-node-read)’
Get node by ID                                                                  ‘(org-mem-entry-by-id ID)’
Get list of files                           ‘(org-roam-list-files)’             ‘(org-mem-all-files)’
Get backlink objects                        ‘(org-roam-backlinks-get NODE)’     ‘(org-mem-id-links-to-entry NODE)’
Get reflink objects                         ‘(org-roam-reflinks-get NODE)’      ‘(org-mem-roam-reflinks-to-entry NODE)’
Get title                                   ‘(org-roam-node-title NODE)’        ‘(org-mem-entry-title NODE)’
Get title of file where NODE is             ‘(org-roam-node-file-title NODE)’   ‘(org-mem-file-title NODE)’
Get title _or_ name of file where NODE is                                       ‘(org-mem-file-title-or-basename NODE)’
Get full path to file where NODE is         ‘(org-roam-node-file NODE)’         ‘(org-mem-entry-file NODE)’
Get ID                                      ‘(org-roam-node-id NODE)’           ‘(org-mem-entry-id NODE)’
Get tags                                    ‘(org-roam-node-tags NODE)’         ‘(org-mem-entry-tags NODE)’
Get tags (local only)                                                           ‘(org-mem-entry-tags-local NODE)’
Get tags (inherited only)                                                       ‘(org-mem-entry-tags-inherited NODE)’
Get outline level                           ‘(org-roam-node-level NODE)’        ‘(org-mem-entry-level NODE)’
Get char position                           ‘(org-roam-node-point NODE)’        ‘(org-mem-entry-pos node)’
Get line number                                                                 ‘(org-mem-entry-lnum NODE)’
Get properties                              ‘(org-roam-node-properties NODE)’   ‘(org-mem-entry-properties NODE)’
Get subtree TODO state                      ‘(org-roam-node-todo NODE)’         ‘(org-mem-entry-todo-state NODE)’
Get subtree SCHEDULED                       ‘(org-roam-node-scheduled NODE)’    ‘(org-mem-entry-scheduled NODE)’
Get subtree DEADLINE                        ‘(org-roam-node-deadline NODE)’     ‘(org-mem-entry-deadline NODE)’
Get subtree CLOSED                                                              ‘(org-mem-entry-closed NODE)’
Get subtree priority                        ‘(org-roam-node-priority NODE)’     ‘(org-mem-entry-priority NODE)’
Get outline-path                            ‘(org-roam-node-olp NODE)’          ‘(org-mem-entry-olpath NODE)’
Get ‘ROAM_REFS’                             ‘(org-roam-node-refs NODE)’         ‘(org-mem-entry-roam-refs NODE)’
Get ‘ROAM_ALIASES’                          ‘(org-roam-node-aliases NODE)’      ‘(org-mem-entry-roam-aliases NODE)’
Get ‘ROAM_EXCLUDE’                                                              ‘(org-mem-entry-property "ROAM_EXCLUDE" NODE)’
Ensure fresh data                           ‘(org-roam-db-sync)’                ‘(org-node-cache-ensure t t)’


File: org-node.info,  Node: Appendix II How to rollback,  Next: Appendix III Random tips,  Prev: Appendix I Rosetta stone,  Up: Appendix

5.2 Appendix II: How to rollback
================================

Instructions to downgrade to an older version
(https://github.com/meedstrom/org-node/tags), let’s say 1.6.2.

   With Quelpa (https://github.com/quelpa/quelpa):
     (use-package org-node
       :quelpa (org-node :fetcher github :repo "meedstrom/org-node"
                         :branch "v1.6"))

   With vc-use-package (https://github.com/slotThe/vc-use-package) on
Emacs 29:
     (use-package org-node
       :vc ( :fetcher github :repo "meedstrom/org-node"
             :branch "v1.6"))

   With built-in ‘:vc’ on Emacs 30+ (but note default value of
‘use-package-vc-prefer-newest’ means you never update, since it is not
aware of Git tags):
     (use-package org-node
       :vc ( :url "https://github.com/meedstrom/org-node"
             :branch "v1.6"))

   With Elpaca (https://github.com/progfolio/elpaca) as follows.  Note
that recipe changes only take effect after you do ‘M-x elpaca-delete’
and it re-clones – the idea is that Elpaca users will prefer to do it
manually.

     (use-package org-node
       :ensure ( :fetcher github :repo "meedstrom/org-node"
                 :branch "v1.6"))

   ...Elpaca can also target an exact version tag.  Package manager of
the future, it is:

     (use-package org-node
       :ensure ( :fetcher github :repo "meedstrom/org-node"
                 :tag "1.6.2"))

   With Straight (https://github.com/radian-software/straight.el):

     (use-package org-node
       :straight (org-node :type git :host github :repo "meedstrom/org-node"
                           :branch "v1.6"))


File: org-node.info,  Node: Appendix III Random tips,  Next: Appendix IV What are ROAM_REFS?,  Prev: Appendix II How to rollback,  Up: Appendix

5.3 Appendix III: Random tips
=============================

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+, then set this.

     (setq org-html-prefer-user-labels t)


File: org-node.info,  Node: Appendix IV What are ROAM_REFS?,  Prev: Appendix III Random tips,  Up: Appendix

5.4 Appendix IV: What are ‘ROAM_REFS’?
======================================

Here’s the start of one of my note files.  Note the ‘:ROAM_REFS:’ line.

     :PROPERTIES:
     :CREATED:  [2023-09-11 Mon 12:00]
     :ID:       3bf9opc0tik0
     :ROAM_REFS: https://www.greaterwrong.com/s/pFatcKW3JJhTSxqAF https://mindingourway.com/guilt/
     :END:
     #+filetags: :pub:
     #+options: toc:t
     #+title: Replacing Guilt

     Takeaways from Nate Soares' excellent "Replacing Guilt" series.

     ...

   An explanation: think of them as like IDs.  While org-node is built
around the ID property because it acts as a singular identifier, the
concept can be generalized.

   In another universe, ‘ROAM_REFS’ might have been called ‘EXTRA_IDS’
because in many ways it is just a list of additional IDs for the same
node.

   For performance reasons, not just any string of text is accepted – it
must have valid links per Org syntax, such as ‘[[https://gnu.org][GNU
Website]]’ or ‘https://gnu.org’.  That is because the org-mem
(https://github.com/meedstrom/org-mem) library searches for links anyway
in all body text, making it cheap to see after-the-fact where else this
same "extra ID" may have been mentioned, and generate a backlink!

   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".

* Menu:

* What's it actually used for?::
* Citations::


File: org-node.info,  Node: What's it actually used for?,  Next: Citations,  Up: Appendix IV What are ROAM_REFS?

5.4.1 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.


File: org-node.info,  Node: Citations,  Prev: What's it actually used for?,  Up: Appendix IV What are ROAM_REFS?

5.4.2 Citations
---------------

As a special case, citation keys such as "@ioannidis2005" also work in
‘ROAM_REFS’, corresponding to Org citations like
‘[cite:@ioannidis2005]’.



Tag Table:
Node: Top201
Node: What's all this1740
Node: What's a "node"?3278
Node: Benchmarks on my machine5372
Node: Features5917
Node: Setup8538
Node: Install8682
Node: An update broke things?10256
Node: Quick start10502
Node: Backlinks11147
Node: Backlink solution 1 displayed in a separate window11612
Node: Option 1A Reuse the org-roam buffer11969
Node: Option 1B Use the org-node-context buffer12459
Node: Backlink solution 2 Print inside the file13079
Node: Option 2A Automatic BACKLINKS property line14169
Node: Option 2B Automatic BACKLINKSEND drawer14726
Node: Option 2C Semi-automatic BACKLINKSEND drawer15384
Node: Misc17114
Node: Org-capture17527
Node: Exclude uninteresting nodes19373
Node: Missing completions?20282
Node: Completion-at-point21030
Node: Customize appearance21367
Node: Sort completions21902
Node: Lining up properties22561
Node: Grep23496
Node: Let org-open-at-point detect refs24424
Node: Limitation TRAMP25127
Node: Limitation Unique titles25558
Node: Limitation Org-ref26680
Node: Toolbox27843
Node: Experimental Node sequences32435
Node: What are node seqs?32961
Node: Appendix33756
Node: Appendix I Rosetta stone33978
Node: Appendix II How to rollback37859
Node: Appendix III Random tips39617
Node: Appendix IV What are ROAM_REFS?40082
Node: What's it actually used for?41772
Node: Citations42078

End Tag Table


Local Variables:
coding: utf-8
End:
