From c45173fb30e866e179fe2bb6cf2c9c95097cafbc Mon Sep 17 00:00:00 2001 From: jethrokuan Date: Fri, 15 May 2020 08:11:19 +0000 Subject: [PATCH] =?UTF-8?q?Deploying=20to=20gh-pages=20from=20=20@=20f3905?= =?UTF-8?q?93cfb2b880fa36bc06c0b42fb402a8f7af9=20=F0=9F=9A=80?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- manual/Anatomy-of-an-Org_002droam-File.html | 8 +- manual/FAQ.html | 2 +- manual/File-Refs.html | 6 +- ...-than-one-Org_002droam-directory_003f.html | 4 +- manual/Installation-_00281_0029.html | 8 +- manual/Installation.html | 12 +- manual/Installing-from-MELPA.html | 6 +- .../Installing-from-the-Git-Repository.html | 2 +- manual/Post_002dInstallation-Tasks.html | 2 +- manual/Roam-Protocol.html | 13 +- manual/Tags.html | 105 +++++++++++++++ manual/The-roam_002dfile-protocol.html | 2 +- manual/The-roam_002dref-Protocol.html | 2 +- manual/Titles.html | 118 +++++++++++++++++ ...le-Aliases.html => _005f-_00281_0029.html} | 30 ++--- manual/_005f-_00282_0029.html | 75 +++++++++++ manual/_005f.html | 77 +++++++++++ manual/index.html | 41 +++--- org-roam.org | 45 ++++++- org-roam.texi | 124 +++++++++++++++--- 20 files changed, 595 insertions(+), 87 deletions(-) create mode 100644 manual/Tags.html create mode 100644 manual/Titles.html rename manual/{File-Aliases.html => _005f-_00281_0029.html} (62%) create mode 100644 manual/_005f-_00282_0029.html create mode 100644 manual/_005f.html diff --git a/manual/Anatomy-of-an-Org_002droam-File.html b/manual/Anatomy-of-an-Org_002droam-File.html index 2611712..a457995 100644 --- a/manual/Anatomy-of-an-Org_002droam-File.html +++ b/manual/Anatomy-of-an-Org_002droam-File.html @@ -25,7 +25,7 @@ General Public License for more details. - + + + + + + + +
+

+Next: , Previous: , Up: Anatomy of an Org-roam File   [Contents]

+
+
+ +

4.2 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 +variable ‘org-roam-tag-sources’, to control how tags are extracted. The tag +extraction methods supported are: +

+
    +
  1. ‘'prop’: This extracts tags from the ‘#+ROAM_TAGS’ property. Tags are space delimited, and can be multi-word using double quotes. +
  2. ‘'all-directories’: All sub-directories relative to ‘org-roam-directory’ are +extracted as tags. That is, if a file is located at relative path +‘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’. +
+ +

By default, only the ‘'prop’ extraction method is enabled. To enable the other +extraction methods, you may modify ‘org-roam-tag-sources’: +

