From f4539ac2e68adc46f301872be6e8bccdf7536520 Mon Sep 17 00:00:00 2001 From: jethrokuan Date: Fri, 13 Nov 2020 05:18:05 +0000 Subject: [PATCH] =?UTF-8?q?Deploying=20to=20gh-pages=20from=20=20@=20eaf99?= =?UTF-8?q?cba03f3c4a116bc460aca10798e9d7bcb1e=20=F0=9F=9A=80?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- manual.html | 162 ++++++++++++++++++++++++++------------------------ org-roam.org | 158 ++++++++++++++++++++++++------------------------ org-roam.texi | 155 ++++++++++++++++++++++++----------------------- 3 files changed, 241 insertions(+), 234 deletions(-) diff --git a/manual.html b/manual.html index 4504092..726cc37 100644 --- a/manual.html +++ b/manual.html @@ -292,16 +292,17 @@ Next: , P

1 Introduction

-

Org-roam is a Roam Research replica built around the -all-powerful Org-mode. +

Org-roam is a tool for network thought. It reproduces some of Roam +Research’s 1 features within the all-powerful Org-mode.

-

Org-roam is a solution for effortless non-hierarchical note-taking -with Org-mode. With Org-roam, notes flow naturally, making note-taking -fun and easy. Org-roam should also work as a plug-and-play solution -for anyone already using Org-mode for their personal wiki. +

Org-roam is a solution for effortless non-hierarchical note-taking with +Org-mode. With Org-roam, notes flow naturally, making note-taking fun and easy. +Org-roam keeps closely to Org syntax, and will work for anyone already using +Org-mode for their personal wiki.

-

To understand more about Roam, a collection of links are available in -Note-taking Workflows. +

Org-roam gains its superpowers by leveraging the mature ecosystem around +Org-mode. For example, it has first-class support for org-ref for citation +management.

Org-roam aims to implement the core features of Roam, leveraging the mature ecosystem around Org-mode where possible. Eventually, we hope @@ -310,25 +311,25 @@ to further introduce features enabled by the Emacs ecosystem.

Org-roam provides several benefits over other tooling:

@@ -386,30 +387,32 @@ Next: , Previou aims to provide a brief introduction to the “slip-box”, or “Zettelkasten” method. By providing some background on the method, we hope that the design decisions of Org-roam will become clear, and that will aid in using Org-roam -appropriately. In this section we will also introduce terms commonly used within -the Zettelkasten community, which will also commonly appear in the Org-roam -forums and channels of discussion. +appropriately. In this section we will introduce terms commonly used within the +Zettelkasten community and the Org-roam forums.

-

The Zettelkasten method of note-taking is designed to increase research -productivity: in particular, it acts as a research partner, where conversations -with it may produce new and surprising lines of thought. This method is -attributed to German sociologist Niklas Luhmann, who using the method had -produced volumes of written works. +

The Zettelkasten is a personal tool for thinking and writing. It places heavy +emphasis on connecting ideas, building up a web of thought. Hence, it is well +suited for knowledge workers and intellectual tasks, such as conducting +research. The Zettelkasten can act as a research partner, where conversations +with it may produce new and surprising lines of thought.

-

In its paper form, the slip-box is simply a box of cards. These cards are small -– often only large enough to fit a single concept. The size limitation -encourages ideas to be broken down into individual concepts. These ideas are -explicitly linked together. The breakdown of ideas encourages tangential -exploration of ideas, increasing the surface for thought. Making linking -explicit between notes also encourages one to think about the connections -between concepts. +

This method is attributed to German sociologist Niklas Luhmann, who using the +method had produced volumes of written works. Luhmann’s slip-box was simply a +box of cards. These cards are small – often only large enough to fit a single +concept. The size limitation encourages ideas to be broken down into individual +concepts. These ideas are explicitly linked together. The breakdown of ideas +encourages tangential exploration of ideas, increasing the surface for thought. +Making linking explicit between notes also encourages one to think about the +connections between concepts. +

+

At the corner of each note, Luhmann ascribed each note with an ordered ID, +allowing him to link and jump between notes. In Org-roam, we simply use +hyperlinks.

