(doc): document org-roam-tag-sources (#1274)

doc/org-roam.org

@@ -379,19 +379,29 @@ 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]]).
 
-* Anatomy of an Org-roam File
+* Files
+:PROPERTIES:
+:ID:       3edec3e6-8e26-4a43-8a0a-bf204268bbb3
+:END:
 
-The bulk of Org-roam's functionality is built on top of vanilla Org-mode.
+In Org-roam, notes typically consist of multiple files, where each file is a
-However, to support additional functionality, Org-roam adds several
+zettel.
-Org-roam-specific keywords.
 
-** Titles
+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.
 
-To easily find a note, a title needs to be prescribed to a note. A note can have
+This section explains the important components of a file, and the extensions to
-many titles: this allows a note to be referred to by different names, which is
+Org-mode.
-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
+** File Titles
-"WWII".
+
+To easily find a note, a title needs to be prescribed to a note.
+
+A note can have many titles: this allows a note to be referred to by different
+names, which is 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
 variable ~org-roam-title-sources~, to control how the titles are extracted. The
@@ -417,6 +427,8 @@ Take for example the following org file:
 | ~'headline~ | '("Headline")            |
 | ~'alias~    | '("WWII" "World War II") |
 
+If no title is provided, Org-roam defaults to using the file-path.
+
 *** Customizing Title Extraction
 
 To control how Org-roam extracts titles, customize ~org-roam-title-sources~. If
@@ -443,14 +455,14 @@ note's title.
 
   The currently supported symbols are:
 
-  `title'
+   ~'title~
-   The \"#+title\" property of org file.
+   The ~#+title~ property of org file.
 
-  `alias'
+   ~'alias~
-   The \"#+roam_alias\" property of the org file, using
+   The ~#+roam_alias~ property of the org file, using
    space-delimited strings.
 