+
+
(setq org-roam-tag-sources '(prop last-directory))
+
+ +

If you wish to add your own tag extraction method, you may push a symbol ‘'foo’ +into ‘org-roam-tag-sources’, and define a ‘org-roam--extract-tags-foo’ which +accepts the absolute file path as its argument. See +‘org-roam--extract-tags-prop’ for an example. +

+ + + + + diff --git a/manual/The-roam_002dfile-protocol.html b/manual/The-roam_002dfile-protocol.html index 2a1035c..e563eff 100644 --- a/manual/The-roam_002dfile-protocol.html +++ b/manual/The-roam_002dfile-protocol.html @@ -66,7 +66,7 @@ Next:
-

11.2 The ‘roam-file’ protocol

+

11.3 The ‘roam-file’ protocol

This is a simple protocol that opens the path specified by the ‘file’ key (e.g. ‘org-protocol://roam-file?file=/tmp/file.org’). This is used diff --git a/manual/The-roam_002dref-Protocol.html b/manual/The-roam_002dref-Protocol.html index d38f22b..6bc56ac 100644 --- a/manual/The-roam_002dref-Protocol.html +++ b/manual/The-roam_002dref-Protocol.html @@ -66,7 +66,7 @@ Previous:

-

11.3 The ‘roam-ref’ Protocol

+

11.4 The ‘roam-ref’ Protocol

This protocol finds or creates a new note with a given ‘ROAM_KEY’ (see Anatomy of an Org-roam File):

diff --git a/manual/Titles.html b/manual/Titles.html new file mode 100644 index 0000000..60599a9 --- /dev/null +++ b/manual/Titles.html @@ -0,0 +1,118 @@ + + + + + + +Titles (Org-roam User Manual) + + + + + + + + + + + + + + + + + + +
+

+Next: , Up: Anatomy of an Org-roam File   [Contents]

+
+
+ +

4.1 Titles

+ +

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 +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 +
+ +

Take for example the following org file: +

+
+
#+TITLE: World War 2
+#+ROAM_ALIAS: "WWII" "World War II"
+
+* Headline
+
+ + + + + + +
MethodTitles
‘'title’’(“World War 2”)
‘'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. +

+

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. +

+ + + + + diff --git a/manual/File-Aliases.html b/manual/_005f-_00281_0029.html similarity index 62% rename from manual/File-Aliases.html rename to manual/_005f-_00281_0029.html index 08ca954..c534378 100644 --- a/manual/File-Aliases.html +++ b/manual/_005f-_00281_0029.html @@ -15,18 +15,18 @@ General Public License for more details. -File Aliases (Org-roam User Manual) +_ (1) (Org-roam User Manual) - - + + - - - + + + + + + + + + +
+

+Previous: , Up: Top   [Contents]

+
+
+ +

15 _ :ignore:

+ +

Emacs 28.0.50 (Org mode 9.4) +

+ + + + diff --git a/manual/_005f.html b/manual/_005f.html new file mode 100644 index 0000000..5bab159 --- /dev/null +++ b/manual/_005f.html @@ -0,0 +1,77 @@ + + + + + + +_ (Org-roam User Manual) + + + + + + + + + + + + + + + + + + +
+

+Next: , Up: Installation   [Contents]

+
+
+ +

2.1 _ :ignore:

+ +

Org-roam can be installed using Emacs’ package manager or manually from its development repository. +

+ + + + + diff --git a/manual/index.html b/manual/index.html index a1ddbf5..23f0161 100644 --- a/manual/index.html +++ b/manual/index.html @@ -72,15 +72,17 @@ ul.no-bullet {list-style: none}
  • 1 Introduction
  • 2 Installation
  • 3 Getting Started
  • 4 Anatomy of an Org-roam File
  • 5 The Templating System @@ -152,10 +156,9 @@ Next:

    FAQ:   +• _:   + 

     
 
    — The Detailed Node Listing —
 
 Installation
 
-
    • Installing from MELPA:   +• _:   + +• Installing from MELPA:   • Installing from the Git Repository:   @@ -209,7 +216,9 @@ Installation Anatomy of an Org-roam File -• File Aliases:   +• Titles:   + +• Tags:   • File Refs:   @@ -251,7 +260,9 @@ Graphing Roam Protocol -• Installation:   +• _:   + +• Installation:   • The ‘roam-file’ protocol:   diff --git a/org-roam.org b/org-roam.org index 4d96513..d6e46bb 100644 --- a/org-roam.org +++ b/org-roam.org @@ -19,10 +19,9 @@ This manual is for Org-roam version 1.1.1. #+BEGIN_QUOTE Copyright (C) 2020-2020 Jethro Kuan -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 version 3 of the License, or (at your option) any -later version. +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 +version 3 of the License, or (at your option) any later version. This document is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of @@ -174,7 +173,7 @@ 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. -** File Titles +** Titles 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 @@ -211,6 +210,41 @@ One can freely control which extraction methods to use by customizing information. If all methods of title extraction return no results, the file-name is used in place of the titles for completions. +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. + +** 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 +variable =org-roam-tag-sources=, to control how tags are extracted. The tag +extraction methods supported are: + +1. ='prop=: This extracts tags from the =#+ROAM_TAGS= property. Tags are space delimited, and can be multi-word using double quotes. +2. ='all-directories=: All sub-directories relative to =org-roam-directory= are + extracted as tags. That is, if a file is located at relative path + =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=. + +By default, only the ='prop= extraction method is enabled. To enable the other +extraction methods, you may modify =org-roam-tag-sources=: + +#+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= +into =org-roam-tag-sources=, and define a =org-roam--extract-tags-foo= which +accepts the absolute file path as its argument. See +=org-roam--extract-tags-prop= for an example. + ** File Refs Refs are unique identifiers for files. Each note can only have 1 ref. @@ -932,6 +966,7 @@ file within that directory, at least once. * _ :ignore: # Local Variables: +# eval: (refill-mode +1) # before-save-hook: org-make-toc # after-save-hook: (lambda nil (progn (require 'ox-texinfo nil t) (org-texinfo-export-to-info))) # indent-tabs-mode: nil diff --git a/org-roam.texi b/org-roam.texi index 38882da..7ef205a 100644 --- a/org-roam.texi +++ b/org-roam.texi @@ -51,10 +51,9 @@ This manual is for Org-roam version 1.1.1. @quotation Copyright (C) 2020-2020 Jethro Kuan -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 version 3 of the License, or (at your option) any -later version. +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 +version 3 of the License, or (at your option) any later version. This document is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of @@ -79,19 +78,22 @@ General Public License for more details. * Diagnosing and Repairing Files:: * Appendix:: * FAQ:: +* _: _ (2). @detailmenu --- The Detailed Node Listing --- Installation +* _:: * Installing from MELPA:: * Installing from the Git Repository:: * Post-Installation Tasks:: Anatomy of an Org-roam File -* File Aliases:: +* Titles:: +* Tags:: * File Refs:: The Templating System @@ -117,6 +119,7 @@ Graphing Roam Protocol +* _: _ (1). * Installation: Installation (1). * The @samp{roam-file} protocol:: * The @samp{roam-ref} Protocol:: @@ -176,14 +179,18 @@ Emacs is also a fantastic interface for editing text, and we can inherit many of @node Installation @chapter Installation -Org-roam can be installed using Emacs' package manager or manually from its development repository. - @menu +* _:: * Installing from MELPA:: * Installing from the Git Repository:: * Post-Installation Tasks:: @end menu +@node _ +@section _ :ignore: + +Org-roam can be installed using Emacs' package manager or manually from its development repository. + @node Installing from MELPA @section Installing from MELPA @@ -310,22 +317,100 @@ several Org-roam-specific keywords. These functionality are not crucial to effective use of Org-roam. @menu -* File Aliases:: +* Titles:: +* Tags:: * File Refs:: @end menu -@node File Aliases -@section File Aliases +@node Titles +@section Titles -Suppose you want a note to be referred to by different names (e.g. -``World War 2'', ``WWII''). You may specify such aliases using the -@samp{#+ROAM_ALIAS} attribute: +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 @samp{org-roam--extract-titles} to extract titles. It uses the +variable @samp{org-roam-title-sources}, to control how the titles are extracted. The +title extraction methods supported are: + +@enumerate +@item +@samp{'title}: This extracts the title using the file @samp{#+TITLE} property +@item +@samp{'headline}: This extracts the title from the first headline in the Org file +@item +@samp{'alias}: This extracts a list of titles using the @samp{#ROAM_ALIAS} property. +The aliases are space-delimited, and can be multi-worded using quotes +@end enumerate + +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 @samp{'title} +@tab '(``World War 2'') +@item @samp{'headline} +@tab '(``Headline'') +@item @samp{'alias} +@tab '(``WWII'' ``World War II'') +@end multitable + +One can freely control which extraction methods to use by customizing +@samp{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. + +If you wish to add your own title extraction method, you may push a symbol +@samp{'foo} into @samp{org-roam-title-sources}, and define a +@samp{org-roam--extract-titles-foo} which accepts no arguments. See +@samp{org-roam--extract-titles-title} for an example. + +@node Tags +@section 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 @samp{org-roam--extract-tags} to extract tags from files. It uses the +variable @samp{org-roam-tag-sources}, to control how tags are extracted. The tag +extraction methods supported are: + +@enumerate +@item +@samp{'prop}: This extracts tags from the @samp{#+ROAM_TAGS} property. Tags are space delimited, and can be multi-word using double quotes. +@item +@samp{'all-directories}: All sub-directories relative to @samp{org-roam-directory} are +extracted as tags. That is, if a file is located at relative path +@samp{foo/bar/file.org}, the file will have tags @samp{foo} and @samp{bar}. +@item +@samp{'last-directory}: Extracts the last directory relative to +@samp{org-roam-directory} as the tag. That is, if a file is located at relative +path @samp{foo/bar/file.org}, the file will have tag @samp{bar}. +@end enumerate + +By default, only the @samp{'prop} extraction method is enabled. To enable the other +extraction methods, you may modify @samp{org-roam-tag-sources}: + +@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 @samp{'foo} +into @samp{org-roam-tag-sources}, and define a @samp{org-roam--extract-tags-foo} which +accepts the absolute file path as its argument. See +@samp{org-roam--extract-tags-prop} for an example. + @node File Refs @section File Refs @@ -754,15 +839,19 @@ Other options include @samp{'ido}, and @samp{'ivy}. @node Roam Protocol @chapter Roam Protocol -Org-roam extending @samp{org-protocol} with 2 protocols: the @samp{roam-file} -and @samp{roam-ref} protocol. - @menu +* _: _ (1). * Installation: Installation (1). * The @samp{roam-file} protocol:: * The @samp{roam-ref} Protocol:: @end menu +@node _ (1) +@section _ :ignore: + +Org-roam extending @samp{org-protocol} with 2 protocols: the @samp{roam-file} +and @samp{roam-ref} protocol. + @node Installation (1) @section Installation @@ -1191,5 +1280,8 @@ All files within that directory will be treated as their own separate set of Org-roam files. Remember to run @samp{org-roam-db-build-cache} from a file within that directory, at least once. +@node _ (2) +@chapter _ :ignore: + Emacs 28.0.50 (Org mode 9.4) @bye