diff --git a/CHANGELOG.md b/CHANGELOG.md index 1389131..a12196b 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -16,7 +16,7 @@ In this release, we added two new features: 1. `org-roam-doctor`: a linting system that helps you discover possible problems with your Org-roam files. This is in the spirit of keeping notes in top quality. -2. A tagging system: one can now use sub-directories, and the `#+ROAM_TAG` key add additional meta data to notes. For more information, see [here](https://org-roam.github.io/org-roam/manual/Tags.html#Tags). +2. A tagging system: one can now use sub-directories, and the `#+roam_tags` key add additional meta data to notes. For more information, see [here](https://org-roam.github.io/org-roam/manual/Tags.html#Tags). As usual, this release comes with a multitude of bug-fixes and refactorings. diff --git a/doc/org-roam.org b/doc/org-roam.org index 6186296..deef795 100644 --- a/doc/org-roam.org +++ b/doc/org-roam.org @@ -1,18 +1,18 @@ -#+TITLE: Org-roam User Manual +#+title: Org-roam User Manual :PREAMBLE: -#+AUTHOR: Jethro Kuan -#+EMAIL: jethrokuan95@gmail.com -#+DATE: 2020-2020 -#+LANGUAGE: en +#+author: Jethro Kuan +#+email: jethrokuan95@gmail.com +#+date: 2020-2020 +#+language: en -#+TEXINFO_DIR_CATEGORY: Emacs -#+TEXINFO_DIR_TITLE: Org-roam: (org-roam). -#+TEXINFO_DIR_DESC: Rudimentary Roam Replica for Emacs. -#+SUBTITLE: for version 1.1.1 +#+texinfo_dir_category: Emacs +#+texinfo_dir_title: Org-roam: (org-roam). +#+texinfo_dir_desc: Rudimentary Roam Replica for Emacs. +#+subtitle: for version 1.1.1 -#+OPTIONS: H:4 num:3 toc:2 creator:t -#+PROPERTY: header-args :eval never -#+TEXINFO: @noindent +#+options: H:4 num:3 toc:2 creator:t +#+property: header-args :eval never +#+texinfo: @noindent This manual is for Org-roam version 1.1.1. @@ -756,7 +756,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 [[*Anatomy of an Org-roam File][Anatomy of an Org-roam File]]): [[file:images/roam-ref.gif]] @@ -770,7 +770,7 @@ javascript:location.href = + encodeURIComponent(document.title) #+END_SRC -or as a keybinding in =qutebrowser=, adding the following to the =autoconfig.yml= file: +or as a keybinding in ~qutebrowser~, adding the following to the ~autoconfig.yml~ file: #+BEGIN_SRC yaml settings: @@ -780,18 +780,18 @@ settings: gc: open javascript:void(location.href='org-protocol://roam-ref?template=r&ref='+encodeURIComponent(location.href)+'&title='+encodeURIComponent(document.title)) #+END_SRC -where =template= is the template key for a template in -=org-roam-capture-ref-templates= (see [[*The Templating System][The Templating System]]). These templates -should contain a =#+roam_key: ${ref}= in it. +where ~template~ is the template key for a template in +~org-roam-capture-ref-templates~ (see [[*The Templating System][The Templating System]]). These templates +should contain a ~#+roam_key: ${ref}~ in it. * TODO Daily Notes * Diagnosing and Repairing Files Org-roam provides a utility for diagnosing and repairing problematic files via -=org-roam-doctor=. By default, =org-roam-doctor= runs the check across all Org-roam -files, and this can take some time. To run the check only for the current file, -run =C-u M-x org-roam-doctor=. +~org-roam-doctor~. By default, ~org-roam-doctor~ runs the check on the current +Org-roam file. To run the check only for the current file, run =C-u M-x +org-roam-doctor=, but note that this may take some time. - Function: org-roam-doctor &optional this-buffer diff --git a/doc/org-roam.texi b/doc/org-roam.texi index 086462c..3f30379 100644 --- a/doc/org-roam.texi +++ b/doc/org-roam.texi @@ -23,7 +23,7 @@ General Public License for more details. @end quotation @end copying -@dircategory Emacs +@dircategory emacs @direntry * Org-roam: (org-roam). Rudimentary Roam Replica for Emacs. @end direntry @@ -76,6 +76,7 @@ General Public License for more details. * Graphing:: * Org-roam Completion System:: * Roam Protocol:: +* Daily Notes:: * Diagnosing and Repairing Files:: * Appendix:: * FAQ:: @@ -192,13 +193,13 @@ 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. -In its paper form, the slip-box is simply a box of cards. These cards are small, -and often only large enough to fit a single concept. The size limitation +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, using an indexing system. Enforcing 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, which forms a large part of research. +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. 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. @@ -207,6 +208,20 @@ 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. +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 +@code{org-capture} (see @ref{capture,,,org,}), or using Org-roam's daily notes +functionality (see @ref{Daily Notes}). This provides a central inbox for collecting +thoughts, to be processed later into 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. +Concept notes require much more care in authoring: they need to be +self-explanatory and detailed. Org-roam's templating system supports the +addition of different templates to facilitate the creation of these notes. + @node Installation @chapter Installation @@ -1030,7 +1045,7 @@ in the generated graph. @node The @samp{roam-ref} Protocol @section The @samp{roam-ref} Protocol -This protocol finds or creates a new note with a given @samp{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{Anatomy of an Org-roam File}): @image{images/roam-ref,,,,gif} @@ -1044,7 +1059,7 @@ javascript:location.href = + encodeURIComponent(document.title) @end example -or as a keybinding in @samp{qutebrowser}, adding the following to the @samp{autoconfig.yml} file: +or as a keybinding in @code{qutebrowser}, adding the following to the @code{autoconfig.yml} file: @example settings: @@ -1054,9 +1069,9 @@ settings: gc: open javascript:void(location.href='org-protocol://roam-ref?template=r&ref='+encodeURIComponent(location.href)+'&title='+encodeURIComponent(document.title)) @end example -where @samp{template} is the template key for a template in -@samp{org-roam-capture-ref-templates} (see @ref{The Templating System}). These templates -should contain a @samp{#+roam_key: $@{ref@}} in it. +where @code{template} is the template key for a template in +@code{org-roam-capture-ref-templates} (see @ref{The Templating System}). These templates +should contain a @code{#+roam_key: $@{ref@}} in it. @node Daily Notes @chapter @strong{TODO} Daily Notes @@ -1065,9 +1080,9 @@ should contain a @samp{#+roam_key: $@{ref@}} in it. @chapter Diagnosing and Repairing Files Org-roam provides a utility for diagnosing and repairing problematic files via -@samp{org-roam-doctor}. By default, @samp{org-roam-doctor} runs the check across all Org-roam -files, and this can take some time. To run the check only for the current file, -run @samp{C-u M-x org-roam-doctor}. +@code{org-roam-doctor}. By default, @code{org-roam-doctor} runs the check on the current +Org-roam file. To run the check only for the current file, run @samp{C-u M-x +org-roam-doctor}, but note that this may take some time. @itemize @item @@ -1238,8 +1253,7 @@ These are some plugins that make note-taking in Org-mode more enjoyable. @node Org-download @unnumberedsubsubsec Org-download -@uref{https://github.com/abo-abo/org-download, Org-download} lets you -screenshot and yank images from the web into your notes: +@uref{https://github.com/abo-abo/org-download, Org-download} lets you screenshot and yank images from the web into your notes: @float Figure @image{images/org-download,,,,gif} @@ -1258,9 +1272,7 @@ screenshot and yank images from the web into your notes: @node mathpixel @unnumberedsubsubsec mathpix.el -@uref{https://github.com/jethrokuan/mathpix.el, mathpix.el} uses -@uref{https://mathpix.com/, Mathpix's} API to convert clips into latex -equations: +@uref{https://github.com/jethrokuan/mathpix.el, mathpix.el} uses @uref{https://mathpix.com/, Mathpix's} API to convert clips into latex equations: @float Figure @image{images/mathpix,,,,gif} @@ -1297,11 +1309,8 @@ tight integration between @node Spaced Repetition @unnumberedsubsubsec Spaced Repetition -@uref{https://github.com/l3kn/org-fc/, Org-fc} is a spaced repetition -system that scales well with a large number of files. Other alternatives -include -@uref{https://orgmode.org/worg/org-contrib/org-drill.html, org-drill}, and -@uref{https://github.com/abo-abo/pamparam, pamparam}. +@uref{https://github.com/l3kn/org-fc/, Org-fc} is a spaced repetition system that scales well with a large number of +files. Other alternatives include @uref{https://orgmode.org/worg/org-contrib/org-drill.html, org-drill}, and @uref{https://github.com/abo-abo/pamparam, pamparam}. @node FAQ @chapter FAQ diff --git a/org-roam-dailies.el b/org-roam-dailies.el index 959f786..d05e096 100644 --- a/org-roam-dailies.el +++ b/org-roam-dailies.el @@ -41,7 +41,7 @@ "" :immediate-finish t :file-name "%<%Y-%m-%d>" - :head "#+TITLE: %<%Y-%m-%d>")) + :head "#+title: %<%Y-%m-%d>")) "Capture templates for daily notes in Org-roam.") ;; Declarations diff --git a/org-roam-doctor.el b/org-roam-doctor.el index 0737bca..871d816 100644 --- a/org-roam-doctor.el +++ b/org-roam-doctor.el @@ -83,7 +83,7 @@ :description "Check #+roam_alias."))) (defconst org-roam-doctor--supported-roam-properties - '("ROAM_TAGS" "ROAM_ALIAS" "ROAM_KEY") + '("roam_tags" "roam_alias" "roam_key") "List of supported Org-roam properties.") (defun org-roam-doctor-check-roam-props (ast) @@ -93,7 +93,7 @@ AST is the org-element parse tree." (org-element-map ast 'keyword (lambda (kw) (let ((key (org-element-property :key kw))) - (when (and (string-prefix-p "ROAM_" key t) + (when (and (string-prefix-p "roam_" key t) (not (member key org-roam-doctor--supported-roam-properties))) (push `(,(org-element-property :begin kw) @@ -110,7 +110,7 @@ AST is the org-element parse tree." (let (reports) (org-element-map ast 'keyword (lambda (kw) - (when (string-collate-equalp (org-element-property :key kw) "ROAM_TAGS" nil t) + (when (string-collate-equalp (org-element-property :key kw) "roam_tags" nil t) (let ((tags (org-element-property :value kw))) (condition-case nil (org-roam--str-to-list tags) @@ -130,7 +130,7 @@ AST is the org-element parse tree." (let (reports) (org-element-map ast 'keyword (lambda (kw) - (when (string-collate-equalp (org-element-property :key kw) "ROAM_ALIAS" nil t) + (when (string-collate-equalp (org-element-property :key kw) "roam_alias" nil t) (let ((aliases (org-element-property :value kw))) (condition-case nil (org-roam--str-to-list aliases) diff --git a/org-roam.el b/org-roam.el index 700d2b3..46266ca 100644 --- a/org-roam.el +++ b/org-roam.el @@ -534,16 +534,16 @@ it as FILE-PATH." (defun org-roam--extract-titles-title () "Return title from \"#+title\" of the current buffer." - (let* ((prop (org-roam--extract-global-props '("TITLE"))) - (title (cdr (assoc "TITLE" prop)))) + (let* ((prop (org-roam--extract-global-props '("title"))) + (title (cdr (assoc "title" prop)))) (when title (list title)))) (defun org-roam--extract-titles-alias () "Return the aliases from the current buffer. -Reads from the \"ROAM_ALIAS\" property." - (let* ((prop (org-roam--extract-global-props '("ROAM_ALIAS"))) - (aliases (cdr (assoc "ROAM_ALIAS" prop)))) +Reads from the \"roam_alias\" property." + (let* ((prop (org-roam--extract-global-props '("roam_alias"))) + (aliases (cdr (assoc "roam_alias" prop)))) (condition-case nil (org-roam--str-to-list aliases) (error @@ -597,7 +597,7 @@ The final directory component is used as a tag." (defun org-roam--extract-tags-prop (_file) "Extract tags from the current buffer's \"#roam_tags\" global property." - (let* ((prop (cdr (assoc "ROAM_TAGS" (org-roam--extract-global-props '("ROAM_TAGS")))))) + (let* ((prop (cdr (assoc "roam_tags" (org-roam--extract-global-props '("roam_tags")))))) (condition-case nil (org-roam--str-to-list prop) (error @@ -656,11 +656,11 @@ Examples: (defun org-roam--extract-ref () "Extract the ref from current buffer and return the type and the key of the ref." - (pcase (cdr (assoc "ROAM_KEY" - (org-roam--extract-global-props '("ROAM_KEY")))) + (pcase (cdr (assoc "roam_key" + (org-roam--extract-global-props '("roam_key")))) ('nil nil) ((pred string-empty-p) - (user-error "ROAM_KEY cannot be empty")) + (user-error "Org property #+roam_key cannot be empty")) (ref (let* ((type (org-roam--ref-type ref)) (key (cond ((string= "cite" type) @@ -945,7 +945,7 @@ for Org-ref cite links." (defun org-roam-store-link () "Store a link to an `org-roam' file." (when (org-before-first-heading-p) - (when-let ((title (cdr (assoc "TITLE" (org-roam--extract-global-props '("TITLE")))))) + (when-let ((title (cdr (assoc "title" (org-roam--extract-global-props '("title")))))) (org-link-store-props :type "file" :link (format "file:%s" (abbreviate-file-name buffer-file-name)) diff --git a/tests/roam-files/alias.org b/tests/roam-files/alias.org index c1ef924..3e21811 100644 --- a/tests/roam-files/alias.org +++ b/tests/roam-files/alias.org @@ -1,2 +1,2 @@ -#+ROAM_ALIAS: "a1" "a 2" -#+TITLE: t1 +#+roam_alias: "a1" "a 2" +#+title: t1 diff --git a/tests/roam-files/bar.org b/tests/roam-files/bar.org index aa6c1ad..3dd4911 100644 --- a/tests/roam-files/bar.org +++ b/tests/roam-files/bar.org @@ -1,3 +1,3 @@ -#+TITLE: Bar +#+title: Bar This is file bar. Bar links to [[file:nested/bar.org][Nested Bar]]. diff --git a/tests/roam-files/base.org b/tests/roam-files/base.org index 1c9316b..876953a 100644 --- a/tests/roam-files/base.org +++ b/tests/roam-files/base.org @@ -1 +1 @@ -#+TITLE: Base +#+title: Base diff --git a/tests/roam-files/foo.org b/tests/roam-files/foo.org index 463b0dd..5252e95 100644 --- a/tests/roam-files/foo.org +++ b/tests/roam-files/foo.org @@ -1,4 +1,4 @@ -#+TITLE: Foo +#+title: Foo This is the foo file. It contains a link to [[file:bar.org][Bar]]. diff --git a/tests/roam-files/nested/bar.org b/tests/roam-files/nested/bar.org index 7289e6d..b1c7400 100644 --- a/tests/roam-files/nested/bar.org +++ b/tests/roam-files/nested/bar.org @@ -1,3 +1,3 @@ -#+TITLE: Nested Bar +#+title: Nested Bar This file is nested, 1 level deeper. It links to both [[file:../foo.org][Foo]] and [[file:foo.org][Nested Foo]]. diff --git a/tests/roam-files/nested/deeply/deeply_nested_file.org b/tests/roam-files/nested/deeply/deeply_nested_file.org index 3156db6..e64d8d3 100644 --- a/tests/roam-files/nested/deeply/deeply_nested_file.org +++ b/tests/roam-files/nested/deeply/deeply_nested_file.org @@ -1 +1 @@ -#+TITLE: Deeply Nested File +#+title: Deeply Nested File diff --git a/tests/roam-files/nested/foo.org b/tests/roam-files/nested/foo.org index c492dc1..b40c6e5 100644 --- a/tests/roam-files/nested/foo.org +++ b/tests/roam-files/nested/foo.org @@ -1,3 +1,3 @@ -#+TITLE: Nested Foo +#+title: Nested Foo This file has no links. diff --git a/tests/roam-files/tags/no_tag.org b/tests/roam-files/tags/no_tag.org index 3e78f2b..ad8984f 100644 --- a/tests/roam-files/tags/no_tag.org +++ b/tests/roam-files/tags/no_tag.org @@ -1,3 +1,3 @@ -#+TITLE: Tagless File +#+title: Tagless File -This file has no tags, and should not yield any tags on extracting via =#+ROAM_TAGS=. +This file has no tags, and should not yield any tags on extracting via ~#+roam_tags~. diff --git a/tests/roam-files/tags/tag.org b/tests/roam-files/tags/tag.org index 68d8170..206b026 100644 --- a/tests/roam-files/tags/tag.org +++ b/tests/roam-files/tags/tag.org @@ -1,4 +1,4 @@ -#+ROAM_TAGS: "t1" "t2 with space" t3 -#+TITLE: Tags +#+roam_tags: "t1" "t2 with space" t3 +#+title: Tags This file is used to test functionality for =(org-roam--extract-tags)= diff --git a/tests/roam-files/titles/aliases.org b/tests/roam-files/titles/aliases.org index ab6d12c..440dd78 100644 --- a/tests/roam-files/titles/aliases.org +++ b/tests/roam-files/titles/aliases.org @@ -1 +1 @@ -#+ROAM_ALIAS: "roam" "alias" +#+roam_alias: "roam" "alias" diff --git a/tests/roam-files/titles/combination.org b/tests/roam-files/titles/combination.org index 4ed12c0..34ec92f 100644 --- a/tests/roam-files/titles/combination.org +++ b/tests/roam-files/titles/combination.org @@ -1,4 +1,4 @@ -#+TITLE: TITLE PROP -#+ROAM_ALIAS: "roam" "alias" +#+title: TITLE PROP +#+roam_alias: "roam" "alias" * Headline diff --git a/tests/roam-files/titles/title.org b/tests/roam-files/titles/title.org index d125f61..a241bc4 100644 --- a/tests/roam-files/titles/title.org +++ b/tests/roam-files/titles/title.org @@ -1 +1 @@ -#+TITLE: Title +#+title: Title diff --git a/tests/roam-files/unlinked.org b/tests/roam-files/unlinked.org index 2f72967..0059965 100644 --- a/tests/roam-files/unlinked.org +++ b/tests/roam-files/unlinked.org @@ -1,3 +1,3 @@ -#+TITLE: Unlinked +#+title: Unlinked Nothing links here :( diff --git a/tests/roam-files/web_ref.org b/tests/roam-files/web_ref.org index 166a976..c5acfd4 100644 --- a/tests/roam-files/web_ref.org +++ b/tests/roam-files/web_ref.org @@ -1 +1 @@ -#+ROAM_KEY: https://google.com/ +#+roam_key: https://google.com/