Org-roam is the slip-box, digitalized in Org-mode. Every zettel (card) is a -plain-text, Org-mode file. These files are often placed in the same directory. -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. Org-roam also facilitates the linking of zettels using Org-mode file: -links. +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.

• Fleeting notes:   @@ -427,7 +430,7 @@ Next: , U

3.1 Fleeting notes

-

A slip-box requires a method of quickly capturing ideas. These are called +

A slip-box requires a method for quickly capturing ideas. These are called fleeting notes: they are simple reminders of information or ideas that will need to be processed later on, or trashed. This is typically accomplished using org-capture (see (org)capture), or using Org-roam’s daily notes @@ -602,8 +605,7 @@ dependencies that it requires. These include:

You can install this manually as well, or get the latest version from MELPA. You -may wish to use use-package, straight.el, or some other tool or tools to help -manage this. +may wish to use use-package, straight.el to help manage this.

If you would like to install the manual for access from Emacs’ built-in Info system, you’ll need to compile the .texi source file, and install it in an @@ -693,10 +695,10 @@ requires a radical change in your current note-taking workflow. To understand more about the methods and madness, see Note-taking Workflows.

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, and database index -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: +Org-roam files. The directory that will contain your notes 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: 

(make-directory "~/org-roam")
@@ -705,39 +707,38 @@ this tutorial, create an empty directory, and set org-roam-directoryWe 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.
-Instead of relying on the file hierarchy for any form of categorization, we
-solely rely on links between files to establish connections between notes.
+fine; Org-roam searches recursively within org-roam-directory for notes.
+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 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:
+
Next, we need to enable the global minor mode 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 org-roam-mode on startup:
 

 

 
(add-hook 'after-init-hook 'org-roam-mode)
 

 
-
To build the cache manually, one can run M-x org-roam-db-build-cache. The
-cache is a sqlite database named org-roam.db, which defaults to residing in
-the root org-roam-directory. Cache builds may take a while the first time, but
-is often instantaneous in subsequent runs.
+
To build the cache manually, one can run 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 M-x org-roam-find-file. This shows a list
-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
-process. This process uses org-capture’s templating system, and can be freely
-customized (see 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
-the note you have created, and selecting that entry will bring you to that note.
+
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 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 process. This process uses org-capture’s templating system, and can
+be customized (see 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 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
-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
-files: this facilitates building up a dense knowledge graph of inter-connected
-notes.
+
Org-roam makes 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 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 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
 currently active Org-roam note, along with some surrounding context. To toggle
@@ -746,8 +747,7 @@ 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
 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 Roam
-Protocol).
+navigate to the files, but this requires some additional setup (see Roam Protocol).
 

 

 
@@ -758,10 +758,9 @@ Next: 
 
6 Anatomy of an Org-roam File

 
-
The bulk of Org-roam’s functionality is built on top of vanilla
-Org-mode. However, to support additional functionality, Org-roam adds
-several Org-roam-specific keywords. These functionality are not crucial
-to effective use of Org-roam.
+
The bulk of Org-roam’s functionality is built on top of vanilla Org-mode.
+However, to support additional functionality, Org-roam adds several
+Org-roam-specific keywords.
 

 

 
• Titles:  
@@ -2566,7 +2565,14 @@ Previous: ,
 

 
 
Emacs 28.0.50 (Org mode 9.4)
-

+

+

+
Footnotes

+
+
(1)

+
To understand more about Roam, a collection of links are available in Note-taking Workflows.

+

+

 
 
 
diff --git a/org-roam.org b/org-roam.org
index f5f476a..8c8906f 100644
--- a/org-roam.org
+++ b/org-roam.org
@@ -31,16 +31,17 @@ General Public License for more details.
 
 * Introduction
 
-Org-roam is a [[https://roamresearch.com/][Roam Research]] replica built around the
-all-powerful [[https://orgmode.org/][Org-mode]].
+Org-roam is a tool for network thought. It reproduces some of [[https://roamresearch.com/][Roam
+Research's]] [fn:roam] features within the all-powerful [[https://orgmode.org/][Org-mode]].
 
-Org-roam is a solution for effortless non-hierarchical note-taking
-with Org-mode. With Org-roam, notes flow naturally, making note-taking
-fun and easy. Org-roam should also work as a plug-and-play solution
-for anyone already using Org-mode for their personal wiki.
+Org-roam is a solution for effortless non-hierarchical note-taking with
+Org-mode. With Org-roam, notes flow naturally, making note-taking fun and easy.
+Org-roam keeps closely to Org syntax, and will work for anyone already using
+Org-mode for their personal wiki.
 
-To understand more about Roam, a collection of links are available in
-[[*Note-taking Workflows][Note-taking Workflows]].
+Org-roam gains its superpowers by leveraging the mature ecosystem around
+Org-mode. For example, it has first-class support for [[https://github.com/jkitchin/org-ref][org-ref]] for citation
+management.
 
 Org-roam aims to implement the core features of Roam, leveraging the
 mature ecosystem around Org-mode where possible. Eventually, we hope
@@ -48,21 +49,21 @@ to further introduce features enabled by the Emacs ecosystem.
 
 Org-roam provides several benefits over other tooling:
 
-- Privacy and Security :: Edit your personal wiki completely offline, entirely
-  in your control. Encrypt your notes with GPG.
-- Longevity of Plain Text :: Unlike web solutions like Roam research, the notes
-  are first and foremost plain Org-mode files -- Org-roam simply builds up an
-  auxilliary database to give the personal wiki superpowers. Having your notes
+- *Privacy and Security:* Keep your personal wiki entirely offline and in your
+  control. Encrypt your notes with GPG.
+- *Longevity of Plain Text:* Unlike web solutions like Roam Research, the notes
+  are first and foremost plain Org-mode files -- Org-roam simply builds an
+  auxiliary database to give the personal wiki superpowers. Having your notes
   in plain-text is crucial for the longevity of your wiki. Never have to worry
-  about proprietary web solutions being taken down. Edit your plain-text notes
-  in notepad if all other editors cease to exist
-- Free and Open Source :: Org-roam is free and open-source, which means that if
+  about proprietary web solutions being taken down. The notes are still
+  functional even if Org-roam ceases to exist.
+- *Free and Open Source:* Org-roam is free and open-source, which means that if
   you feel unhappy with any part of Org-roam, you may choose to extend Org-roam,
-  or open a PR.
-- Leverages the Org-mode ecosystem :: Over the years, Emacs and Org-mode has
+  or open a pull request.
+- *Leverage the Org-mode ecosystem:* Over the years, 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.
-- Built on Emacs :: Emacs is also a fantastic interface for editing text, and we
+- *Built on Emacs:* Emacs is also a fantastic interface for editing text, and we
   can inherit many of the powerful text-navigation and editing packages
   available to Emacs.
 
@@ -104,34 +105,36 @@ Org-roam provides utilities for maintaining a digital slip-box. This section
 aims to provide a brief introduction to the "slip-box", or "Zettelkasten"
 method. By providing some background on the method, we hope that the design
 decisions of Org-roam will become clear, and that will aid in using Org-roam
-appropriately. In this section we will also introduce terms commonly used within
-the Zettelkasten community, which will also commonly appear in the Org-roam
-forums and channels of discussion.
+appropriately. In this section we will introduce terms commonly used within the
+Zettelkasten community and the Org-roam forums.
 
-The Zettelkasten method of note-taking is designed to increase research
-productivity: in particular, it acts as a research partner, where conversations
-with it may produce new and surprising lines of thought. This method is
-attributed to German sociologist Niklas Luhmann, who using the method had
-produced volumes of written works.
+The Zettelkasten is a personal tool for thinking and writing. It places heavy
+emphasis on connecting ideas, building up a web of thought. Hence, it is well
+suited for knowledge workers and intellectual tasks, such as conducting
+research. The Zettelkasten can act as a research partner, where conversations
+with it may produce new and surprising lines of thought.
 
-In its paper form, the slip-box is simply a box of cards. These cards are small
--- often only large enough to fit a single concept. The size limitation
-encourages ideas to be broken down into individual concepts. These ideas are
-explicitly linked together. The breakdown of ideas encourages tangential
-exploration of ideas, increasing the surface for thought. Making linking
-explicit between notes also encourages one to think about the connections
-between concepts.
+This method is attributed to German sociologist Niklas Luhmann, who using the
+method had produced volumes of written works. Luhmann's slip-box was simply a
+box of cards. These cards are small -- often only large enough to fit a single
+concept. The size limitation encourages ideas to be broken down into individual
+concepts. These ideas are explicitly linked together. The breakdown of ideas
+encourages tangential exploration of ideas, increasing the surface for thought.
+Making linking explicit between notes also encourages one to think about the
+connections between concepts.
+
+At the corner of each note, Luhmann ascribed each note with an ordered ID,
+allowing him to link and jump between notes. In Org-roam, we simply use
+hyperlinks.
 
 Org-roam is the slip-box, digitalized in Org-mode. Every zettel (card) is a
-plain-text, Org-mode file. These files are often placed in the same directory.
-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. Org-roam also facilitates the linking of zettels using Org-mode ~file:~
-links.
+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.
 
 ** Fleeting notes
 
-A slip-box requires a method of quickly capturing ideas. These are called
+A slip-box requires a method for quickly capturing ideas. These are called
 *fleeting notes*: they are simple reminders of information or ideas that will
 need to be processed later on, or trashed. This is typically accomplished using
 ~org-capture~ (see info:org#capture), or using Org-roam's daily notes
@@ -249,8 +252,7 @@ dependencies that it requires. These include:
 - emacsql-sqlite3
 
 You can install this manually as well, or get the latest version from MELPA. You
-may wish to use [[https://github.com/jwiegley/use-package][use-package]], [[https://github.com/raxod502/straight.el][straight.el]], or some other tool or tools to help
-manage this.
+may wish to use [[https://github.com/jwiegley/use-package][use-package]], [[https://github.com/raxod502/straight.el][straight.el]] to help manage this.
 
 If you would like to install the manual for access from Emacs' built-in Info
 system, you'll need to compile the .texi source file, and install it in an
@@ -322,10 +324,10 @@ 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 first start using Org-roam, one needs to pick a location to store the
-Org-roam files. The directory that will contain your notes, and database index
-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~:
+Org-roam files. The directory that will contain your notes 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")
@@ -334,39 +336,38 @@ this tutorial, create an empty directory, and set ~org-roam-directory~:
 
 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.
-Instead of relying on the file hierarchy for any form of categorization, we
-solely rely on links between files to establish connections between notes.
+fine; Org-roam searches recursively within ~org-roam-directory~ for notes.
+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 ~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:
+Next, we need to enable the global minor mode ~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 ~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 is a sqlite database named ~org-roam.db~, which defaults to residing in
-the root ~org-roam-directory~. Cache builds may take a while the first time, but
-is often instantaneous in subsequent runs.
+To build the cache manually, one can run ~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 ~M-x org-roam-find-file~. This shows a list
-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
-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
-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.
+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 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 process. This process uses ~org-capture~'s templating system, and can
+be 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 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
-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
-files: this facilitates building up a dense knowledge graph of inter-connected
-notes.
+Org-roam makes 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 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 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
 currently active Org-roam note, along with some surrounding context. To toggle
@@ -375,15 +376,14 @@ 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
 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 [[*Roam Protocol][Roam
-Protocol]]).
+navigate to the files, but this requires some additional setup (see [[*Roam
+Protocol][Roam Protocol]]).
 
 * Anatomy of an Org-roam File
 
-The bulk of Org-roam's functionality is built on top of vanilla
-Org-mode. However, to support additional functionality, Org-roam adds
-several Org-roam-specific keywords. These functionality are not crucial
-to effective use of Org-roam.
+The bulk of Org-roam's functionality is built on top of vanilla Org-mode.
+However, to support additional functionality, Org-roam adds several
+Org-roam-specific keywords.
 
 ** Titles
 
@@ -1543,7 +1543,9 @@ are the solutions:
 :INDEX:      vr
 :END:
 
-
+* Footnotes
+[fn:roam] To understand more about Roam, a collection of links are available in [[*Note-taking Workflows][Note-taking Workflows]].
+ 
 # Local Variables:
 # eval: (require 'ol-info)
 # eval: (require 'ox-texinfo+ nil t)
diff --git a/org-roam.texi b/org-roam.texi
index d34efb9..1cf10c0 100644
--- a/org-roam.texi
+++ b/org-roam.texi
@@ -180,16 +180,17 @@ FAQ
 @node Introduction
 @chapter Introduction
 
-Org-roam is a @uref{https://roamresearch.com/, Roam Research} replica built around the
-all-powerful @uref{https://orgmode.org/, Org-mode}.
+Org-roam is a tool for network 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}.
 
-Org-roam is a solution for effortless non-hierarchical note-taking
-with Org-mode. With Org-roam, notes flow naturally, making note-taking
-fun and easy. Org-roam should also work as a plug-and-play solution
-for anyone already using Org-mode for their personal wiki.
+Org-roam is a solution for effortless non-hierarchical note-taking with
+Org-mode. With Org-roam, notes flow naturally, making note-taking fun and easy.
+Org-roam keeps closely to Org syntax, and will work for anyone already using
+Org-mode for their personal wiki.
 
-To understand more about Roam, a collection of links are available in
-@ref{Note-taking Workflows}.
+Org-roam gains its superpowers by leveraging the mature ecosystem around
+Org-mode. For example, it has first-class support for @uref{https://github.com/jkitchin/org-ref, org-ref} for citation
+management.
 
 Org-roam aims to implement the core features of Roam, leveraging the
 mature ecosystem around Org-mode where possible. Eventually, we hope
@@ -198,30 +199,30 @@ to further introduce features enabled by the Emacs ecosystem.
 Org-roam provides several benefits over other tooling:
 
 @itemize
- @item
- Privacy and SecurityEdit your personal wiki completely offline, entirely
-in your control. Encrypt your notes with GPG@.
+@item
+@strong{Privacy and Security:} Keep your personal wiki entirely offline and in your
+control. Encrypt your notes with GPG@.
 
 @item
- Longevity of Plain TextUnlike web solutions like Roam research, the notes
-are first and foremost plain Org-mode files -- Org-roam simply builds up an
-auxilliary database to give the personal wiki superpowers. Having your notes
+@strong{Longevity of Plain Text:} Unlike web solutions like Roam Research, the notes
+are first and foremost plain Org-mode files -- Org-roam simply builds an
+auxiliary database to give the personal wiki superpowers. Having your notes
 in plain-text is crucial for the longevity of your wiki. Never have to worry
-about proprietary web solutions being taken down. Edit your plain-text notes
-in notepad if all other editors cease to exist
+about proprietary web solutions being taken down. The notes are still
+functional even if Org-roam ceases to exist.
 
 @item
- Free and Open SourceOrg-roam is free and open-source, which means that if
+@strong{Free and Open Source:} Org-roam is free and open-source, which means that if
 you feel unhappy with any part of Org-roam, you may choose to extend Org-roam,
-or open a PR@.
+or open a pull request.
 
 @item
- Leverages the Org-mode ecosystemOver the years, Emacs and Org-mode has
+@strong{Leverage the Org-mode ecosystem:} Over the years, 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
- Built on EmacsEmacs is also a fantastic interface for editing text, and we
+@strong{Built on Emacs:} Emacs is also a fantastic interface for editing text, and we
 can inherit many of the powerful text-navigation and editing packages
 available to Emacs.
 @end itemize
@@ -267,30 +268,32 @@ Org-roam provides utilities for maintaining a digital slip-box. This section
 aims to provide a brief introduction to the ``slip-box'', or ``Zettelkasten''
 method. By providing some background on the method, we hope that the design
 decisions of Org-roam will become clear, and that will aid in using Org-roam
-appropriately. In this section we will also introduce terms commonly used within
-the Zettelkasten community, which will also commonly appear in the Org-roam
-forums and channels of discussion.
+appropriately. In this section we will introduce terms commonly used within the
+Zettelkasten community and the Org-roam forums.
 
-The Zettelkasten method of note-taking is designed to increase research
-productivity: in particular, it acts as a research partner, where conversations
-with it may produce new and surprising lines of thought. This method is
-attributed to German sociologist Niklas Luhmann, who using the method had
-produced volumes of written works.
+The Zettelkasten is a personal tool for thinking and writing. It places heavy
+emphasis on connecting ideas, building up a web of thought. Hence, it is well
+suited for knowledge workers and intellectual tasks, such as conducting
+research. The Zettelkasten can act as a research partner, where conversations
+with it may produce new and surprising lines of thought.
 
-In its paper form, the slip-box is simply a box of cards. These cards are small
--- often only large enough to fit a single concept. The size limitation
-encourages ideas to be broken down into individual concepts. These ideas are
-explicitly linked together. The breakdown of ideas encourages tangential
-exploration of ideas, increasing the surface for thought. Making linking
-explicit between notes also encourages one to think about the connections
-between concepts.
+This method is attributed to German sociologist Niklas Luhmann, who using the
+method had produced volumes of written works. Luhmann's slip-box was simply a
+box of cards. These cards are small -- often only large enough to fit a single
+concept. The size limitation encourages ideas to be broken down into individual
+concepts. These ideas are explicitly linked together. The breakdown of ideas
+encourages tangential exploration of ideas, increasing the surface for thought.
+Making linking explicit between notes also encourages one to think about the
+connections between concepts.
+
+At the corner of each note, Luhmann ascribed each note with an ordered ID,
+allowing him to link and jump between notes. In Org-roam, we simply use
+hyperlinks.
 
 Org-roam is the slip-box, digitalized in Org-mode. Every zettel (card) is a
-plain-text, Org-mode file. These files are often placed in the same directory.
-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. Org-roam also facilitates the linking of zettels using Org-mode @code{file:}
-links.
+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
 * Fleeting notes::
@@ -300,7 +303,7 @@ links.
 @node Fleeting notes
 @section Fleeting notes
 
-A slip-box requires a method of quickly capturing ideas. These are called
+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
 need to be processed later on, or trashed. This is typically accomplished using
 @code{org-capture} (see @ref{capture,,,org,}), or using Org-roam's daily notes
@@ -449,8 +452,7 @@ emacsql-sqlite3
 @end itemize
 
 You can install this manually as well, or get the latest version from MELPA@. You
-may wish to use @uref{https://github.com/jwiegley/use-package, use-package}, @uref{https://github.com/raxod502/straight.el, straight.el}, or some other tool or tools to help
-manage this.
+may wish to use @uref{https://github.com/jwiegley/use-package, use-package}, @uref{https://github.com/raxod502/straight.el, straight.el} to help manage this.
 
 If you would like to install the manual for access from Emacs' built-in Info
 system, you'll need to compile the .texi source file, and install it in an
@@ -531,10 +533,10 @@ requires a radical change in your current note-taking workflow. To understand
 more about the methods and madness, see @ref{Note-taking Workflows}.
 
 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, and database index
-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}:
+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
+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")
@@ -543,39 +545,38 @@ this tutorial, create an empty directory, and set @code{org-roam-directory}:
 
 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 @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.
+fine; Org-roam searches recursively within @code{org-roam-directory} for notes.
+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, builds a cache and keeps it consistent. We recommend
-starting @code{org-roam-mode} on startup:
+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)
 @end lisp
 
-To build the cache manually, one can run @code{M-x org-roam-db-build-cache}. The
-cache is a sqlite database named @code{org-roam.db}, which defaults to residing in
-the root @code{org-roam-directory}. Cache builds may take a while the first time, but
-is often instantaneous in subsequent runs.
+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 list
-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 @code{RET} should begin the note creation
-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 @code{C-c
-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.
+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 @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 @code{RET} should begin 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. 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 @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
-files: this facilitates building up a dense knowledge graph of inter-connected
-notes.
+Org-roam makes it easy to create notes, and link them together. 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 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
 currently active Org-roam note, along with some surrounding context. To toggle
@@ -584,16 +585,14 @@ 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, , Roam
-Protocol}).
+navigate to the files, but this requires some additional setup (see @ref{Roam Protocol}).
 
 @node Anatomy of an Org-roam File
 @chapter Anatomy of an Org-roam File
 
-The bulk of Org-roam's functionality is built on top of vanilla
-Org-mode. However, to support additional functionality, Org-roam adds
-several Org-roam-specific keywords. These functionality are not crucial
-to effective use of Org-roam.
+The bulk of Org-roam's functionality is built on top of vanilla Org-mode.
+However, to support additional functionality, Org-roam adds several
+Org-roam-specific keywords.
 
 @menu
 * Titles::