Deploying to gh-pages from @ aee3467b3e 🚀

org-roam.texi

@@ -25,13 +25,13 @@ General Public License for more details.
 
 @dircategory Emacs
 @direntry
-* Org-roam: (org-roam). Rudimentary Roam Replica for Emacs.
+* Org-roam: (org-roam). Roam Research for Emacs.
 @end direntry
 
 @finalout
 @titlepage
 @title Org-roam User Manual
-@subtitle for version 1.2.3
+@subtitle for version 2.0.0
 @author Jethro Kuan
 @page
 @vskip 0pt plus 1filll
@@ -44,10 +44,10 @@ General Public License for more details.
 
 @noindent
 
-This manual is for Org-roam version 1.2.3.
+This manual is for Org-roam version 2.0.0.
 
 @quotation
-Copyright (C) 2020-2020 Jethro Kuan <jethrokuan95@@gmail.com>
+Copyright (C) 2020-2021 Jethro Kuan <jethrokuan95@@gmail.com>
 
 You can redistribute this document and/or modify it under the terms of the GNU
 General Public License as published by the Free Software Foundation, either
@@ -67,13 +67,24 @@ General Public License for more details.
 * A Brief Introduction to the Zettelkasten Method::
 * Installation::
 * Getting Started::
-* Files::
+* Viewing the links::
+* Node Properties::
+* The Org-roam Buffer::
+* Styling Org-roam::
+* Completion::
+* Encryption::
+* Org-roam protocol::
+* Diagnosing and Repair::
+* Building Extensions::
+* The Org-mode Ecosystem::
+* Frequently Asked Questions::
+* Developer's Guide to Org-roam::
 * The Templating System::
 * Concepts and Configuration::
 * Inserting Links::
 * Completions::
 * Navigating Around::
-* Encryption::
+* Encryption: Encryption (1). 
 * Graphing::
 * Minibuffer Completion::
 * Roam Protocol::
@@ -91,31 +102,33 @@ General Public License for more details.
 @detailmenu
 --- The Detailed Node Listing ---
 
-A Brief Introduction to the Zettelkasten Method
-
-* Fleeting notes::
-* Permanent notes::
-
 Installation
 
 * Installing from MELPA::
 * Installing from Apt::
-* Installing from the Git Repository::
+* Installing from Source::
 * Post-Installation Tasks::
 
-Files
+Getting Started
 
-* File Titles::
+* The Org-roam Node::
-* File Tags::
+* Links between Nodes::
-* File Refs::
+* Setting up Org-roam::
+* Creating and Linking Nodes::
 
-File Titles
+Node Properties
 
-* Customizing Title Extraction::
+* Standard Org properties::
+* Aliases::
+* Refs::
 
-File Tags
+Building Extensions
 
-* Customizing Tag Extraction::
+* Public Interface::
+
+Developer's Guide to Org-roam
+
+* Org-roam's Design Principles::
 
 The Templating System
 
@@ -125,10 +138,9 @@ The Templating System
 Concepts and Configuration
 
 * Directories and Files::
-* The Org-roam Buffer::
+* The Org-roam Buffer: The Org-roam Buffer (1). 
 * Org-roam Files::
 * Org-roam Faces::
-* The Database::
 
 Completions
 
@@ -198,28 +210,24 @@ FAQ
 @node Introduction
 @chapter Introduction
 
