From 0da3afd8e032f96fe3fa70ff8d5ad13a6576fdb9 Mon Sep 17 00:00:00 2001 From: jethrokuan Date: Fri, 13 Nov 2020 14:56:34 +0000 Subject: [PATCH] =?UTF-8?q?Deploying=20to=20gh-pages=20from=20=20@=2048ef3?= =?UTF-8?q?fee1104822df86e1bad3ff26d6cfb74fc04=20=F0=9F=9A=80?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- manual.html | 77 +++++++++++++++++++++++++++++++++++++++++++++------ org-roam.org | 49 ++++++++++++++++++++++++++------ org-roam.texi | 70 ++++++++++++++++++++++++++++++++++++++++------ 3 files changed, 172 insertions(+), 24 deletions(-) diff --git a/manual.html b/manual.html index b52295e..7f317b8 100644 --- a/manual.html +++ b/manual.html @@ -171,6 +171,12 @@ Anatomy of an Org-roam File 
 
+Titles
+
+
• Customizing Title Extraction:   + +
+
 The Templating System
• Template Walkthrough:   @@ -815,15 +821,69 @@ The aliases are space-delimited, and can be multi-worded using quotes. 'alias’(“WWII” “World War II”) -

One can freely control which extraction methods to use by customizing -org-roam-title-sources: see the doc-string for the variable for more -information. If all methods of title extraction return no results, the file-name -is used in place of the titles for completions. + + +
• Customizing Title Extraction:   +
+ +

+ +
+

+Up: Titles   [Index]

+
+ +

6.1.1 Customizing Title Extraction

+ +

To control how Org-roam extracts titles, customize org-roam-title-sources. If +all methods of title extraction return no results, the file-name is used as the +note’s title.

-

If you wish to add your own title extraction method, you may push a symbol -'foo into org-roam-title-sources, and define a -org-roam--extract-titles-foo which accepts no arguments. See -org-roam--extract-titles-title for an example. +

+
User Option: org-roam-title-sources
+
+

The list of sources from which to retrieve a note title. +Each element in the list is either: +

+ + + +

Adding your own title extraction method requires two steps. First, define a +method (defun org-roam--extract-titles-foo () ...), where 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 +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.

@@ -2557,6 +2617,7 @@ Previous: , org-roam-link-auto-replace: Inserting Links org-roam-link-title-format: Inserting Links org-roam-link-use-custom-faces: Org-roam Faces +org-roam-title-sources: Customizing Title Extraction
Jump to:   O diff --git a/org-roam.org b/org-roam.org index e3f30f2..ba45080 100644 --- a/org-roam.org +++ b/org-roam.org @@ -417,15 +417,48 @@ Take for example the following org file: | ~'headline~ | '("Headline") | | ~'alias~ | '("WWII" "World War II") | -One can freely control which extraction methods to use by customizing -~org-roam-title-sources~: see the doc-string for the variable for more -information. If all methods of title extraction return no results, the file-name -is used in place of the titles for completions. +*** Customizing Title Extraction -If you wish to add your own title extraction method, you may push a symbol -~'foo~ into ~org-roam-title-sources~, and define a -~org-roam--extract-titles-foo~ which accepts no arguments. See -~org-roam--extract-titles-title~ for an example. +To control how Org-roam extracts titles, customize ~org-roam-title-sources~. If +all methods of title extraction return no results, the file-name is used as the +note's title. + +- User Option: org-roam-title-sources + + The list of sources from which to retrieve a note title. + Each element in the list is either: + +1. a symbol -- this symbol corresponds to a title retrieval function, which + returns the list of titles for the current buffer + 2. 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. + + The return results of the root list are concatenated. + + For example the setting: '((title headline) alias) means the following: + + 1. Return the 'title + 'alias, if the title of current buffer is non-empty; + 2. Or return 'headline + 'alias otherwise. + + The currently supported symbols are: + + `title' + The \"#+title\" property of org file. + + `alias' + The \"#+roam_alias\" property of the org file, using + space-delimited strings. + + `headline' + The first headline in the org file. + +Adding your own title extraction method requires two steps. First, define a +method ~(defun org-roam--extract-titles-foo () ...)~, where ~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 +~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 diff --git a/org-roam.texi b/org-roam.texi index c13adb9..ade9e50 100644 --- a/org-roam.texi +++ b/org-roam.texi @@ -108,6 +108,10 @@ Anatomy of an Org-roam File * Tags:: * File Refs:: +Titles + +* Customizing Title Extraction:: + The Templating System * Template Walkthrough:: @@ -645,15 +649,65 @@ Take for example the following org file: @tab '(``WWII'' ``World War II'') @end multitable -One can freely control which extraction methods to use by customizing -@code{org-roam-title-sources}: see the doc-string for the variable for more -information. If all methods of title extraction return no results, the file-name -is used in place of the titles for completions. +@menu +* Customizing Title Extraction:: +@end menu -If you wish to add your own title extraction method, you may push a symbol -@code{'foo} into @code{org-roam-title-sources}, and define a -@code{org-roam--extract-titles-foo} which accepts no arguments. See -@code{org-roam--extract-titles-title} for an example. +@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: + +`title' + The \``#+title\'' property of org file. + +`alias' + The \``#+roam@math{_alias}\'' property of the org file, using + space-delimited strings. + +`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 Tags @section Tags