-   `headline'
+   ~'headline~
    The first headline in the org file.
 
 Adding your own title extraction method requires two steps. First, define a
@@ -460,40 +472,69 @@ arguments, and returns a list of strings (titles). Finally, push the symbol
 ~foo~ into ~org-roam-title-sources~. You may need to rebuild the cache from
 scratch to re-process all files to pick up the new titles.
 
-** Tags
+** 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.
 
-Org-roam calls ~org-roam--extract-tags~ to extract tags from files. It uses the
+By default, tags are extracted from the ~#+roam_tags~ property. To add
-variable ~org-roam-tag-sources~, to control how tags are extracted. The tag
+additional extraction methods, see [[id:c986edba-9498-4af1-b033-c94b733d42c8][Customizing Tag Extraction]].
-extraction methods supported are:
 
-1. ~'prop~: This extracts tags from the ~#+roam_tags~ property. Tags are space
+*** Customizing Tag Extraction
-   delimited, and can be multi-word using double quotes.
+:PROPERTIES:
-2. ~'all-directories~: All sub-directories relative to ~org-roam-directory~ are
+:ID:       c986edba-9498-4af1-b033-c94b733d42c8
-   extracted as tags. That is, if a file is located at relative path
+:END:
-   ~foo/bar/file.org~, the file will have tags ~foo~ and ~bar~.
-3. ~'last-directory~: Extracts the last directory relative to
-   ~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~.
-4. ~'first-directory~: Extracts the first directory relative to
-   ~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~.
 
+Org-roam calls ~org-roam--extract-tags~ to extract tags from files. The variable
+~org-roam-tag-sources~, to control how tags are extracted.
+
+- User Option: org-roam-tag-sources
+
+Sources to obtain tags from.
+
+It should be a list of symbols representing any of the following extraction
+methods:
+
+  ~'prop~
+    Extract tags from the ~#+roam_tags~ property.
+    Tags are space delimited.
+    Tags may contain spaces if they are double-quoted.
+    e.g. ~#+roam_tags: TAG "tag with spaces"~
+
+  ~'vanilla~
+    Extract vanilla org-mode tags, including ~#+FILETAGS~ and
+    inherited tags.
+
+  ~'all-directories~
+    Extract sub-directories relative to ~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".
+
+  ~'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\".
+
+  ~'first-directory~
+    Extract the first 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 "foo"
+    
 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~, for example:
 
 #+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~
+Adding your own tag extraction method requires two steps. First, define a method
-into ~org-roam-tag-sources~, and define a ~org-roam--extract-tags-foo~ which
+~(defun org-roam--extract-tags-foo (file) ...)~, where ~foo~ a self-prescribed
-accepts the absolute file path as its argument. See
+name for the tag extraction method. This method takes the file path as an
-~org-roam--extract-tags-prop~ for an example.
+argument, and returns a list of strings (titles). Finally, push the symbol ~foo~
+into ~org-roam-tag-sources~. You may need to rebuild the cache from scratch to
+re-process all files to pick up the new tags.
 
 ** File Refs
 
@@ -1084,7 +1125,7 @@ in the generated graph.
 
 ** 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]]):
+This protocol finds or creates a new note with a given ~roam_key~ (see [[id:3edec3e6-8e26-4a43-8a0a-bf204268bbb3][Files]]):
 
 [[file:images/roam-ref.gif]]
 

doc/org-roam.texi

@@ -67,7 +67,7 @@ General Public License for more details.
 * A Brief Introduction to the Zettelkasten Method::
 * Installation::
 * Getting Started::
-* Anatomy of an Org-roam File::
+* Files::
 * The Templating System::
 * Concepts and Configuration::
 * Inserting Links::
@@ -102,16 +102,20 @@ Installation
 * Installing from the Git Repository::
 * Post-Installation Tasks::
 
-Anatomy of an Org-roam File
+Files
 
-* Titles::
+* File Titles::
-* Tags::
+* File Tags::
 * File Refs::
 
-Titles
+File Titles
 
 * Customizing Title Extraction::
 
+File Tags
+
+* Customizing Tag Extraction::
+
 The Templating System
 
 * Template Walkthrough::
@@ -591,27 +595,34 @@ 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 Anatomy of an Org-roam File
+@node Files
-@chapter Anatomy of an Org-roam File
+@chapter Files
 
-The bulk of Org-roam's functionality is built on top of vanilla Org-mode.
+In Org-roam, notes typically consist of multiple files, where each file is a
-However, to support additional functionality, Org-roam adds several
+zettel.
-Org-roam-specific keywords.
+
+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
-* Titles::
+* File Titles::
-* Tags::
+* File Tags::
 * File Refs::
 @end menu
 
-@node Titles
+@node File Titles
-@section Titles
+@section File Titles
 
-To easily find a note, a title needs to be prescribed to a note. A note can have
+To easily find a note, a title needs to be prescribed to a note.
-many titles: this allows a note to be referred to by different names, which is
+
-especially useful for topics or concepts with acronyms. For example, for a note
+A note can have many titles: this allows a note to be referred to by different
-like ``World War 2'', it may be desirable to also refer to it using the acronym
+names, which is especially useful for topics or concepts with acronyms. For
-``WWII''.
+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
@@ -649,6 +660,8 @@ Take for example the following org file:
 @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
@@ -691,14 +704,14 @@ Or return 'headline + 'alias otherwise.
 
 The currently supported symbols are:
 
-`title'
+@code{'title}
- The \``#+title\'' property of org file.
+The @code{#+title} property of org file.
 
-`alias'
+@code{'alias}
- The \``#+roam@math{_alias}\'' property of the org file, using
+The @code{#+roam_alias} property of the org file, using
- space-delimited strings.
+space-delimited strings.
 
-`headline'
+@code{'headline}
 The first headline in the org file.
 @end itemize
 
@@ -709,50 +722,73 @@ 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 Tags
+@node File Tags
-@section 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.
 
-Org-roam calls @code{org-roam--extract-tags} to extract tags from files. It uses the
+By default, tags are extracted from the @code{#+roam_tags} property. To add
-variable @code{org-roam-tag-sources}, to control how tags are extracted. The tag
+additional extraction methods, see @ref{Customizing Tag Extraction}.
-extraction methods supported are:
 
-@itemize
+@menu
-@item
+* Customizing Tag Extraction::
-@code{'prop}: This extracts tags from the @code{#+roam_tags} property. Tags are space
+@end menu
-delimited, and can be multi-word using double quotes.
 
-@item
+@node Customizing Tag Extraction
-@code{'all-directories}: All sub-directories relative to @code{org-roam-directory} are
+@subsection Customizing Tag Extraction
-extracted as tags. That is, if a file is located at relative path
-@code{foo/bar/file.org}, the file will have tags @code{foo} and @code{bar}.
 
-@item
+Org-roam calls @code{org-roam--extract-tags} to extract tags from files. The variable
-@code{'last-directory}: Extracts the last directory relative to
+@code{org-roam-tag-sources}, to control how tags are extracted.
-@code{org-roam-directory} as the tag. That is, if a file is located at relative
-path @code{foo/bar/file.org}, the file will have tag @code{bar}.
 
-@item
+@defopt org-roam-tag-sources
-@code{'first-directory}: Extracts the first directory relative to
+@end defopt
-@code{org-roam-directory} as the tag. That is, if a file is located at relative
+
-path @code{foo/bar/file.org}, the file will have tag @code{foo}.
+Sources to obtain tags from.
-@end itemize
+
+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}:
+extraction methods, you may modify @code{org-roam-tag-sources}, for example:
 
 @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 @code{'foo}
+Adding your own tag extraction method requires two steps. First, define a method
-into @code{org-roam-tag-sources}, and define a @code{org-roam--extract-tags-foo} which
+@code{(defun org-roam--extract-tags-foo (file) ...)}, where @code{foo} a self-prescribed
-accepts the absolute file path as its argument. See
+name for the tag extraction method. This method takes the file path as an
-@code{org-roam--extract-tags-prop} for an example.
+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
@@ -1497,7 +1533,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{Anatomy of an Org-roam File}):
+This protocol finds or creates a new note with a given @code{roam_key} (see @ref{Files}):
 
 @image{images/roam-ref,,,,gif}