-Org-roam is a tool for network thought. It reproduces some of @uref{https://roamresearch.com/, Roam
+Org-roam is a tool for networked thought. It reproduces some of @uref{https://roamresearch.com/, Roam
-Research's} @footnote{To understand more about Roam, a collection of links are available in @ref{Note-taking Workflows}.} features within the all-powerful @uref{https://orgmode.org/, Org-mode}.
+Research's} @footnote{To understand more about Roam, a collection of links are available in @ref{Note-taking Workflows}.} key features within @uref{https://orgmode.org/, Org-mode}.
 
-Org-roam is a solution for effortless non-hierarchical note-taking with
+Org-roam allows for effortless non-hierarchical note-taking: with Org-roam,
-Org-mode. With Org-roam, notes flow naturally, making note-taking fun and easy.
+notes flow naturally, making note-taking fun and easy. Org-roam augments the
-Org-roam keeps closely to Org syntax, and will work for anyone already using
+Org-mode syntax, and will work for anyone already using Org-mode for their
-Org-mode for their personal wiki.
+personal wiki.
 
-Org-roam gains its superpowers by leveraging the mature ecosystem around
+Org-roam leverages the mature ecosystem around Org-mode. For example, it has
-Org-mode. For example, it has first-class support for @uref{https://github.com/jkitchin/org-ref, org-ref} for citation
+first-class support for @uref{https://github.com/jkitchin/org-ref, org-ref} for citation management, and is able to
-management.
+piggyback off Org's excellent @LaTeX{} and source-block evaluation capabilities.
 
-Org-roam aims to implement the core features of Roam, leveraging the
+Org-roam provides these benefits over other tooling:
-mature ecosystem around Org-mode where possible. Eventually, we hope
-to further introduce features enabled by the Emacs ecosystem.
-
-Org-roam provides several benefits over other tooling:
 
 @itemize
 @item
-@strong{Privacy and Security:} Keep your personal wiki entirely offline and in your
+@strong{Privacy and Security:} Your personal wiki belongs only to you, entirely
-control. Encrypt your notes with GPG@.
+offline and in your control. Encrypt your notes with GPG@.
 
 @item
 @strong{Longevity of Plain Text:} Unlike web solutions like Roam Research, the notes
@@ -235,13 +243,13 @@ you feel unhappy with any part of Org-roam, you may choose to extend Org-roam,
 or open a pull request.
 
 @item
-@strong{Leverage the Org-mode ecosystem:} Over the years, Emacs and Org-mode has
+@strong{Leverage the Org-mode ecosystem:} Over the decades, Emacs and Org-mode has
 developed into a mature system for plain-text organization. Building upon
 Org-mode already puts Org-roam light-years ahead of many other solutions.
 
 @item
-@strong{Built on Emacs:} Emacs is also a fantastic interface for editing text, and we
+@strong{Built on Emacs:} Emacs is also a fantastic interface for editing text, and
-can inherit many of the powerful text-navigation and editing packages
+Org-roam inherits many of the powerful text-navigation and editing packages
 available to Emacs.
 @end itemize
 
@@ -249,18 +257,18 @@ available to Emacs.
 @chapter Target Audience
 
 Org-roam is a tool that will appear unfriendly to anyone unfamiliar with Emacs
-and Org-mode, but is also extremely powerful to those willing to put effort in
+and Org-mode, but it is also extremely powerful to those willing to put effort
-mastering the intricacies of the tools. Org-roam stands on the shoulders on
+inn mastering the intricacies. Org-roam stands on the shoulders of giants. Emacs
-giants. Emacs was first created in 1976, and remains a top tier tool for editing
+was first created in 1976, and remains the tool of choice for many for editing
 text and designing textual interfaces. The malleability of Emacs allowed the
 creation of Org-mode, an all-purpose plain-text system for maintaining TODO
 lists, planning projects, and authoring documents. Both of these tools are
 incredibly vast and require significant time investment to master.
 
-Org-roam assumes basic familiarity with these tools. It is not difficult to get
+Org-roam assumes only basic familiarity with these tools. It is not difficult to
-up and running with basic text-editing functionality, but one will only fully
+get up and running with basic text-editing functionality, but one will only
-appreciate the power of building Roam functionality into Emacs and Org-mode when
+fully appreciate the power of building Roam functionality into Emacs and
-the usage of these tools become more advanced.
+Org-mode when the usage of these tools become more advanced.
 
 One key advantage to Org-roam is that building on top of Emacs gives it
 malleability. This is especially important for note-taking workflows. It is our
@@ -313,13 +321,7 @@ plain-text, Org-mode file. In the same way one would maintain a paper slip-box,
 Org-roam makes it easy to create new zettels, pre-filling boilerplate content
 using a powerful templating system.
 
-@menu
+@strong{Fleeting notes}
-* Fleeting notes::
-* Permanent notes::
-@end menu
-
-@node Fleeting notes
-@section Fleeting notes
 
 A slip-box requires a method for quickly capturing ideas. These are called
 @strong{fleeting notes}: they are simple reminders of information or ideas that will
@@ -328,8 +330,7 @@ need to be processed later on, or trashed. This is typically accomplished using
 functionality (see @ref{Daily-notes}). This provides a central inbox for collecting
 thoughts, to be processed later into permanent notes.
 
-@node Permanent notes
+@strong{Permanent notes}
-@section Permanent notes
 
 Permanent notes are further split into two categories: @strong{literature notes} and
 @strong{concept notes}. Literature notes can be brief annotations on a particular
@@ -338,6 +339,9 @@ Concept notes require much more care in authoring: they need to be
 self-explanatory and detailed. Org-roam's templating system supports the
 addition of different templates to facilitate the creation of these notes.
 
+For further reading on the Zettelkasten method, ``How to Take Smart Notes'' by
+Sonke Ahrens is a decent guide.
+
 @node Installation
 @chapter Installation
 
@@ -347,7 +351,7 @@ development repository.
 @menu
 * Installing from MELPA::
 * Installing from Apt::
-* Installing from the Git Repository::
+* Installing from Source::
 * Post-Installation Tasks::
 @end menu
 
@@ -416,8 +420,8 @@ apt-get install elpa-org-roam
 
 Org-roam will then be autoloaded into Emacs.
 
-@node Installing from the Git Repository
+@node Installing from Source
-@section Installing from the Git Repository
+@section Installing from Source
 
 You may install Org-roam directly from the repository on @uref{https://github.com/org-roam/org-roam, GitHub} if you like.
 This will give you access to the latest version hours or days before it appears
@@ -520,18 +524,19 @@ install-info /path/to/my/info/files/org-roam.info /path/to/my/info/files/dir
 @node Post-Installation Tasks
 @section Post-Installation Tasks
 
-Org-roam uses @code{emacsql-sqlite3}, which requires @code{sqlite3} to be located on
+Org-roam requires @code{sqlite3} to be locatable by Emacs (i.e. on @code{exec-path}).
-@code{exec-path}. Please ensure that @code{sqlite3} is installed appropriately on your
+Please ensure that @code{sqlite3} is installed appropriately on your operating
-operating system. You can verify that this is the case by executing:
+system. You can verify that this is the case by executing @footnote{Two easy ways to evaluate elisp: 1) Place the cursor after the closing
+paren and run @samp{M-x eval-last-sexp RET} or 2) Press @samp{C-c C-c} with your cursor in
+an Org file code block (like @samp{#+BEGIN_SRC emacs-lisp}).}:
 
 @lisp
 (executable-find "sqlite3")
 @end lisp
 
 If you have @code{sqlite3} installed, and @code{executable-find} still reports @code{nil}, then
-it is likely that the path to the executable is not a member of the Emacs
+the path to the executable is not a member of the Emacs variable @code{exec-path}.
-variable @code{exec-path}. You may rectify this by manually adding the path within
+Rectify this by manually adding the path within your Emacs configuration:
-your Emacs configuration:
 
 @lisp
 (add-to-list 'exec-path "path/to/sqlite3")
@@ -540,283 +545,145 @@ your Emacs configuration:
 @node Getting Started
 @chapter Getting Started
 
-This short tutorial describes the essential commands used in Org-roam, to help
+@menu
-you get started.
+* The Org-roam Node::
+* Links between Nodes::
+* Setting up Org-roam::
+* Creating and Linking Nodes::
+@end menu
 
-First, it is important to understand how Org-roam was designed. Org-roam was
+@node The Org-roam Node
-built to support a workflow that was not possible with vanilla Org-mode. This
+@section The Org-roam Node
-flow is modelled after the @uref{https://zettelkasten.de/, Zettelkasten Method}, and many of @uref{https://roamresearch.com, Roam Research's}
+
-workflows. Org-roam does not magically make note-taking better -- this often
+We first begin with some terminology we'll use throughout the manual. We term
-requires a radical change in your current note-taking workflow. To understand
+the basic denomination in Org-roam a node. We define a node as follows:
-more about the methods and madness, see @ref{Note-taking Workflows}.
+
+@quotation
+A node is any headline or top level file with an ID@.
+
+@end quotation
+
+For example, with this example file content:
+
+@example
+:PROPERTIES:
+:ID:       foo
+:END:
+#+title: Foo
+
+* Bar
+:PROPERTIES:
+:ID:       bar
+:END:
+@end example
+
+We create two nodes:
+
+@itemize
+@item
+A file node ``Foo'' with id @code{foo}.
+
+@item
+A headline node ``Bar'' with id @code{bar}.
+@end itemize
+
+Headlines without IDs will not be considered Org-roam nodes. Org IDs can be
+added to files or headlines via the interactive command @code{M-x org-id-get-create}.
+
+@node Links between Nodes
+@section Links between Nodes
+
+We link between nodes using Org's standard ID link (e.g. @code{id:foo}). While only
+ID links will be considered during the computation of links between nodes,
+Org-roam caches all other links in the documents for external use.
+
+@node Setting up Org-roam
+@section Setting up Org-roam
+
+Org-roam's capabilities stem from its aggressive caching: it crawls all files
+within @code{org-roam-directory}, keeping a cache of all its links and nodes, while
+making sure that the cache is consistent.
 
 To first start using Org-roam, one needs to pick a location to store the
 Org-roam files. The directory that will contain your notes is specified by the
-variable @code{org-roam-directory}. This variable needs to be set before any calls to
+variable @code{org-roam-directory}. Org-roam searches recursively within
-Org-roam functions, including enabling @code{org-roam-mode}. For this tutorial,
+@code{org-roam-directory} for notes. This variable needs to be set before any calls
-create an empty directory, and set @code{org-roam-directory}:
+to Org-roam functions. For this tutorial, create an empty directory, and set
+@code{org-roam-directory}:
 
 @lisp
 (make-directory "~/org-roam")
 (setq org-roam-directory "~/org-roam")
 @end lisp
 
-We encourage using a flat hierarchy for storing notes, but some prefer using
+Next, we need to setup Org-roam to maintain cache consistency. This is achieved
-folders for storing specific kinds of notes (e.g. websites, papers). This is
+by running @code{M-x org-roam-setup}. To ensure that Org-roam is available on
-fine; Org-roam searches recursively within @code{org-roam-directory} for notes.
+startup, one can place this in their Emacs configuration:
-Instead of relying on the file hierarchy for any form of categorization, one
-should use links between files to establish connections between notes.
-
-Next, we need to enable the global minor mode @code{org-roam-mode}. This sets up
-Emacs with several hooks, building a cache that is kept consistent as your
-slip-box grows. We recommend starting @code{org-roam-mode} on startup:
 
 @lisp
-(add-hook 'after-init-hook 'org-roam-mode)
+(require 'org-roam)
+(org-roam-setup)
 @end lisp
 
 To build the cache manually, one can run @code{M-x org-roam-db-build-cache}. Cache
 builds may take a while the first time, but is often instantaneous in subsequent
 runs because it only reprocesses modified files.
 
-Let us now create our first note. Call @code{M-x org-roam-find-file}. This shows a
+@node Creating and Linking Nodes
-list of titles for notes that reside in @code{org-roam-directory}. It should show
+@section @strong{TODO} Creating and Linking Nodes
-nothing right now, since there are no notes in the directory. Entering the title
+
-of the note you wish to create, and pressing @code{RET} should begin the note
+Org-roam makes it easy to create notes and link them together. There are 2 main
+functions for creating nodes:
+
+@itemize
+@item
+@code{org-roam-node-insert}: creates a node if it does not exist, and inserts a
+link to the node at point.
+
+@item
+@code{org-roam-node-find}: creates a node if it does not exist, and visits the
+node.
+@end itemize
+
+Let's first try @code{org-roam-node-find}. Calling @code{M-x org-roam-node-find} will
+show a list of titles for nodes that reside in @code{org-roam-directory}. It should
+show nothing right now, since there are no notes in the directory. Enter the
+title of the note you wish to create, and press @code{RET}. This begins the note
 creation process. This process uses @code{org-capture}'s templating system, and can
 be customized (see @ref{The Templating System}). Using the default template, pressing
 @code{C-c C-c} finishes the note capture.
 
-By default, Org-roam updates the cache asynchronously in the background to
+Now that we have a node, we can try inserting a link to the node using @code{M-x
-avoid getting in the way of writing. Org-roam queues updates to the files,
+org-roam-node-insert}. This brings up the list of nodes, which should contain
-waits for you to be idle for 2 seconds, and then automatically triggers
+the node you just created. Selecting the node will insert an @code{id:} link to the
-updating the cache. After the cache has been updated, running @code{M-x
+node. If you instead entered a title that does not exist, you will once again be
-org-roam-find-file} again should show the note you have created, and selecting
+brought through the node creation process. To enable link auto-completion,
-that entry will bring you to that note @footnote{Depending on your completion framework, you may need to press TAB to
+see @ref{Completion}.
-see the list.}. One can customize the waiting
-time by setting @code{org-roam-db-update-idle-seconds}; or change the cache update
-to be triggered immediately after buffer save by setting
-@code{org-roam-db-update-method} to @code{'immediate}.
 
-For experienced @code{org-capture} users, the behavior of @code{M-x org-roam-find-file} 
+@node Viewing the links
-may seem unfamiliar: after finishing a capture with @code{C-c C-c}, you are returned  
+@chapter @strong{TODO} Viewing the links
-not to the original buffer from which you called @code{M-x org-roam-find-file}, but 
-to a buffer pointing to the note you just created. For the usual @code{org-capture} 
-behavior you can call @code{M-x org-roam-capture} instead of @code{M-x org-roam-find-file}. 
 
-Org-roam makes it easy to create notes, and link them together. To link notes
+Org-roam provides an interface to view relationships with other notes
-together, we call @code{M-x org-roam-insert}. This brings up a prompt with a list of
+(backlinks, reference links, unlinked references etc.). To pop up this info
-title for existing notes. Selecting an existing entry will create and insert a
+buffer, call @code{M-x org-roam-buffer}.
-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 files: this
-facilitates building up a dense graph of inter-connected notes.
 
-Org-roam provides an interface to view backlinks. It shows backlinks for the
+@node Node Properties
-currently active Org-roam note, along with some surrounding context. To toggle
+@chapter @strong{TODO} Node Properties
-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
-as nodes, and links between them as edges. The generated graph can be used to
-navigate to the files, but this requires some additional setup (see @ref{Roam Protocol}).
-
-@node Files
-@chapter Files
-
-In Org-roam, notes typically consist of multiple files, where each file is a
-zettel.
-
-While the bulk of Org-roam's functionality is built on top of vanilla Org-mode,
-Org-roam adds several Org-roam-specific keywords to support additional
-functionality.
-
-This section explains the important components of a file, and the extensions to
-Org-mode.
 
 @menu
-* File Titles::
+* Standard Org properties::
-* File Tags::
+* Aliases::
-* File Refs::
+* Refs::
 @end menu
 
-@node File Titles
+@node Standard Org properties
-@section File Titles
+@section @strong{TODO} Standard Org properties
 
-To easily find a note, a title needs to be prescribed to a note.
+@node Aliases
+@section @strong{TODO} Aliases
 
-A note can have many titles: this allows a note to be referred to by different
+@node Refs
-names, which is especially useful for topics or concepts with acronyms. For
+@section @strong{TODO} Refs
-example, for a note like ``World War 2'', it may be desirable to also refer to it
-using the acronym ``WWII''.
-
-Org-roam calls @code{org-roam--extract-titles} to extract titles. It uses the
-variable @code{org-roam-title-sources}, to control how the titles are extracted. The
-title extraction methods supported are:
-
-@itemize
-@item
-@code{'title}: This extracts the title using the file @code{#+title} property
-
-@item
-@code{'headline}: This extracts the title from the first headline in the Org file
-
-@item
-@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 itemize
-
-Take for example the following org file:
-
-@example
-#+title: World War 2
-#+roam_alias: "WWII" "World War II"
-
-* Headline
-@end example
-
-@multitable {aaaaaaaaaaa} {aaaaaaaaaaaaaaaaaaaaaaaa}
-@headitem Method
-@tab Titles
-@item @code{'title}
-@tab '(``World War 2'')
-@item @code{'headline}
-@tab '(``Headline'')
-@item @code{'alias}
-@tab '(``WWII'' ``World War II'')
-@end multitable
-
-If no title is provided, Org-roam defaults to using the file-path.
-
-@menu
-* Customizing Title Extraction::
-@end menu
-
-@node Customizing Title Extraction
-@subsection Customizing Title Extraction
-
-To control how Org-roam extracts titles, customize @code{org-roam-title-sources}. If
-all methods of title extraction return no results, the file-name is used as the
-note's title.
-
-@defopt org-roam-title-sources
-
-The list of sources from which to retrieve a note title.
-Each element in the list is either:
-@end defopt
-
-@itemize
-@item
-a symbol -- this symbol corresponds to a title retrieval function, which
-returns the list of titles for the current buffer
-@itemize
-@item
-a list of symbols -- symbols in the list are treated as with (1). The
-return value of this list is the first symbol in the list returning a
-non-nil value.
-@end itemize
-
-The return results of the root list are concatenated.
-
-For example the setting: '((title headline) alias) means the following:
-
-@itemize
-@item
-Return the 'title + 'alias, if the title of current buffer is non-empty;
-
-@item
-Or return 'headline + 'alias otherwise.
-@end itemize
-
-The currently supported symbols are:
-
-@code{'title}
-The @code{#+title} property of org file.
-
-@code{'alias}
-The @code{#+roam_alias} property of the org file, using
-space-delimited strings.
-
-@code{'headline}
-The first headline in the org file.
-@end itemize
-
-Adding your own title extraction method requires two steps. First, define a
-method @code{(defun org-roam--extract-titles-foo () ...)}, where @code{foo} a
-self-prescribed name for the title extraction method. This method takes no
-arguments, and returns a list of strings (titles). Finally, push the symbol
-@code{foo} into @code{org-roam-title-sources}. You may need to rebuild the cache from
-scratch to re-process all files to pick up the new titles.
-
-@node File Tags
-@section File Tags
-
-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.
-
-By default, tags are extracted from the @code{#+roam_tags} property. To add
-additional extraction methods, see @ref{Customizing Tag Extraction}.
-
-@menu
-* Customizing Tag Extraction::
-@end menu
-
-@node Customizing Tag Extraction
-@subsection Customizing Tag Extraction
-
-Org-roam calls @code{org-roam--extract-tags} to extract tags from files. The variable
-@code{org-roam-tag-sources}, to control how tags are extracted.
-
-@defopt org-roam-tag-sources
-@end defopt
-
-Sources to obtain tags from.
-
-It should be a list of symbols representing any of the following extraction
-methods:
-
-@code{'prop}
-  Extract tags from the @code{#+roam_tags} property.
-  Tags are space delimited.
-  Tags may contain spaces if they are double-quoted.
-  e.g. @code{#+roam_tags: TAG "tag with spaces"}
-
-@code{'vanilla}
-  Extract vanilla org-mode tags, including @code{#+FILETAGS} and
-  inherited tags.
-
-@code{'all-directories}
-  Extract sub-directories relative to @code{org-roam-directory}.
-  That is, if a file is located at relative path foo/bar/file.org,
-  the file will have tags ``foo'' and ``bar''.
-
-@code{'last-directory}
-  Extract the last directory relative to `org-roam-directory'.
-  That is, if a file is located at relative path foo/bar/file.org,
-  the file will have tag \``bar\''.
-
-@code{'first-directory}
-  Extract the first directory relative to @code{org-roam-directory}.
-  That is, if a file is located at relative path foo/bar/file.org,
-  the file will have tag ``foo''
-
-By default, only the @code{'prop} extraction method is enabled. To enable the other
-extraction methods, you may modify @code{org-roam-tag-sources}, for example:
-
-@lisp
-(setq org-roam-tag-sources '(prop last-directory))
-@end lisp
-
-Adding your own tag extraction method requires two steps. First, define a method
-@code{(defun org-roam--extract-tags-foo (file) ...)}, where @code{foo} a self-prescribed
-name for the tag extraction method. This method takes the file path as an
-argument, and returns a list of strings (titles). Finally, push the symbol @code{foo}
-into @code{org-roam-tag-sources}. You may need to rebuild the cache from scratch to
-re-process all files to pick up the new tags.
-
-@node File Refs
-@section File Refs
 
 Refs are unique identifiers for files. For example, a note for a website may
 contain a ref:
@@ -849,6 +716,159 @@ You may assign multiple refs to a single file, for example when you want
 multiple papers in a series to share the same note, or an article has a citation
 key and a URL at the same time.
 
+@node The Org-roam Buffer
+@chapter @strong{TODO} The Org-roam Buffer
+
+@node Styling Org-roam
+@chapter @strong{TODO} Styling Org-roam
+
+@node Completion
+@chapter @strong{TODO} Completion
+
+@node Encryption
+@chapter @strong{TODO} Encryption
+
+@node Org-roam protocol
+@chapter @strong{TODO} Org-roam protocol
+
+@node Diagnosing and Repair
+@chapter @strong{TODO} Diagnosing and Repair
+
+@node Building Extensions
+@chapter @strong{TODO} Building Extensions
+
+@menu
+* Public Interface::
+@end menu
+
+@node Public Interface
+@section @strong{TODO} Public Interface
+
+Database (for developers)
+@itemize
+@item
+querying: (org-roam-db-query)
+
+@item
+updating full database: (org-roam-db-sync)
+
+@item
+update current file: (org-roam-db-update-file)
+
+@item
+remove file from database: (org-roam-db-clear-file)
+@end itemize
+
+Nodes:
+@itemize
+@item
+List all nodes
+
+@item
+Read a node in from completion
+
+@item
+Get node at point
+@end itemize
+
+Links:
+@itemize
+@item
+Get backlinks for node
+@end itemize
+
+Tags:
+@itemize
+@item
+Add tag to node
+
+@item
+delete tag for node
+
+@item
+Get tags for node
+@end itemize
+
+Aliases:
+@itemize
+@item
+Add alias to node
+
+@item
+Delete alias for node
+
+@item
+Get aliases for node
+@end itemize
+
+Ref:
+@itemize
+@item
+Add ref to node
+@end itemize
+
+Capture:
+
+Navigation:
+@itemize
+@item
+Find or create a node
+@end itemize
+
+@node The Org-mode Ecosystem
+@chapter @strong{TODO} The Org-mode Ecosystem
+
+@node Frequently Asked Questions
+@chapter @strong{TODO} Frequently Asked Questions
+
+@node Developer's Guide to Org-roam
+@chapter @strong{TODO} Developer's Guide to Org-roam
+
+@menu
+* Org-roam's Design Principles::
+@end menu
+
+@node Org-roam's Design Principles
+@section Org-roam's Design Principles
+
+Org-roam is primarily motivated by the need for a dual representation. We
+(humans) love operating in a plain-text environment. The syntax rules of
+Org-mode are simple and fit snugly within our brain. This also allows us to use
+the tools and packages we love to explore and edit our notes. Org-mode is simply
+the most powerful plain-text format available, with support for images, @LaTeX{},
+TODO planning and much more.
+
+But this plain-text format is simply ill-suited for exploration of these notes:
+plain-text is simply not amenable for answering large-scale, complex queries
+(e.g. how many tasks do I have that are due by next week?). Interfaces such as
+Org-agenda slow to a crawl when the number of files becomes unwieldy, which
+can quickly become the case.
+
+At its core, Org-roam provides a database abstraction layer, providing a dual
+representation of what's already available in plain-text. This allows us
+(humans) to continue working with plain-text, while programs can utilize the
+database layer to perform complex queries. These capabilities include, but are
+not limited to:
+
+@itemize
+@item
+link graph traversal and visualization
+
+@item
+Instantaneous SQL-like queries on headlines
+@itemize
+@item
+What are my TODOs, scheduled for X, or due by Y@?
+@end itemize
+@end itemize
+
+All of these functionality is powered by this database abstraction layer. Hence,
+at its core Org-roam's primary goal is to provide a resilient dual
+representation that is cheap to maintain, easy to understand, and is as
+up-to-date as it possibly can. Org-roam also then exposes an API to this
+database abstraction layer for users who would like to perform programmatic
+queries on their Org files.
+
 @node The Templating System
 @chapter The Templating System
 
@@ -918,7 +938,7 @@ The template is given a description of @code{"default"}.
 @code{(function org-roam--capture-get-point)} should not be changed.
 
 @item
-@code{"%?"} is the template inserted on each call to @code{org-roam-capture--capture}.
+@code{"%?"} is the template inserted on each call to @code{org-roam-capture-}.
 This template means don't insert any content, but place the cursor here.
 
 @item
@@ -990,10 +1010,9 @@ org-roam}.
 
 @menu
 * Directories and Files::
-* The Org-roam Buffer::
+* The Org-roam Buffer: The Org-roam Buffer (1). 
 * Org-roam Files::
 * Org-roam Faces::
-* The Database::
 @end menu
 
 @node Directories and Files
@@ -1021,7 +1040,7 @@ with multiple Org-roam instances.
 Files matching this regular expression are excluded from the Org-roam.
 @end defvar
 
-@node The Org-roam Buffer
+@node The Org-roam Buffer (1)
 @section The Org-roam Buffer
 
 The Org-roam buffer displays backlinks for the currently active Org-roam note.
@@ -1086,27 +1105,6 @@ The @code{org-roam-link-current} face corresponds to links to the same file it i
 The @code{org-roam-link-invalid} face is applied to links that are broken. These are
 links to files or IDs that cannot be found.
 
-@node The Database
-@section @strong{TODO} The Database
-
-Org-roam is backed by a Sqlite database.
-
-@defopt org-roam-db-update-method
-
-Method to update the Org-roam database.
-
-@code{'immediate}: Update the database immediately upon file changes.
-
-@code{'idle-timer}: Updates the database if dirty, if Emacs idles for
-@code{org-roam-db-update-idle-seconds}.
-@end defopt
-
-@defopt org-roam-db-update-idle-seconds
-
-Number of idle seconds before triggering an Org-roam database update. This is
-only valid if @code{org-roam-db-update-method} is @code{'idle-timer}.
-@end defopt
-
 @node Inserting Links
 @chapter Inserting Links
 
@@ -1194,7 +1192,7 @@ represents the cursor:
 @code{[[|]]}: completes for a file title
 
 @item
-@code{[[roam:]]}: completes for a file title
+@code{[[roam:|]]}: completes for a file title
 
 @item
 @code{[[*|]]}: completes for a headline within this file
@@ -1206,6 +1204,9 @@ represents the cursor:
 @code{[[roam:foo*|]]} completes a headline within the file with title ``foo''
 @end itemize
 
+If you don't see the literal display of your links like the above examples,
+call @code{M-x org-toggle-link-display}
+
 Completions account for the current input. For example, for @code{[[f|]]}, the
 completions (by default) only show for files with titles that start with ``f''.
 
@@ -1279,7 +1280,7 @@ title is @code{"Index"}.
 Opens the Index file in the current @code{org-roam-directory}.
 @end defun
 
-@node Encryption
+@node Encryption (1)
 @chapter Encryption
 
 One may wish to keep private, encrypted files. Org-roam supports encryption (via
@@ -1617,7 +1618,7 @@ in the generated graph.
 @node The roam-ref protocol
 @section The roam-ref protocol
 
-This protocol finds or creates a new note with a given @code{roam_key} (see @ref{Files}):
+This protocol finds or creates a new note with a given @code{roam_key}:
 
 @image{images/roam-ref,,,,gif}
 
@@ -1720,7 +1721,7 @@ template @code{j} will put its notes under the heading ‘Journal’.
 
 Create an entry in the daily note for today.
 
-When @code{goto} is non-nil, go the note without creating an entry.
+When @code{goto} is non-nil, go to the note without creating an entry.
 @end defun
 
 @defun @code{org-roam-dailies-find-today}
@@ -1986,22 +1987,6 @@ using @uref{https://github.com/raxod502/el-patch, el-patch}:
 
 (eval-when-compile
   (require 'el-patch))
-
-(use-package deft
-  ;; same as above...
-  :config/el-patch
-  (defun deft-parse-title (file contents)
-    "Parse the given FILE and CONTENTS and determine the title.
-If `deft-use-filename-as-title' is nil, the title is taken to
-be the first non-empty line of the FILE.  Else the base name of the FILE is
-used as title."
-    (el-patch-swap (if deft-use-filename-as-title
-                       (deft-base-filename file)
-                     (let ((begin (string-match "^.+$" contents)))
-                       (if begin
-                           (funcall deft-parse-title-function
-                                    (substring contents begin (match-end 0))))))
-                   (org-roam-db--get-title file))))
 @end lisp
 
 The Deft interface can slow down quickly when the number of files get huge.
@@ -2105,6 +2090,9 @@ file with the right @samp{#+roam_key}.
 @uref{https://www.leonrische.me/fc/index.html, Org-fc} is a spaced repetition system that scales well with a large number of
 files. Other alternatives include @uref{https://orgmode.org/worg/org-contrib/org-drill.html, org-drill}, and @uref{https://github.com/abo-abo/pamparam, pamparam}.
 
+To use Anki for spaced repetition, @uref{https://github.com/louietan/anki-editor, anki-editor} allows you to write your cards in
+Org-mode, and sync your cards to Anki via @uref{https://github.com/FooSoft/anki-connect#installation, anki-connect}.
+
 @node FAQ
 @chapter FAQ