(doc): various improvements (#1253)

- options: explicitly enable smart quotes on export
- zettelkasten introduction: add sections for fleeting notes and
  permanent notes for easier access and reference
- anatomy: add a missing period
- encryption: clarify org-roam-encrypt-files is a user option
- roam protocol: remove extraneous heading
- roam protocol: small grammar fix
- doctor: explain what the doctor does by default
- org-roam-bibtex: explain part of what orb actually does

doc/org-roam.org

@@ -12,7 +12,7 @@
 #+texinfo_dir_desc: Rudimentary Roam Replica for Emacs.
 #+subtitle: for version 1.2.2
 
-#+options: H:4 num:3 toc:2 creator:t
+#+options: H:4 num:3 toc:2 creator:t ':t
 #+property: header-args :eval never
 #+texinfo: @noindent
 
@@ -122,6 +122,8 @@ 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.
 
+** Fleeting notes
+
 A slip-box requires a method of 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
@@ -129,6 +131,8 @@ need to be processed later on, or trashed. This is typically accomplished using
 functionality (see [[*Daily-notes][Daily-notes]]). This provides a central inbox for collecting
 thoughts, to be processed later into permanent notes.
 
+** Permanent notes
+
 Permanent notes are further split into two categories: *literature notes* and
 *concept notes*. Literature notes can be brief annotations on a particular
 source (e.g. book, website or paper), that you'd like to access later on.
@@ -370,7 +374,7 @@ title extraction methods supported are:
 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
 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
+   The aliases are space-delimited, and can be multi-worded using quotes.
 
 Take for example the following org file:
 
@@ -731,7 +735,7 @@ Note that Emacs will prompt for a password for encrypted files during
 cache updates if it requires reading the encrypted file. To reduce the
 number of password prompts, you may wish to cache the password.
 
-- Variable: org-roam-encrypt-files
+- User Option: org-roam-encrypt-files
 
   Whether to encrypt new files.  If true, create files with .org.gpg extension.
 * Graphing
@@ -847,9 +851,9 @@ commands, set:
 Other options include ~'ido~, and ~'ivy~.
 
 * Roam Protocol
-** _ :ignore:
+
-Org-roam extending ~org-protocol~ with 2 protocols: the ~roam-file~
+Org-roam extends ~org-protocol~ with 2 protocols: the ~roam-file~
-and ~roam-ref~ protocol.
+and ~roam-ref~ protocols.
 
 ** Installation
 
@@ -1149,8 +1153,9 @@ org-roam-doctor~, but note that this may take some time.
   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
+The checks run are defined in ~org-roam-doctor--checkers~. By default, there are checkers for broken links and invalid =#+roam_*= properties.
-instance of ~org-roam-doctor-checker~. To define a checker, use
+
+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
@@ -1406,6 +1411,8 @@ tight integration between
 ~org-roam~. This helps you manage your bibliographic notes under
 ~org-roam~.
 
+For example, though helm-bibtex provides the ability to visit notes for bibliographic entries, org-roam-bibtex extends it with the ability to visit the file with the right =#+roam_key=.
+
 **** Spaced Repetition
     :PROPERTIES:
     :CUSTOM_ID: spaced-repetition

doc/org-roam.texi

@@ -89,6 +89,11 @@ 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::
@@ -125,7 +130,6 @@ Graphing
 
 Roam Protocol
 
-* _::
 * Installation: Installation (1). 
 * The roam-file protocol::
 * The roam-ref protocol::
@@ -267,6 +271,14 @@ 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.
 
+@menu
+* Fleeting notes::
+* Permanent notes::
+@end menu
+
+@node Fleeting notes
+@section Fleeting notes
+
 A slip-box requires a method of 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
@@ -274,6 +286,9 @@ 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
+@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
 source (e.g. book, website or paper), that you'd like to access later on.
@@ -418,7 +433,7 @@ Where @code{/path/to/my/info/files} is the location where you keep info files. T
 @lisp
 (require 'info)
 (add-to-list 'Info-default-directory-list
-         "/path/to/my/info/files")
+             "/path/to/my/info/files")
 @end lisp
 
 You can also use one of the default locations, such as:
@@ -568,7 +583,7 @@ title extraction methods supported are:
 
 @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
+The aliases are space-delimited, and can be multi-worded using quotes.
 @end itemize
 
 Take for example the following org file:
@@ -1026,10 +1041,10 @@ Note that Emacs will prompt for a password for encrypted files during
 cache updates if it requires reading the encrypted file. To reduce the
 number of password prompts, you may wish to cache the password.
 
-@defvar org-roam-encrypt-files
+@defopt org-roam-encrypt-files
 
 Whether to encrypt new files.  If true, create files with .org.gpg extension.
-@end defvar
+@end defopt
 
 @node Graphing
 @chapter Graphing
@@ -1181,19 +1196,15 @@ Other options include @code{'ido}, and @code{'ivy}.
 @node Roam Protocol
 @chapter Roam Protocol
 
+Org-roam extends @code{org-protocol} with 2 protocols: the @code{roam-file}
+and @code{roam-ref} protocols.
+
 @menu
-* _::
 * Installation: Installation (1). 
 * The roam-file protocol::
 * The roam-ref protocol::
 @end menu
 
-@node _
-@section _ :ignore:
-
-Org-roam extending @code{org-protocol} with 2 protocols: the @code{roam-file}
-and @code{roam-ref} protocol.
-
 @node Installation (1)
 @section Installation
 
@@ -1527,8 +1538,9 @@ Perform a check on Org-roam files to ensure cleanliness. If THIS-BUFFER, run
 the check only for the current buffer.
 @end defun
 
-The checks run are defined in @code{org-roam-doctor--checkers}. Each checker is an
+The checks run are defined in @code{org-roam-doctor--checkers}. By default, there are checkers for broken links and invalid @samp{#+roam_*} properties.
-instance of @code{org-roam-doctor-checker}. To define a checker, use
+
+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
@@ -1822,6 +1834,8 @@ tight integration between
 @code{org-roam}. This helps you manage your bibliographic notes under
 @code{org-roam}.
 
+For example, though helm-bibtex provides the ability to visit notes for bibliographic entries, org-roam-bibtex extends it with the ability to visit the file with the right @samp{#+roam_key}.
+
 @node Spaced Repetition
 @unnumberedsubsubsec Spaced Repetition