(docs)capture: document default-val syntax and available expansions (o…

…rg-roam#1721) Closes org-roam#1399.
heyste · Aug 1, 2021 · 1d03f87 · 1d03f87
1 parent 48d1c15
commit 1d03f87
Show file tree

Hide file tree

Showing 2 changed files with 37 additions and 0 deletions.
diff --git a/doc/org-roam.org b/doc/org-roam.org
@@ -941,6 +941,23 @@ strings. ~${foo}~'s substitution is performed as follows:
 3. Else look up ~org-roam-capture--info~ for ~foo~. This is an internal variable
    that is set before the capture process begins.
 4. If none of the above applies, read a string using ~completing-read~.
+   a. Org-roam also provides the ~${foo=default_val}~ syntax, where if a default
+      value is provided, will be the initial value for the ~foo~ key during
+      minibuffer completion.
+
+One can check the list of available keys for nodes by inspecting the
+~org-roam-node~ struct. At the time of writing, it is:
+
+#+begin_src emacs-lisp
+  (cl-defstruct (org-roam-node (:constructor org-roam-node-create)
+                               (:copier nil))
+    "A heading or top level file with an assigned ID property."
+    file file-hash file-atime file-mtime
+    id level point todo priority scheduled deadline title properties olp
+    tags aliases refs)
+#+end_src
+
+This makes ~${file}~, ~${file-hash}~ etc. all valid substitutions.
 
 * Graphing
 

diff --git a/doc/org-roam.texi b/doc/org-roam.texi
@@ -1369,7 +1369,27 @@ that is set before the capture process begins.
 
 @item
 If none of the above applies, read a string using @code{completing-read}.
+@itemize
+@item
+Org-roam also provides the @code{$@{foo=default_val@}} syntax, where if a default
+value is provided, will be the initial value for the @code{foo} key during
+minibuffer completion.
 @end itemize
+@end itemize
+
+One can check the list of available keys for nodes by inspecting the
+@code{org-roam-node} struct. At the time of writing, it is:
+
+@lisp
+(cl-defstruct (org-roam-node (:constructor org-roam-node-create)
+                             (:copier nil))
+  "A heading or top level file with an assigned ID property."
+  file file-hash file-atime file-mtime
+  id level point todo priority scheduled deadline title properties olp
+  tags aliases refs)
+@end lisp
+
+This makes @code{$@{file@}}, @code{$@{file-hash@}} etc. all valid substitutions.
 
 @node Graphing
 @chapter Graphing