(docs): make explicit need to set org-roam-directory early (#946)

doc/org-roam.org

@@ -185,9 +185,11 @@ workflows. Org-roam does not magically make note-taking better -- this often
 requires a radical change in your current note-taking workflow. To understand
 more about the methods and madness, see [[*Note-taking Workflows][Note-taking Workflows]].
 
-To begin using Org-roam, one should set the =org-roam-directory= to the directory
+To first start using Org-roam, one needs to pick a location to store the
-containing your notes. For this tutorial, create an empty directory, and set the
+Org-roam files. The directory that will contain your notes, and database index
-=org-roam-directory=:
+is specified by the variable ~org-roam-directory~. This variable needs to be set
+before any calls to Org-roam functions, including enabling ~org-roam-mode~. For
+this tutorial, create an empty directory, and set ~org-roam-directory~:
 
 #+BEGIN_SRC emacs-lisp
 (make-directory "~/org-roam")
@@ -196,34 +198,34 @@ containing your notes. For this tutorial, create an empty directory, and set the
 
 We encourage using a flat hierarchy for storing notes, but some prefer using
 folders for storing specific kinds of notes (e.g. websites, papers). This is
-fine; Org-roam searches recursively within =org-roam-directory= for any notes.
+fine; Org-roam searches recursively within ~org-roam-directory~ for any notes.
 Instead of relying on the file hierarchy for any form of categorization, we
 solely rely on links between files to establish connections between notes.
 
-Next, we need to enable the global minor mode =org-roam-mode=. This sets up Emacs
+Next, we need to enable the global minor mode ~org-roam-mode~. This sets up Emacs
 with several hooks, builds a cache and keeps it consistent. We recommend
-starting =org-roam-mode= on startup:
+starting ~org-roam-mode~ on startup:
 
 #+BEGIN_SRC emacs-lisp
 (add-hook 'after-init-hook 'org-roam-mode)
 #+END_SRC
 
-To build the cache manually, one can run =M-x org-roam-db-build-cache=. The cache
+To build the cache manually, one can run ~M-x org-roam-db-build-cache~. The
-is a sqlite database named =org-roam.db=, which defaults to residing in the root
+cache is a sqlite database named ~org-roam.db~, which defaults to residing in
-=org-roam-directory=. Cache builds may take a while the first time, but is often
+the root ~org-roam-directory~. Cache builds may take a while the first time, but
-instantaneous in subsequent runs.
+is often instantaneous in subsequent runs.
 
-Let us now create our first note. Call =M-x org-roam-find-file=. This shows a list
+Let us now create our first note. Call ~M-x org-roam-find-file~. This shows a list
-of titles for notes that reside in =org-roam-directory=. It should show nothing
+of titles for notes that reside in ~org-roam-directory~. It should show nothing
 right now, since there are no notes in the directory. Entering the title of the
-note you wish to create, and pressing =RET= should begin the note creation
+note you wish to create, and pressing ~RET~ should begin the note creation
-process. This process uses =org-capture='s templating system, and can be freely
+process. This process uses ~org-capture~'s templating system, and can be freely
-customized (see [[*The Templating System][The Templating System]]). Using the default template, pressing =C-c
+customized (see [[*The Templating System][The Templating System]]). Using the default template, pressing ~C-c
-C-c= finishes the note capture. Running =M-x org-roam-find-file= again should show
+C-c~ finishes the note capture. Running ~M-x org-roam-find-file~ again should show
 the note you have created, and selecting that entry will bring you to that note.
 
 The crux of Org-roam is making it easy to create notes, and link them together.
-To link notes together, we call =M-x org-roam-insert=. This brings up a prompt
+To link notes together, we call ~M-x org-roam-insert~. This brings up a prompt
 with a list of title for existing notes. Selecting an existing entry will create
 and insert a link to the current file. Entering a non-existent title will create
 a new note with that title. Good usage of Org-roam requires liberally linking
@@ -232,7 +234,7 @@ notes.
 
 Org-roam provides an interface to view backlinks. It shows backlinks for the
 currently active Org-roam note, along with some surrounding context. To toggle
-the visibility of this buffer, call =M-x org-roam=.
+the visibility of this buffer, call ~M-x org-roam~.
 
 For a visual representation of the notes and their connections, Org-roam also
 provides graphing capabilities, using Graphviz. It generates graphs with notes
@@ -255,13 +257,13 @@ especially useful for topics or concepts with acronyms. For example, for a note
 like "World War 2", it may be desirable to also refer to it using the acronym
 "WWII".
 
-Org-roam calls =org-roam--extract-titles= to extract titles. It uses the
+Org-roam calls ~org-roam--extract-titles~ to extract titles. It uses the
-variable =org-roam-title-sources=, to control how the titles are extracted. The
+variable ~org-roam-title-sources~, to control how the titles are extracted. The
 title extraction methods supported are:
 
-1. ='title=: This extracts the title using the file =#+title= property
+1. ~'title~: This extracts the title using the file ~#+title~ property
-2. ='headline=: This extracts the title from the first headline in the Org file
+2. ~'headline~: This extracts the title from the first headline in the Org file
-3. ='alias=: This extracts a list of titles using the =#+roam_alias= property.
+3. ~'alias~: This extracts a list of titles using the ~#+roam_alias~ property.
    The aliases are space-delimited, and can be multi-worded using quotes
 
 Take for example the following org file:
@@ -275,19 +277,19 @@ Take for example the following org file:
 
 | Method      | Titles                   |
 |-------------+--------------------------|
-| ='title=    | '("World War 2")         |
+| ~'title~    | '("World War 2")         |
-| ='headline= | '("Headline")            |
+| ~'headline~ | '("Headline")            |
-| ='alias=    | '("WWII" "World War II") |
+| ~'alias~    | '("WWII" "World War II") |
 
 One can freely control which extraction methods to use by customizing
-=org-roam-title-sources=: see the doc-string for the variable for more
+~org-roam-title-sources~: see the doc-string for the variable for more
 information. If all methods of title extraction return no results, the file-name
 is used in place of the titles for completions.
 
 If you wish to add your own title extraction method, you may push a symbol
-='foo= into =org-roam-title-sources=, and define a
+~'foo~ into ~org-roam-title-sources~, and define a
-=org-roam--extract-titles-foo= which accepts no arguments. See
+~org-roam--extract-titles-foo~ which accepts no arguments. See
-=org-roam--extract-titles-title= for an example.
+~org-roam--extract-titles-title~ for an example.
 
 ** Tags
 
@@ -295,32 +297,32 @@ Tags are used as meta-data for files: they facilitate interactions with notes
 where titles are insufficient. For example, tags allow for categorization of
 notes: differentiating between bibliographical and structure notes during interactive commands.
 
-Org-roam calls =org-roam--extract-tags= to extract tags from files. It uses the
+Org-roam calls ~org-roam--extract-tags~ to extract tags from files. It uses the
-variable =org-roam-tag-sources=, to control how tags are extracted. The tag
+variable ~org-roam-tag-sources~, to control how tags are extracted. The tag
 extraction methods supported are:
 
-1. ='prop=: This extracts tags from the =#+roam_tags= property. Tags are space delimited, and can be multi-word using double quotes.
+1. ~'prop~: This extracts tags from the ~#+roam_tags~ property. Tags are space delimited, and can be multi-word using double quotes.
-2. ='all-directories=: All sub-directories relative to =org-roam-directory= are
+2. ~'all-directories~: All sub-directories relative to ~org-roam-directory~ are
    extracted as tags. That is, if a file is located at relative path
-   =foo/bar/file.org=, the file will have tags =foo= and =bar=.
+   ~foo/bar/file.org~, the file will have tags ~foo~ and ~bar~.
-3. ='last-directory=: Extracts the last directory relative to
+3. ~'last-directory~: Extracts the last directory relative to
-   =org-roam-directory= as the tag. That is, if a file is located at relative
+   ~org-roam-directory~ as the tag. That is, if a file is located at relative
-   path =foo/bar/file.org=, the file will have tag =bar=.
+   path ~foo/bar/file.org~, the file will have tag ~bar~.
-4. ='first-directory=: Extracts the first directory relative to
+4. ~'first-directory~: Extracts the first directory relative to
-   =org-roam-directory= as the tag. That is, if a file is located at relative
+   ~org-roam-directory~ as the tag. That is, if a file is located at relative
-   path =foo/bar/file.org=, the file will have tag =foo=.
+   path ~foo/bar/file.org~, the file will have tag ~foo~.
 
-By default, only the ='prop= extraction method is enabled. To enable the other
+By default, only the ~'prop~ extraction method is enabled. To enable the other
-extraction methods, you may modify =org-roam-tag-sources=:
+extraction methods, you may modify ~org-roam-tag-sources~:
 
 #+BEGIN_SRC emacs-lisp
 (setq org-roam-tag-sources '(prop last-directory))
 #+END_SRC
 
-If you wish to add your own tag extraction method, you may push a symbol ='foo=
+If you wish to add your own tag extraction method, you may push a symbol ~'foo~
-into =org-roam-tag-sources=, and define a =org-roam--extract-tags-foo= which
+into ~org-roam-tag-sources~, and define a ~org-roam--extract-tags-foo~ which
 accepts the absolute file path as its argument. See
-=org-roam--extract-tags-prop= for an example.
+~org-roam--extract-tags-prop~ for an example.
 
 ** File Refs
 
@@ -333,7 +335,7 @@ For example, a note for a website may contain a ref:
 #+END_SRC
 
 These keys come in useful for when taking website notes, using the
-=roam-ref= protocol (see [[*Roam Protocol][Roam Protocol]]).
+~roam-ref~ protocol (see [[*Roam Protocol][Roam Protocol]]).
 
 Alternatively, add a ref for notes for a specific paper, using its
 [[https://github.com/jkitchin/org-ref][org-ref]] citation key:
@@ -384,28 +386,28 @@ the default template, reproduced below.
        :unnarrowed t)
 #+END_SRC
 
-1. The template has short key ="d"=. If you have only one template,
+1. The template has short key ~"d"~. If you have only one template,
    org-roam automatically chooses this template for you.
-2. The template is given a description of ="default"=.
+2. The template is given a description of ~"default"~.
-3. =plain= text is inserted. Other options include Org headings via
+3. ~plain~ text is inserted. Other options include Org headings via
-   =entry=.
+   ~entry~.
-4. =(function org-roam--capture-get-point)= should not be changed.
+4. ~(function org-roam--capture-get-point)~ should not be changed.
-5. ="%?"= is the template inserted on each call to =org-roam-capture--capture=.
+5. ~"%?"~ is the template inserted on each call to ~org-roam-capture--capture~.
    This template means don't insert any content, but place the cursor
    here.
-6. =:file-name= is the file-name template for a new note, if it doesn't yet
+6. ~:file-name~ is the file-name template for a new note, if it doesn't yet
    exist. This creates a file at path that looks like
-   =/path/to/org-roam-directory/20200213032037-foo.org=. This template also
+   ~/path/to/org-roam-directory/20200213032037-foo.org~. This template also
    allows you to specify if you want the note to go into a subdirectory. For
-   example, the template =private/${slug}= will create notes in
+   example, the template ~private/${slug}~ will create notes in
-   =/path/to/org-roam-directory/private=.
+   ~/path/to/org-roam-directory/private~.
-7. =:head= contains the initial template to be inserted (once only), at
+7. ~:head~ contains the initial template to be inserted (once only), at
    the beginning of the file. Here, the title global attribute is
    inserted.
-8. =:unnarrowed t= tells org-capture to show the contents for the whole
+8. ~:unnarrowed t~ tells org-capture to show the contents for the whole
    file, rather than narrowing to just the entry.
 
-Other options you may want to learn about include =:immediate-finish=.
+Other options you may want to learn about include ~:immediate-finish~.
 
 ** Org-roam Template Expansion
 
@@ -413,26 +415,26 @@ Org-roam's template definitions also extend org-capture's template syntax, to
 allow prefilling of strings. We have seen a glimpse of this in [[*Template Walkthrough][Template
 Walkthrough]].
 
-In org-roam templates, the =${var}= syntax allows for the expansion of
+In org-roam templates, the ~${var}~ syntax allows for the expansion of
-variables, stored in =org-roam-capture--info=. For example, during
+variables, stored in ~org-roam-capture--info~. For example, during
-=org-roam-insert=, the user is prompted for a title. Upon entering a
+~org-roam-insert~, the user is prompted for a title. Upon entering a
-non-existent title, the =title= key in =org-roam-capture--info= is set to the
+non-existent title, the ~title~ key in ~org-roam-capture--info~ is set to the
-provided title. =${title}= is then expanded into the provided title during the
+provided title. ~${title}~ is then expanded into the provided title during the
 org-capture process. Any variables that do not contain strings, are prompted for
-values using =completing-read=.
+values using ~completing-read~.
 
 After doing this expansion, the org-capture's template expansion system
 is used to fill up the rest of the template. You may read up more on
 this on [[https://orgmode.org/manual/Template-expansion.html#Template-expansion][org-capture's documentation page]].
 
 To illustrate this dual expansion process, take for example the template string:
-="%<%Y%m%d%H%M%S>-${title}"=, with the title ="Foo"=. The template is first
+~"%<%Y%m%d%H%M%S>-${title}"~, with the title ~"Foo"~. The template is first
-expanded into =%<%Y%m%d%H%M%S>-Foo=. Then org-capture expands =%<%Y%m%d%H%M%S>=
+expanded into ~%<%Y%m%d%H%M%S>-Foo~. Then org-capture expands ~%<%Y%m%d%H%M%S>~
-with timestamp: e.g. =20200213032037-Foo=.
+with timestamp: e.g. ~20200213032037-Foo~.
 
 All of the flexibility afforded by Emacs and Org-mode are available. For
 example, if you want to encode a UTC timestamp in the filename, you can take
-advantage of org-mode's =%(EXP)= template expansion to call =format-time-string=
+advantage of org-mode's ~%(EXP)~ template expansion to call ~format-time-string~
 directly to provide its third argument to specify UTC.
 
 #+BEGIN_SRC emacs-lisp
@@ -449,7 +451,7 @@ the Org-roam codebase manageable. However, we attempt to accommodate as
 many usage styles as possible.
 
 All of Org-roam's customization options can be viewed via
-=M-x customize-group org-roam=.
+~M-x customize-group org-roam~.
 
 ** Directories and Files
 
@@ -474,39 +476,39 @@ The Org-roam buffer displays backlinks for the currently active Org-roam note.
 
 - User Option: org-roam-buffer
 
-  The name of the org-roam buffer. Defaults to =*org-roam*=.
+  The name of the org-roam buffer. Defaults to ~*org-roam*~.
 
 - User Option: org-roam-buffer-position
 
-  The position of the Org-roam buffer side window. Valid values are ='left=,
+  The position of the Org-roam buffer side window. Valid values are ~'left~,
-  ='right=, ='top=, ='bottom=.
+  ~'right~, ~'top~, ~'bottom~.
 
 - User Option: org-roam-buffer-width
 
-  Width of =org-roam-buffer=. Has an effect only if =org-roam-buffer-position= is
+  Width of ~org-roam-buffer~. Has an effect only if ~org-roam-buffer-position~ is
-  ='left= or ='right=.
+  ~'left~ or ~'right~.
 
 - User Option: org-roam-buffer-height
 
-  Height of =org-roam-buffer=. Has an effect only if =org-roam-buffer-position= is
+  Height of ~org-roam-buffer~. Has an effect only if ~org-roam-buffer-position~ is
-  ='top= or ='bottom=.
+  ~'top~ or ~'bottom~.
 
 - User Option: org-roam-buffer-no-delete-other-windows
 
-  The =no-delete-window= parameter for the org-roam buffer. Setting it to ='t= prevents the window from being deleted when calling =delete-other-windows=.
+  The ~no-delete-window~ parameter for the org-roam buffer. Setting it to ~'t~ prevents the window from being deleted when calling ~delete-other-windows~.
 
 ** Org-roam Links
 
-Org-roam links are regular =file:= links in Org-mode. By default, links are
+Org-roam links are regular ~file:~ links in Org-mode. By default, links are
-inserted with the title as the link description with =org-roam-insert=.
+inserted with the title as the link description with ~org-roam-insert~.
 
 - User Option: org-roam-link-title-format
 
   To distinguish between org-roam links and regular links, one may choose to use
-  special indicators for Org-roam links. Defaults to ="%s"=.
+  special indicators for Org-roam links. Defaults to ~"%s"~.
 
-  If your version of Org is at least =9.2=, consider styling the link differently,
+  If your version of Org is at least ~9.2~, consider styling the link differently,
-  by customizing the =org-roam-link=, and =org-roam-link-current= faces.
+  by customizing the ~org-roam-link~, and ~org-roam-link-current~ faces.
 
 ** Org-roam Files
 
@@ -521,27 +523,27 @@ As your collection grows, you might want to create an index where you keep links
 to your main files.
 
 In Org-roam, you can define the path to your index file by setting
-=org-roam-index-file=.
+~org-roam-index-file~.
 
 - Variable: org-roam-index-file
 
   Path to the Org-roam index file.
 
   The path can be a string or a function. If it is a string, it should be the
-  path (absolute or relative to =org-roam-directory=) to the index file. If it
+  path (absolute or relative to ~org-roam-directory~) to the index file. If it
   is is a function, the function should return the path to the index file.
-  Otherwise, the index is assumed to be a note in =org-roam-index= whose
+  Otherwise, the index is assumed to be a note in ~org-roam-index~ whose
-  title is ="Index"=.
+  title is ~"Index"~.
 
 - Function: org-roam-find-index
 
-  Opens the Index file in the current =org-roam-directory=.
+  Opens the Index file in the current ~org-roam-directory~.
 
 * Encryption
 
 One may wish to keep private, encrypted files. Org-roam supports encryption (via
-GPG), which can be enabled for all new files by setting =org-roam-encrypt-files=
+GPG), which can be enabled for all new files by setting ~org-roam-encrypt-files~
-to =t=. When enabled, new files are created with the =.org.gpg= extension and
+to ~t~. When enabled, new files are created with the ~.org.gpg~ extension and
 decryption are handled automatically by EasyPG.
 
 Note that Emacs will prompt for a password for encrypted files during
@@ -557,7 +559,7 @@ Org-roam provides graphing capabilities to explore interconnections between
 notes. This is done by performing SQL queries and generating images using
 [[https://graphviz.org/][Graphviz]]. The graph can also be navigated: see [[*Roam Protocol][Roam Protocol]].
 
-The entry point to graph creation is =org-roam-graph=.
+The entry point to graph creation is ~org-roam-graph~.
 
 - Function: org-roam-graph & optional arg file node-query
 
@@ -565,18 +567,18 @@ The entry point to graph creation is =org-roam-graph=.
   If FILE is nil, default to current buffer’s file name.
   ARG may be any of the following values:
 
-  - =nil=       show the graph.
+  - ~nil~       show the graph.
-  - =C-u=       show the graph for FILE.
+  - ~C-u~       show the graph for FILE.
-  - =C-u N=     show the graph for FILE limiting nodes to N steps.
+  - ~C-u N~     show the graph for FILE limiting nodes to N steps.
-  - =C-u C-u=   build the graph.
+  - ~C-u C-u~   build the graph.
-  - =C-u -=     build the graph for FILE.
+  - ~C-u -~     build the graph for FILE.
-  - =C-u -N=    build the graph for FILE limiting nodes to N steps.
+  - ~C-u -N~    build the graph for FILE limiting nodes to N steps.
 
 - User Option: org-roam-graph-executable
 
   Path to the graphing executable (in this case, Graphviz). Set this if Org-roam is unable to find the Graphviz executable on your system.
 
-  You may also choose to use =neato= in place of =dot=, which generates a more
+  You may also choose to use ~neato~ in place of ~dot~, which generates a more
   compact graph layout.
 
 - User Option: org-roam-graph-viewer
@@ -586,7 +588,7 @@ The entry point to graph creation is =org-roam-graph=.
   1. A string, which is a path to the program used
   2. a function accepting a single argument: the graph file path.
 
-  =nil= uses =view-file= to view the graph.
+  ~nil~ uses ~view-file~ to view the graph.
   
   If you are using WSL2 and would like to open the graph in Windows, you can use the second option to set the browser and network file path:
   
@@ -604,22 +606,22 @@ Graphviz provides many options for customizing the graph output, and Org-roam su
 - User Option: org-roam-graph-extra-config
 
   Extra options passed to graphviz for the digraph (The "G" attributes).
-  Example: ='=(("rankdir" . "LR"))=
+  Example: ~'~(("rankdir" . "LR"))~
 
 - User Option: org-roam-graph-node-extra-config
 
   Extra options for nodes in the graphviz output (The "N" attributes).
-  Example: ='(("color" . "skyblue"))=
+  Example: ~'(("color" . "skyblue"))~
 
 - User Option: org-roam-graph-edge-extra-config
 
   Extra options for edges in the graphviz output (The "E" attributes).
-  Example: ='(("dir" . "back"))=
+  Example: ~'(("dir" . "back"))~
 
 - User Option: org-roam-graph-edge-cites-extra-config
 
   Extra options for citation edges in the graphviz output.
-  Example: ='(("color" . "red"))=
+  Example: ~'(("color" . "red"))~
 
 ** Excluding Nodes and Edges
 
@@ -650,19 +652,19 @@ system is configurable. The default setting,
   (setq org-roam-completion-system 'default)
 #+END_SRC
 
-uses Emacs' standard =completing-read=. If you prefer
+uses Emacs' standard ~completing-read~. If you prefer
 [[https://emacs-helm.github.io/helm/][Helm]], use
 
 #+BEGIN_SRC emacs-lisp
   (setq org-roam-completion-system 'helm)
 #+END_SRC
 
-Other options include ='ido=, and ='ivy=.
+Other options include ~'ido~, and ~'ivy~.
 
 * Roam Protocol
 ** _ :ignore:
-Org-roam extending =org-protocol= with 2 protocols: the =roam-file=
+Org-roam extending ~org-protocol~ with 2 protocols: the ~roam-file~
-and =roam-ref= protocol.
+and ~roam-ref~ protocol.
 
 ** Installation
 
@@ -672,12 +674,12 @@ To enable Org-roam's protocol extensions, you have to add the following to your
 (require 'org-roam-protocol)
 #+END_SRC
 
-The instructions for setting up =org-protocol== are reproduced below.
+The instructions for setting up ~org-protocol~ are reproduced below.
 
-We will also need to create a desktop application for =emacsclient=. The
+We will also need to create a desktop application for ~emacsclient~. The
 instructions for various platforms are shown below.
 
-For Linux users, create a desktop application in =~/.local/share/applications/org-protocol.desktop=:
+For Linux users, create a desktop application in ~~/.local/share/applications/org-protocol.desktop~:
 
 #+begin_example
 [Desktop Entry]
@@ -689,7 +691,7 @@ Terminal=false
 MimeType=x-scheme-handler/org-protocol
 #+end_example
 
-Associate =org-protocol://= links with the desktop application by
+Associate ~org-protocol://~ links with the desktop application by
 running in your shell:
 
 #+BEGIN_SRC bash
@@ -697,7 +699,7 @@ xdg-mime default org-protocol.desktop x-scheme-handler/org-protocol
 #+END_SRC
 
 To disable the "confirm" prompt in Chrome, you can also make Chrome
-show a checkbox to tick, so that the =Org-Protocol Client= app will be used
+show a checkbox to tick, so that the ~Org-Protocol Client~ app will be used
 without confirmation. To do this, run in a shell:
 
 #+BEGIN_SRC bash
@@ -713,8 +715,8 @@ sudo chmod 644 /etc/opt/chrome/policies/managed/external_protocol_dialog.json
 and then restart Chrome (for example, by navigating to <chrome://restart>) to
 make the new policy take effect.
 
-See [[https://www.chromium.org/administrators/linux-quick-start][here]] for more info on the =/etc/opt/chrome/policies/managed= directory and
+See [[https://www.chromium.org/administrators/linux-quick-start][here]] for more info on the ~/etc/opt/chrome/policies/managed~ directory and
-[[https://cloud.google.com/docs/chrome-enterprise/policies/?policy=ExternalProtocolDialogShowAlwaysOpenCheckbox][here]] for information on the =ExternalProtocolDialogShowAlwaysOpenCheckbox= policy.
+[[https://cloud.google.com/docs/chrome-enterprise/policies/?policy=ExternalProtocolDialogShowAlwaysOpenCheckbox][here]] for information on the ~ExternalProtocolDialogShowAlwaysOpenCheckbox~ policy.
 
 For MacOS, one solution is to use [[https://github.com/sveinbjornt/Platypus][Platypus]]. Here are the instructions for
 setting up with Platypus and Chrome:
@@ -725,7 +727,7 @@ setting up with Platypus and Chrome:
 brew cask install platypus
 #+END_SRC
 
-2. Create a script =launch_emacs.sh=:
+2. Create a script ~launch_emacs.sh~:
 
 #+BEGIN_SRC bash
 #!/usr/bin/env bash
@@ -746,7 +748,7 @@ brew cask install platypus
 #+end_example
 
 
-Inside =Settings=:
+Inside ~Settings~:
 
 #+begin_example
 | Setting                        | Value          |
@@ -757,7 +759,7 @@ Inside =Settings=:
 #+end_example
 
 To disable the "confirm" prompt in Chrome, you can also make Chrome
-show a checkbox to tick, so that the =OrgProtocol= app will be used
+show a checkbox to tick, so that the ~OrgProtocol~ app will be used
 without confirmation. To do this, run in a shell:
 
 #+BEGIN_SRC bash
@@ -766,7 +768,7 @@ defaults write com.google.Chrome ExternalProtocolDialogShowAlwaysOpenCheckbox -b
 
 
 If you're using [[https://github.com/railwaycat/homebrew-emacsmacport][Emacs Mac Port]], it registered its `Emacs.app` as the default
-handler for the URL scheme `org-protocol`. To make =OrgProtocol.app=
+handler for the URL scheme `org-protocol`. To make ~OrgProtocol.app~
 the default handler instead, run:
 
 #+BEGIN_SRC bash
@@ -776,7 +778,7 @@ defaults write com.apple.LaunchServices/com.apple.launchservices.secure LSHandle
 
 Then restart your computer.
 
-For Windows, create a temporary =org-protocol.reg= file:
+For Windows, create a temporary ~org-protocol.reg~ file:
 
 #+BEGIN_SRC text
 REGEDIT4
@@ -798,13 +800,13 @@ The above will forward the protocol to WSL. If you run Emacs natively on Windows
 
 After executing the .reg file, the protocol is registered and you can delete the file.
 
-** The =roam-file= protocol
+** The roam-file protocol
 
-This is a simple protocol that opens the path specified by the =file=
+This is a simple protocol that opens the path specified by the ~file~
-key (e.g. =org-protocol://roam-file?file=/tmp/file.org=). This is used
+key (e.g. ~org-protocol://roam-file?file=/tmp/file.org~). This is used
 in the generated graph.
 
-** The =roam-ref= Protocol
+** The roam-ref protocol
 
 This protocol finds or creates a new note with a given ~roam_key~ (see [[*Anatomy of an Org-roam File][Anatomy of an Org-roam File]]):
 
@@ -837,15 +839,15 @@ should contain a ~#+roam_key: ${ref}~ in it.
 
 Org-roam provides a utility for diagnosing and repairing problematic files via
 ~org-roam-doctor~. By default, ~org-roam-doctor~ runs the check on the current
-Org-roam file. To run the check only for the current file, run =C-u M-x
+Org-roam file. To run the check only for the current file, run ~C-u M-x
-org-roam-doctor=, but note that this may take some time.
+org-roam-doctor~, but note that this may take some time.
 
 - Function: org-roam-doctor &optional this-buffer
 
   Perform a check on Org-roam files to ensure cleanliness. If THIS-BUFFER, run
   the check only for the current buffer.
 
-The checks run are defined in =org-roam-doctor--checkers=. Each checker is an instance of =org-roam-doctor-checker=. To define a checker, use =make-org-roam-doctor-checker=. Here is a sample definition:
+The checks run are defined in ~org-roam-doctor--checkers~. Each checker is an instance of ~org-roam-doctor-checker~. To define a checker, use ~make-org-roam-doctor-checker~. Here is a sample definition:
 
 #+BEGIN_SRC emacs-lisp
 (make-org-roam-doctor-checker
@@ -856,14 +858,14 @@ The checks run are defined in =org-roam-doctor--checkers=. Each checker is an in
                ("R" . ("Replace link (keep label)" . org-roam-doctor--replace-link-keep-label))))
 #+END_SRC
 
-The =:name= property is the name of the function run. The function takes in the
+The ~:name~ property is the name of the function run. The function takes in the
-Org parse tree, and returns a list of =(point error-message)=. =:description= is a
+Org parse tree, and returns a list of ~(point error-message)~. ~:description~ is a
-short description of what the checker does. =:actions= is an alist containing
+short description of what the checker does. ~:actions~ is an alist containing
-elements of the form =(char . (prompt . function))=. These actions are defined per
+elements of the form ~(char . (prompt . function))~. These actions are defined per
 checker, to perform autofixes for the errors. For each error detected,
-=org-roam-doctor= will move the point to the current error, and pop-up a help
+~org-roam-doctor~ will move the point to the current error, and pop-up a help
 window displaying the error message, as well as the list of actions that can be
-taken provided in =:actions=.
+taken provided in ~:actions~.
 * Performance Optimization
 ** TODO Profiling Key Operations
 ** Garbage Collection
@@ -949,7 +951,7 @@ for browsing and filtering org-roam notes.
 #+END_SRC
 
 If the title of the Org file is not the first line, you might not get
-nice titles. You may choose to patch this to use =org-roam='s
+nice titles. You may choose to patch this to use ~org-roam~'s
 functionality. Here I'm using
 [[https://github.com/raxod502/el-patch][el-patch]]:
 
@@ -989,7 +991,7 @@ that uses an external search engine and indexer.
    :END:
 
 [[https://github.com/bastibe/org-journal][Org-journal]] is a more
-powerful alternative to the simple function =org-roam-dailies-today=. It
+powerful alternative to the simple function ~org-roam-dailies-today~. It
 provides better journaling capabilities, and a nice calendar interface
 to see all dated entries.
 
@@ -1068,8 +1070,8 @@ etc.) within Org-mode.
 tight integration between
 [[https://github.com/jkitchin/org-ref][org-ref]],
 [[https://github.com/tmalsburg/helm-bibtex][helm-bibtex]] and
-=org-roam=. This helps you manage your bibliographic notes under
+~org-roam~. This helps you manage your bibliographic notes under
-=org-roam=.
+~org-roam~.
 
 **** Spaced Repetition
     :PROPERTIES:
@@ -1083,11 +1085,11 @@ files. Other alternatives include [[https://orgmode.org/worg/org-contrib/org-dri
 ** How do I have more than one Org-roam directory?
 
 Emacs supports directory-local variables, allowing the value of
-=org-roam-directory= to be different in different directories. It does this by
+~org-roam-directory~ to be different in different directories. It does this by
-checking for a file named =.dir-locals.el=.
+checking for a file named ~.dir-locals.el~.
 
-To add support for multiple directories, override the =org-roam-directory=
+To add support for multiple directories, override the ~org-roam-directory~
-variable using directory-local variables. This is what =.dir-locals.el= may
+variable using directory-local variables. This is what ~.dir-locals.el~ may
 contain:
 
 #+BEGIN_SRC emacs-lisp
@@ -1095,7 +1097,7 @@ contain:
 #+END_SRC
 
 All files within that directory will be treated as their own separate
-set of Org-roam files. Remember to run =org-roam-db-build-cache= from a
+set of Org-roam files. Remember to run ~org-roam-db-build-cache~ from a
 file within that directory, at least once.
 
 ** How do I migrate from Roam Research?

doc/org-roam.texi

@@ -122,8 +122,8 @@ Roam Protocol
 
 * _::
 * Installation: Installation (1). 
-* The @samp{roam-file} protocol::
+* The roam-file protocol::
-* The @samp{roam-ref} Protocol::
+* The roam-ref protocol::
 
 Performance Optimization
 
@@ -331,9 +331,11 @@ workflows. Org-roam does not magically make note-taking better -- this often
 requires a radical change in your current note-taking workflow. To understand
 more about the methods and madness, see @ref{Note-taking Workflows}.
 
-To begin using Org-roam, one should set the @samp{org-roam-directory} to the directory
+To first start using Org-roam, one needs to pick a location to store the
-containing your notes. For this tutorial, create an empty directory, and set the
+Org-roam files. The directory that will contain your notes, and database index
-@samp{org-roam-directory}:
+is specified by the variable @code{org-roam-directory}. This variable needs to be set
+before any calls to Org-roam functions, including enabling @code{org-roam-mode}. For
+this tutorial, create an empty directory, and set @code{org-roam-directory}:
 
 @lisp
 (make-directory "~/org-roam")
@@ -342,34 +344,34 @@ containing your notes. For this tutorial, create an empty directory, and set the
 
 We encourage using a flat hierarchy for storing notes, but some prefer using
 folders for storing specific kinds of notes (e.g. websites, papers). This is
-fine; Org-roam searches recursively within @samp{org-roam-directory} for any notes.
+fine; Org-roam searches recursively within @code{org-roam-directory} for any notes.
 Instead of relying on the file hierarchy for any form of categorization, we
 solely rely on links between files to establish connections between notes.
 
-Next, we need to enable the global minor mode @samp{org-roam-mode}. This sets up Emacs
+Next, we need to enable the global minor mode @code{org-roam-mode}. This sets up Emacs
 with several hooks, builds a cache and keeps it consistent. We recommend
-starting @samp{org-roam-mode} on startup:
+starting @code{org-roam-mode} on startup:
 
 @lisp
 (add-hook 'after-init-hook 'org-roam-mode)
 @end lisp
 
-To build the cache manually, one can run @samp{M-x org-roam-db-build-cache}. The cache
+To build the cache manually, one can run @code{M-x org-roam-db-build-cache}. The
-is a sqlite database named @samp{org-roam.db}, which defaults to residing in the root
+cache is a sqlite database named @code{org-roam.db}, which defaults to residing in
-@samp{org-roam-directory}. Cache builds may take a while the first time, but is often
+the root @code{org-roam-directory}. Cache builds may take a while the first time, but
-instantaneous in subsequent runs.
+is often instantaneous in subsequent runs.
 
-Let us now create our first note. Call @samp{M-x org-roam-find-file}. This shows a list
+Let us now create our first note. Call @code{M-x org-roam-find-file}. This shows a list
-of titles for notes that reside in @samp{org-roam-directory}. It should show nothing
+of titles for notes that reside in @code{org-roam-directory}. It should show nothing
 right now, since there are no notes in the directory. Entering the title of the
-note you wish to create, and pressing @samp{RET} should begin the note creation
+note you wish to create, and pressing @code{RET} should begin the note creation
-process. This process uses @samp{org-capture}'s templating system, and can be freely
+process. This process uses @code{org-capture}'s templating system, and can be freely
-customized (see @ref{The Templating System}). Using the default template, pressing @samp{C-c
+customized (see @ref{The Templating System}). Using the default template, pressing @code{C-c
-C-c} finishes the note capture. Running @samp{M-x org-roam-find-file} again should show
+C-c} finishes the note capture. Running @code{M-x org-roam-find-file} again should show
 the note you have created, and selecting that entry will bring you to that note.
 
 The crux of Org-roam is making it easy to create notes, and link them together.
-To link notes together, we call @samp{M-x org-roam-insert}. This brings up a prompt
+To link notes together, we call @code{M-x org-roam-insert}. This brings up a prompt
 with a list of title for existing notes. Selecting an existing entry will create
 and insert a link to the current file. Entering a non-existent title will create
 a new note with that title. Good usage of Org-roam requires liberally linking
@@ -378,7 +380,7 @@ notes.
 
 Org-roam provides an interface to view backlinks. It shows backlinks for the
 currently active Org-roam note, along with some surrounding context. To toggle
-the visibility of this buffer, call @samp{M-x org-roam}.
+the visibility of this buffer, call @code{M-x org-roam}.
 
 For a visual representation of the notes and their connections, Org-roam also
 provides graphing capabilities, using Graphviz. It generates graphs with notes
@@ -409,17 +411,17 @@ especially useful for topics or concepts with acronyms. For example, for a note
 like ``World War 2'', it may be desirable to also refer to it using the acronym
 ``WWII''.
 
-Org-roam calls @samp{org-roam--extract-titles} to extract titles. It uses the
+Org-roam calls @code{org-roam--extract-titles} to extract titles. It uses the
-variable @samp{org-roam-title-sources}, to control how the titles are extracted. The
+variable @code{org-roam-title-sources}, to control how the titles are extracted. The
 title extraction methods supported are:
 
 @enumerate
 @item
-@samp{'title}: This extracts the title using the file @samp{#+title} property
+@code{'title}: This extracts the title using the file @code{#+title} property
 @item
-@samp{'headline}: This extracts the title from the first headline in the Org file
+@code{'headline}: This extracts the title from the first headline in the Org file
 @item
-@samp{'alias}: This extracts a list of titles using the @samp{#+roam_alias} property.
+@code{'alias}: This extracts a list of titles using the @code{#+roam_alias} property.
 The aliases are space-delimited, and can be multi-worded using quotes
 @end enumerate
 
@@ -435,23 +437,23 @@ Take for example the following org file:
 @multitable {aaaaaaaaaaa} {aaaaaaaaaaaaaaaaaaaaaaaa}
 @headitem Method
 @tab Titles
-@item @samp{'title}
+@item @code{'title}
 @tab '(``World War 2'')
-@item @samp{'headline}
+@item @code{'headline}
 @tab '(``Headline'')
-@item @samp{'alias}
+@item @code{'alias}
 @tab '(``WWII'' ``World War II'')
 @end multitable
 
 One can freely control which extraction methods to use by customizing
-@samp{org-roam-title-sources}: see the doc-string for the variable for more
+@code{org-roam-title-sources}: see the doc-string for the variable for more
 information. If all methods of title extraction return no results, the file-name
 is used in place of the titles for completions.
 
 If you wish to add your own title extraction method, you may push a symbol
-@samp{'foo} into @samp{org-roam-title-sources}, and define a
+@code{'foo} into @code{org-roam-title-sources}, and define a
-@samp{org-roam--extract-titles-foo} which accepts no arguments. See
+@code{org-roam--extract-titles-foo} which accepts no arguments. See
-@samp{org-roam--extract-titles-title} for an example.
+@code{org-roam--extract-titles-title} for an example.
 
 @node Tags
 @section Tags
@@ -460,38 +462,38 @@ Tags are used as meta-data for files: they facilitate interactions with notes
 where titles are insufficient. For example, tags allow for categorization of
 notes: differentiating between bibliographical and structure notes during interactive commands.
 
-Org-roam calls @samp{org-roam--extract-tags} to extract tags from files. It uses the
+Org-roam calls @code{org-roam--extract-tags} to extract tags from files. It uses the
-variable @samp{org-roam-tag-sources}, to control how tags are extracted. The tag
+variable @code{org-roam-tag-sources}, to control how tags are extracted. The tag
 extraction methods supported are:
 
 @enumerate
 @item
-@samp{'prop}: This extracts tags from the @samp{#+roam_tags} property. Tags are space delimited, and can be multi-word using double quotes.
+@code{'prop}: This extracts tags from the @code{#+roam_tags} property. Tags are space delimited, and can be multi-word using double quotes.
 @item
-@samp{'all-directories}: All sub-directories relative to @samp{org-roam-directory} are
+@code{'all-directories}: All sub-directories relative to @code{org-roam-directory} are
 extracted as tags. That is, if a file is located at relative path
-@samp{foo/bar/file.org}, the file will have tags @samp{foo} and @samp{bar}.
+@code{foo/bar/file.org}, the file will have tags @code{foo} and @code{bar}.
 @item
-@samp{'last-directory}: Extracts the last directory relative to
+@code{'last-directory}: Extracts the last directory relative to
-@samp{org-roam-directory} as the tag. That is, if a file is located at relative
+@code{org-roam-directory} as the tag. That is, if a file is located at relative
-path @samp{foo/bar/file.org}, the file will have tag @samp{bar}.
+path @code{foo/bar/file.org}, the file will have tag @code{bar}.
 @item
-@samp{'first-directory}: Extracts the first directory relative to
+@code{'first-directory}: Extracts the first directory relative to
-@samp{org-roam-directory} as the tag. That is, if a file is located at relative
+@code{org-roam-directory} as the tag. That is, if a file is located at relative
-path @samp{foo/bar/file.org}, the file will have tag @samp{foo}.
+path @code{foo/bar/file.org}, the file will have tag @code{foo}.
 @end enumerate
 
-By default, only the @samp{'prop} extraction method is enabled. To enable the other
+By default, only the @code{'prop} extraction method is enabled. To enable the other
-extraction methods, you may modify @samp{org-roam-tag-sources}:
+extraction methods, you may modify @code{org-roam-tag-sources}:
 
 @lisp
 (setq org-roam-tag-sources '(prop last-directory))
 @end lisp
 
-If you wish to add your own tag extraction method, you may push a symbol @samp{'foo}
+If you wish to add your own tag extraction method, you may push a symbol @code{'foo}
-into @samp{org-roam-tag-sources}, and define a @samp{org-roam--extract-tags-foo} which
+into @code{org-roam-tag-sources}, and define a @code{org-roam--extract-tags-foo} which
 accepts the absolute file path as its argument. See
-@samp{org-roam--extract-tags-prop} for an example.
+@code{org-roam--extract-tags-prop} for an example.
 
 @node File Refs
 @section File Refs
@@ -505,7 +507,7 @@ For example, a note for a website may contain a ref:
 @end example
 
 These keys come in useful for when taking website notes, using the
-@samp{roam-ref} protocol (see @ref{Roam Protocol}).
+@code{roam-ref} protocol (see @ref{Roam Protocol}).
 
 Alternatively, add a ref for notes for a specific paper, using its
 @uref{https://github.com/jkitchin/org-ref, org-ref} citation key:
@@ -574,36 +576,36 @@ the default template, reproduced below.
 
 @enumerate
 @item
-The template has short key @samp{"d"}. If you have only one template,
+The template has short key @code{"d"}. If you have only one template,
 org-roam automatically chooses this template for you.
 @item
-The template is given a description of @samp{"default"}.
+The template is given a description of @code{"default"}.
 @item
-@samp{plain} text is inserted. Other options include Org headings via
+@code{plain} text is inserted. Other options include Org headings via
-@samp{entry}.
+@code{entry}.
 @item
-@samp{(function org-roam--capture-get-point)} should not be changed.
+@code{(function org-roam--capture-get-point)} should not be changed.
 @item
-@samp{"%?"} is the template inserted on each call to @samp{org-roam-capture--capture}.
+@code{"%?"} is the template inserted on each call to @code{org-roam-capture--capture}.
 This template means don't insert any content, but place the cursor
 here.
 @item
-@samp{:file-name} is the file-name template for a new note, if it doesn't yet
+@code{:file-name} is the file-name template for a new note, if it doesn't yet
 exist. This creates a file at path that looks like
-@samp{/path/to/org-roam-directory/20200213032037-foo.org}. This template also
+@code{/path/to/org-roam-directory/20200213032037-foo.org}. This template also
 allows you to specify if you want the note to go into a subdirectory. For
-example, the template @samp{private/$@{slug@}} will create notes in
+example, the template @code{private/$@{slug@}} will create notes in
-@samp{/path/to/org-roam-directory/private}.
+@code{/path/to/org-roam-directory/private}.
 @item
-@samp{:head} contains the initial template to be inserted (once only), at
+@code{:head} contains the initial template to be inserted (once only), at
 the beginning of the file. Here, the title global attribute is
 inserted.
 @item
-@samp{:unnarrowed t} tells org-capture to show the contents for the whole
+@code{:unnarrowed t} tells org-capture to show the contents for the whole
 file, rather than narrowing to just the entry.
 @end enumerate
 
-Other options you may want to learn about include @samp{:immediate-finish}.
+Other options you may want to learn about include @code{:immediate-finish}.
 
 @node Org-roam Template Expansion
 @section Org-roam Template Expansion
@@ -612,26 +614,26 @@ Org-roam's template definitions also extend org-capture's template syntax, to
 allow prefilling of strings. We have seen a glimpse of this in @ref{Template Walkthrough, , Template
 Walkthrough}.
 
-In org-roam templates, the @samp{$@{var@}} syntax allows for the expansion of
+In org-roam templates, the @code{$@{var@}} syntax allows for the expansion of
-variables, stored in @samp{org-roam-capture--info}. For example, during
+variables, stored in @code{org-roam-capture--info}. For example, during
-@samp{org-roam-insert}, the user is prompted for a title. Upon entering a
+@code{org-roam-insert}, the user is prompted for a title. Upon entering a
-non-existent title, the @samp{title} key in @samp{org-roam-capture--info} is set to the
+non-existent title, the @code{title} key in @code{org-roam-capture--info} is set to the
-provided title. @samp{$@{title@}} is then expanded into the provided title during the
+provided title. @code{$@{title@}} is then expanded into the provided title during the
 org-capture process. Any variables that do not contain strings, are prompted for
-values using @samp{completing-read}.
+values using @code{completing-read}.
 
 After doing this expansion, the org-capture's template expansion system
 is used to fill up the rest of the template. You may read up more on
 this on @uref{https://orgmode.org/manual/Template-expansion.html#Template-expansion, org-capture's documentation page}.
 
 To illustrate this dual expansion process, take for example the template string:
-@samp{"%<%Y%m%d%H%M%S>-$@{title@}"}, with the title @samp{"Foo"}. The template is first
+@code{"%<%Y%m%d%H%M%S>-$@{title@}"}, with the title @code{"Foo"}. The template is first
-expanded into @samp{%<%Y%m%d%H%M%S>-Foo}. Then org-capture expands @samp{%<%Y%m%d%H%M%S>}
+expanded into @code{%<%Y%m%d%H%M%S>-Foo}. Then org-capture expands @code{%<%Y%m%d%H%M%S>}
-with timestamp: e.g. @samp{20200213032037-Foo}.
+with timestamp: e.g. @code{20200213032037-Foo}.
 
 All of the flexibility afforded by Emacs and Org-mode are available. For
 example, if you want to encode a UTC timestamp in the filename, you can take
-advantage of org-mode's @samp{%(EXP)} template expansion to call @samp{format-time-string}
+advantage of org-mode's @code{%(EXP)} template expansion to call @code{format-time-string}
 directly to provide its third argument to specify UTC@.
 
 @lisp
@@ -650,7 +652,7 @@ the Org-roam codebase manageable. However, we attempt to accommodate as
 many usage styles as possible.
 
 All of Org-roam's customization options can be viewed via
-@samp{M-x customize-group org-roam}.
+@code{M-x customize-group org-roam}.
 
 @menu
 * Directories and Files::
@@ -690,47 +692,47 @@ The Org-roam buffer displays backlinks for the currently active Org-roam note.
 @item
 User Option: org-roam-buffer
 
-The name of the org-roam buffer. Defaults to @samp{*org-roam*}.
+The name of the org-roam buffer. Defaults to @code{*org-roam*}.
 
 @item
 User Option: org-roam-buffer-position
 
-The position of the Org-roam buffer side window. Valid values are @samp{'left},
+The position of the Org-roam buffer side window. Valid values are @code{'left},
-@samp{'right}, @samp{'top}, @samp{'bottom}.
+@code{'right}, @code{'top}, @code{'bottom}.
 
 @item
 User Option: org-roam-buffer-width
 
-Width of @samp{org-roam-buffer}. Has an effect only if @samp{org-roam-buffer-position} is
+Width of @code{org-roam-buffer}. Has an effect only if @code{org-roam-buffer-position} is
-@samp{'left} or @samp{'right}.
+@code{'left} or @code{'right}.
 
 @item
 User Option: org-roam-buffer-height
 
-Height of @samp{org-roam-buffer}. Has an effect only if @samp{org-roam-buffer-position} is
+Height of @code{org-roam-buffer}. Has an effect only if @code{org-roam-buffer-position} is
-@samp{'top} or @samp{'bottom}.
+@code{'top} or @code{'bottom}.
 
 @item
 User Option: org-roam-buffer-no-delete-other-windows
 
-The @samp{no-delete-window} parameter for the org-roam buffer. Setting it to @samp{'t} prevents the window from being deleted when calling @samp{delete-other-windows}.
+The @code{no-delete-window} parameter for the org-roam buffer. Setting it to @code{'t} prevents the window from being deleted when calling @code{delete-other-windows}.
 @end itemize
 
 @node Org-roam Links
 @section Org-roam Links
 
-Org-roam links are regular @samp{file:} links in Org-mode. By default, links are
+Org-roam links are regular @code{file:} links in Org-mode. By default, links are
-inserted with the title as the link description with @samp{org-roam-insert}.
+inserted with the title as the link description with @code{org-roam-insert}.
 
 @itemize
 @item
 User Option: org-roam-link-title-format
 
 To distinguish between org-roam links and regular links, one may choose to use
-special indicators for Org-roam links. Defaults to @samp{"%s"}.
+special indicators for Org-roam links. Defaults to @code{"%s"}.
 
-If your version of Org is at least @samp{9.2}, consider styling the link differently,
+If your version of Org is at least @code{9.2}, consider styling the link differently,
-by customizing the @samp{org-roam-link}, and @samp{org-roam-link-current} faces.
+by customizing the @code{org-roam-link}, and @code{org-roam-link-current} faces.
 @end itemize
 
 @node Org-roam Files
@@ -753,7 +755,7 @@ As your collection grows, you might want to create an index where you keep links
 to your main files.
 
 In Org-roam, you can define the path to your index file by setting
-@samp{org-roam-index-file}.
+@code{org-roam-index-file}.
 
 @itemize
 @item
@@ -762,23 +764,23 @@ Variable: org-roam-index-file
 Path to the Org-roam index file.
 
 The path can be a string or a function. If it is a string, it should be the
-path (absolute or relative to @samp{org-roam-directory}) to the index file. If it
+path (absolute or relative to @code{org-roam-directory}) to the index file. If it
 is is a function, the function should return the path to the index file.
-Otherwise, the index is assumed to be a note in @samp{org-roam-index} whose
+Otherwise, the index is assumed to be a note in @code{org-roam-index} whose
-title is @samp{"Index"}.
+title is @code{"Index"}.
 
 @item
 Function: org-roam-find-index
 
-Opens the Index file in the current @samp{org-roam-directory}.
+Opens the Index file in the current @code{org-roam-directory}.
 @end itemize
 
 @node Encryption
 @chapter Encryption
 
 One may wish to keep private, encrypted files. Org-roam supports encryption (via
-GPG), which can be enabled for all new files by setting @samp{org-roam-encrypt-files}
+GPG), which can be enabled for all new files by setting @code{org-roam-encrypt-files}
-to @samp{t}. When enabled, new files are created with the @samp{.org.gpg} extension and
+to @code{t}. When enabled, new files are created with the @code{.org.gpg} extension and
 decryption are handled automatically by EasyPG@.
 
 Note that Emacs will prompt for a password for encrypted files during
@@ -799,7 +801,7 @@ Org-roam provides graphing capabilities to explore interconnections between
 notes. This is done by performing SQL queries and generating images using
 @uref{https://graphviz.org/, Graphviz}. The graph can also be navigated: see @ref{Roam Protocol}.
 
-The entry point to graph creation is @samp{org-roam-graph}.
+The entry point to graph creation is @code{org-roam-graph}.
 
 @itemize
 @item
@@ -811,17 +813,17 @@ ARG may be any of the following values:
 
 @itemize
 @item
-@samp{nil}       show the graph.
+@code{nil}       show the graph.
 @item
-@samp{C-u}       show the graph for FILE@.
+@code{C-u}       show the graph for FILE@.
 @item
-@samp{C-u N}     show the graph for FILE limiting nodes to N steps.
+@code{C-u N}     show the graph for FILE limiting nodes to N steps.
 @item
-@samp{C-u C-u}   build the graph.
+@code{C-u C-u}   build the graph.
 @item
-@samp{C-u -}     build the graph for FILE@.
+@code{C-u -}     build the graph for FILE@.
 @item
-@samp{C-u -N}    build the graph for FILE limiting nodes to N steps.
+@code{C-u -N}    build the graph for FILE limiting nodes to N steps.
 @end itemize
 
 @item
@@ -829,7 +831,7 @@ User Option: org-roam-graph-executable
 
 Path to the graphing executable (in this case, Graphviz). Set this if Org-roam is unable to find the Graphviz executable on your system.
 
-You may also choose to use @samp{neato} in place of @samp{dot}, which generates a more
+You may also choose to use @code{neato} in place of @code{dot}, which generates a more
 compact graph layout.
 
 @item
@@ -844,7 +846,7 @@ A string, which is a path to the program used
 a function accepting a single argument: the graph file path.
 @end enumerate
 
-@samp{nil} uses @samp{view-file} to view the graph.
+@code{nil} uses @code{view-file} to view the graph.
 
 If you are using WSL2 and would like to open the graph in Windows, you can use the second option to set the browser and network file path:
 
@@ -871,25 +873,25 @@ Graphviz provides many options for customizing the graph output, and Org-roam su
 User Option: org-roam-graph-extra-config
 
 Extra options passed to graphviz for the digraph (The ``G'' attributes).
-Example: @samp{'=(("rankdir" . "LR"))}
+Example: @code{'~(("rankdir" . "LR"))}
 
 @item
 User Option: org-roam-graph-node-extra-config
 
 Extra options for nodes in the graphviz output (The ``N'' attributes).
-Example: @samp{'(("color" . "skyblue"))}
+Example: @code{'(("color" . "skyblue"))}
 
 @item
 User Option: org-roam-graph-edge-extra-config
 
 Extra options for edges in the graphviz output (The ``E'' attributes).
-Example: @samp{'(("dir" . "back"))}
+Example: @code{'(("dir" . "back"))}
 
 @item
 User Option: org-roam-graph-edge-cites-extra-config
 
 Extra options for citation edges in the graphviz output.
-Example: @samp{'(("color" . "red"))}
+Example: @code{'(("color" . "red"))}
 @end itemize
 
 @node Excluding Nodes and Edges
@@ -926,14 +928,14 @@ system is configurable. The default setting,
 (setq org-roam-completion-system 'default)
 @end lisp
 
-uses Emacs' standard @samp{completing-read}. If you prefer
+uses Emacs' standard @code{completing-read}. If you prefer
 @uref{https://emacs-helm.github.io/helm/, Helm}, use
 
 @lisp
 (setq org-roam-completion-system 'helm)
 @end lisp
 
-Other options include @samp{'ido}, and @samp{'ivy}.
+Other options include @code{'ido}, and @code{'ivy}.
 
 @node Roam Protocol
 @chapter Roam Protocol
@@ -941,15 +943,15 @@ Other options include @samp{'ido}, and @samp{'ivy}.
 @menu
 * _::
 * Installation: Installation (1). 
-* The @samp{roam-file} protocol::
+* The roam-file protocol::
-* The @samp{roam-ref} Protocol::
+* The roam-ref protocol::
 @end menu
 
 @node _
 @section _ :ignore:
 
-Org-roam extending @samp{org-protocol} with 2 protocols: the @samp{roam-file}
+Org-roam extending @code{org-protocol} with 2 protocols: the @code{roam-file}
-and @samp{roam-ref} protocol.
+and @code{roam-ref} protocol.
 
 @node Installation (1)
 @section Installation
@@ -960,12 +962,12 @@ To enable Org-roam's protocol extensions, you have to add the following to your
 (require 'org-roam-protocol)
 @end lisp
 
-The instructions for setting up @samp{org-protocol=} are reproduced below.
+The instructions for setting up @code{org-protocol} are reproduced below.
 
-We will also need to create a desktop application for @samp{emacsclient}. The
+We will also need to create a desktop application for @code{emacsclient}. The
 instructions for various platforms are shown below.
 
-For Linux users, create a desktop application in @samp{~/.local/share/applications/org-protocol.desktop}:
+For Linux users, create a desktop application in @code{~/.local/share/applications/org-protocol.desktop}:
 
 @example
 [Desktop Entry]
@@ -977,7 +979,7 @@ Terminal=false
 MimeType=x-scheme-handler/org-protocol
 @end example
 
-Associate @samp{org-protocol://} links with the desktop application by
+Associate @code{org-protocol://} links with the desktop application by
 running in your shell:
 
 @example
@@ -985,7 +987,7 @@ xdg-mime default org-protocol.desktop x-scheme-handler/org-protocol
 @end example
 
 To disable the ``confirm'' prompt in Chrome, you can also make Chrome
-show a checkbox to tick, so that the @samp{Org-Protocol Client} app will be used
+show a checkbox to tick, so that the @code{Org-Protocol Client} app will be used
 without confirmation. To do this, run in a shell:
 
 @example
@@ -1001,8 +1003,8 @@ sudo chmod 644 /etc/opt/chrome/policies/managed/external_protocol_dialog.json
 and then restart Chrome (for example, by navigating to <chrome://restart>) to
 make the new policy take effect.
 
-See @uref{https://www.chromium.org/administrators/linux-quick-start, here} for more info on the @samp{/etc/opt/chrome/policies/managed} directory and
+See @uref{https://www.chromium.org/administrators/linux-quick-start, here} for more info on the @code{/etc/opt/chrome/policies/managed} directory and
-@uref{https://cloud.google.com/docs/chrome-enterprise/policies/?policy=ExternalProtocolDialogShowAlwaysOpenCheckbox, here} for information on the @samp{ExternalProtocolDialogShowAlwaysOpenCheckbox} policy.
+@uref{https://cloud.google.com/docs/chrome-enterprise/policies/?policy=ExternalProtocolDialogShowAlwaysOpenCheckbox, here} for information on the @code{ExternalProtocolDialogShowAlwaysOpenCheckbox} policy.
 
 For MacOS, one solution is to use @uref{https://github.com/sveinbjornt/Platypus, Platypus}. Here are the instructions for
 setting up with Platypus and Chrome:
@@ -1018,7 +1020,7 @@ brew cask install platypus
 
 @enumerate
 @item
-Create a script @samp{launch_emacs.sh}:
+Create a script @code{launch_emacs.sh}:
 @end enumerate
 
 @example
@@ -1043,7 +1045,7 @@ Create a Platypus app with the following settings:
 @end example
 
 
-Inside @samp{Settings}:
+Inside @code{Settings}:
 
 @example
 | Setting                        | Value          |
@@ -1054,7 +1056,7 @@ Inside @samp{Settings}:
 @end example
 
 To disable the ``confirm'' prompt in Chrome, you can also make Chrome
-show a checkbox to tick, so that the @samp{OrgProtocol} app will be used
+show a checkbox to tick, so that the @code{OrgProtocol} app will be used
 without confirmation. To do this, run in a shell:
 
 @example
@@ -1063,7 +1065,7 @@ defaults write com.google.Chrome ExternalProtocolDialogShowAlwaysOpenCheckbox -b
 
 
 If you're using @uref{https://github.com/railwaycat/homebrew-emacsmacport, Emacs Mac Port}, it registered its `Emacs.app` as the default
-handler for the URL scheme `org-protocol`. To make @samp{OrgProtocol.app}
+handler for the URL scheme `org-protocol`. To make @code{OrgProtocol.app}
 the default handler instead, run:
 
 @example
@@ -1073,7 +1075,7 @@ defaults write com.apple.LaunchServices/com.apple.launchservices.secure LSHandle
 
 Then restart your computer.
 
-For Windows, create a temporary @samp{org-protocol.reg} file:
+For Windows, create a temporary @code{org-protocol.reg} file:
 
 @example
 REGEDIT4
@@ -1095,15 +1097,15 @@ The above will forward the protocol to WSL@. If you run Emacs natively on Window
 
 After executing the .reg file, the protocol is registered and you can delete the file.
 
-@node The @samp{roam-file} protocol
+@node The roam-file protocol
-@section The @samp{roam-file} protocol
+@section The roam-file protocol
 
-This is a simple protocol that opens the path specified by the @samp{file}
+This is a simple protocol that opens the path specified by the @code{file}
-key (e.g. @samp{org-protocol://roam-file?file=/tmp/file.org}). This is used
+key (e.g. @code{org-protocol://roam-file?file=/tmp/file.org}). This is used
 in the generated graph.
 
-@node The @samp{roam-ref} Protocol
+@node The roam-ref protocol
-@section The @samp{roam-ref} Protocol
+@section The roam-ref protocol
 
 This protocol finds or creates a new note with a given @code{roam_key} (see @ref{Anatomy of an Org-roam File}):
 
@@ -1138,7 +1140,7 @@ should contain a @code{#+roam_key: $@{ref@}} in it.
 
 Org-roam provides a utility for diagnosing and repairing problematic files via
 @code{org-roam-doctor}. By default, @code{org-roam-doctor} runs the check on the current
-Org-roam file. To run the check only for the current file, run @samp{C-u M-x
+Org-roam file. To run the check only for the current file, run @code{C-u M-x
 org-roam-doctor}, but note that this may take some time.
 
 @itemize
@@ -1149,7 +1151,7 @@ Perform a check on Org-roam files to ensure cleanliness. If THIS-BUFFER, run
 the check only for the current buffer.
 @end itemize
 
-The checks run are defined in @samp{org-roam-doctor--checkers}. Each checker is an instance of @samp{org-roam-doctor-checker}. To define a checker, use @samp{make-org-roam-doctor-checker}. Here is a sample definition:
+The checks run are defined in @code{org-roam-doctor--checkers}. Each checker is an instance of @code{org-roam-doctor-checker}. To define a checker, use @code{make-org-roam-doctor-checker}. Here is a sample definition:
 
 @lisp
 (make-org-roam-doctor-checker
@@ -1160,14 +1162,14 @@ The checks run are defined in @samp{org-roam-doctor--checkers}. Each checker is
                ("R" . ("Replace link (keep label)" . org-roam-doctor--replace-link-keep-label))))
 @end lisp
 
-The @samp{:name} property is the name of the function run. The function takes in the
+The @code{:name} property is the name of the function run. The function takes in the
-Org parse tree, and returns a list of @samp{(point error-message)}. @samp{:description} is a
+Org parse tree, and returns a list of @code{(point error-message)}. @code{:description} is a
-short description of what the checker does. @samp{:actions} is an alist containing
+short description of what the checker does. @code{:actions} is an alist containing
-elements of the form @samp{(char . (prompt . function))}. These actions are defined per
+elements of the form @code{(char . (prompt . function))}. These actions are defined per
 checker, to perform autofixes for the errors. For each error detected,
-@samp{org-roam-doctor} will move the point to the current error, and pop-up a help
+@code{org-roam-doctor} will move the point to the current error, and pop-up a help
 window displaying the error message, as well as the list of actions that can be
-taken provided in @samp{:actions}.
+taken provided in @code{:actions}.
 
 @node Performance Optimization
 @chapter Performance Optimization
@@ -1282,7 +1284,7 @@ for browsing and filtering org-roam notes.
 @end lisp
 
 If the title of the Org file is not the first line, you might not get
-nice titles. You may choose to patch this to use @samp{org-roam}'s
+nice titles. You may choose to patch this to use @code{org-roam}'s
 functionality. Here I'm using
 @uref{https://github.com/raxod502/el-patch, el-patch}:
 
@@ -1320,7 +1322,7 @@ that uses an external search engine and indexer.
 @subsection Org-journal
 
 @uref{https://github.com/bastibe/org-journal, Org-journal} is a more
-powerful alternative to the simple function @samp{org-roam-dailies-today}. It
+powerful alternative to the simple function @code{org-roam-dailies-today}. It
 provides better journaling capabilities, and a nice calendar interface
 to see all dated entries.
 
@@ -1401,8 +1403,8 @@ etc.) within Org-mode.
 tight integration between
 @uref{https://github.com/jkitchin/org-ref, org-ref},
 @uref{https://github.com/tmalsburg/helm-bibtex, helm-bibtex} and
-@samp{org-roam}. This helps you manage your bibliographic notes under
+@code{org-roam}. This helps you manage your bibliographic notes under
-@samp{org-roam}.
+@code{org-roam}.
 
 @node Spaced Repetition
 @unnumberedsubsubsec Spaced Repetition
@@ -1422,11 +1424,11 @@ files. Other alternatives include @uref{https://orgmode.org/worg/org-contrib/org
 @section How do I have more than one Org-roam directory?
 
 Emacs supports directory-local variables, allowing the value of
-@samp{org-roam-directory} to be different in different directories. It does this by
+@code{org-roam-directory} to be different in different directories. It does this by
-checking for a file named @samp{.dir-locals.el}.
+checking for a file named @code{.dir-locals.el}.
 
-To add support for multiple directories, override the @samp{org-roam-directory}
+To add support for multiple directories, override the @code{org-roam-directory}
-variable using directory-local variables. This is what @samp{.dir-locals.el} may
+variable using directory-local variables. This is what @code{.dir-locals.el} may
 contain:
 
 @lisp
@@ -1434,7 +1436,7 @@ contain:
 @end lisp
 
 All files within that directory will be treated as their own separate
-set of Org-roam files. Remember to run @samp{org-roam-db-build-cache} from a
+set of Org-roam files. Remember to run @code{org-roam-db-build-cache} from a
 file within that directory, at least once.
 
 @node How do I migrate from Roam Research?