diff --git a/Makefile b/Makefile index 9ebb858..c314f92 100644 --- a/Makefile +++ b/Makefile @@ -1,6 +1,7 @@ .PHONY: clean clean: eldev clean all + $(MAKE) -C doc clean .PHONY: prepare prepare: @@ -14,16 +15,17 @@ lint: test: eldev -C --unstable -T test +.PHONY: docs docs: - make -C doc all + $(MAKE) -C doc +.PHONY: html html: - make -C doc html-dir + $(MAKE) -C doc html +.PHONY: install install: install-docs -install-docs: docs - make -C doc install-docs - -install-info: info - make -C doc install-info +.PHONY: install-docs +install-docs: + $(MAKE) -C doc install diff --git a/default.mk b/default.mk deleted file mode 100644 index 3afa60a..0000000 --- a/default.mk +++ /dev/null @@ -1,107 +0,0 @@ -TOP := $(dir $(lastword $(MAKEFILE_LIST))) - -## User options ###################################################### -# -# You can override these settings in "config.mk" or on the command -# line. -# -# You might also want to set LOAD_PATH. If you do, then it must -# contain "-L .". -# -# If you don't do so, then the default is set in the "Load-Path" -# section below. The default assumes that all dependencies are -# installed either at "../", or when using package.el -# at "ELPA_DIR/-". - -sharedir ?= $(HOME)/.local/share -lispdir ?= $(sharedir)/emacs/site-lisp/org-roam -infodir ?= $(sharedir)/info -docdir ?= $(sharedir)/doc/org-roam -statsdir ?= $(TOP)/doc/stats - -CP ?= install -p -m 644 -MKDIR ?= install -p -m 755 -d -RMDIR ?= rm -rf -TAR ?= tar -SED ?= sed - -EMACSBIN ?= emacs -BATCH = $(EMACSBIN) -Q --batch $(LOAD_PATH) - -INSTALL_INFO ?= $(shell command -v ginstall-info || printf install-info) -MAKEINFO ?= makeinfo -MANUAL_HTML_ARGS ?= --css-ref /assets/page.css - -## Files ############################################################# - -PKG = org-roam -PACKAGES = org-roam - -TEXIPAGES = $(addsuffix .texi,$(PACKAGES)) -INFOPAGES = $(addsuffix .info,$(PACKAGES)) -HTMLFILES = $(addsuffix .html,$(PACKAGES)) -HTMLDIRS = $(PACKAGES) -PDFFILES = $(addsuffix .pdf,$(PACKAGES)) -EPUBFILES = $(addsuffix .epub,$(PACKAGES)) - -ELS = org-roam.el -ELS += org-roam-capture.el -ELS += org-roam-compat.el -ELS += org-roam-db.el -ELS += org-roam-mode.el -ELS += org-roam-node.el -ELS += org-roam-utils.el -ELS += extensions/org-roam-dailies.el -ELS += extensions/org-roam-graph.el -ELS += extensions/org-roam-overlay.el -ELS += extensions/org-roam-protocol.el -ELCS = $(ELS:.el=.elc) -ELMS = org-roam.el $(filter-out $(addsuffix .el,$(PACKAGES)),$(ELS)) -ELGS = org-roam-autoloads.el org-roam-version.el - -## Versions ########################################################## - -VERSION ?= $(shell test -e $(TOP).git && git describe --tags --abbrev=0 | cut -c2-) - -EMACS_VERSION = 26.1 - -EMACSOLD := $(shell $(BATCH) --eval \ - "(and (version< emacs-version \"$(EMACS_VERSION)\") (princ \"true\"))") -ifeq "$(EMACSOLD)" "true" - $(error At least version $(EMACS_VERSION) of Emacs is required) -endif - -## Load-Path ######################################################### - -ifndef LOAD_PATH - -ELPA_DIR ?= $(HOME)/.emacs.d/elpa - -SYSTYPE := $(shell $(EMACSBIN) -Q --batch --eval "(princ system-type)") -ifeq ($(SYSTYPE), windows-nt) - CYGPATH := $(shell cygpath --version 2>/dev/null) -endif - -LOAD_PATH = -L $(TOP) - -# When making changes here, then don't forget to adjust "Makefile", -# ".travis.yml", ".github/ISSUE_TEMPLATE/bug_report.md", -# `magit-emacs-Q-command' and the "Installing from the Git Repository" -# info node accordingly. Also don't forget to "rgrep \b\b". - -endif # ifndef LOAD_PATH - -ifndef ORG_LOAD_PATH -ORG_LOAD_PATH = $(LOAD_PATH) -ORG_LOAD_PATH += -L $(TOP)../ox-texinfo-plus -ORG_LOAD_PATH += -L $(TOP)../org-mode/contrib/lisp -ORG_LOAD_PATH += -L $(TOP)../org-mode/lisp -endif - -## Publish ########################################################### - -PUBLISH_TARGETS ?= html html-dir pdf epub - -DOCBOOK_XSL ?= /usr/share/xml/docbook/stylesheet/docbook-xsl/epub/docbook.xsl - -EPUBTRASH = epub.xml META-INF OEBPS diff --git a/doc/AUTHORS.md b/doc/AUTHORS.md deleted file mode 100644 index 75857cc..0000000 --- a/doc/AUTHORS.md +++ /dev/null @@ -1,37 +0,0 @@ -Authors -======= - -The following people have contributed to Org-Roam. - -Names below are sorted alphabetically. - -Author ------- - -- Jethro Kuan - -Maintainers ----------- - -- Jethro Kuan -- Leo Vivier - -Contributors ------------- - -- Alexey Shmalko -- James Ravn -- Jethro Kuan -- Johann Klähn -- Josh English -- Jürgen Hötzel -- Langston Barrett -- Leo Vivier -- Michael Glaesemann -- Michael Herold -- Noboru -- N V <44036031+progfolio@users.noreply.github.com> -- Rafael Accácio Nogueira -- Roland Coeurjoly -- Sayan -- Tim Quelch diff --git a/doc/Makefile b/doc/Makefile index 9e92575..3b9323b 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -1,127 +1,94 @@ -include ../config.mk -include ../default.mk -################################################################### -MANUAL_HTML_ARGS = --css-ref assets/page.css +## User options ###################################################### +# +# You can override these settings in "config.mk" or on the command +# line. -.PHONY: texi install clean AUTHORS.md stats +sharedir ?= $(HOME)/.local/share +infodir ?= $(sharedir)/info -all: info +EMACS ?= emacs +BATCH = $(EMACS) -Q --batch + +INSTALL_INFO ?= $(shell command -v ginstall-info || printf install-info) +MAKEINFO ?= makeinfo +MANUAL_HTML_ARGS ?= --css-ref assets/page.css + +## Files ############################################################# + +PKG = org-roam +PACKAGES = org-roam + +INFOPAGES = $(addsuffix .info,$(PACKAGES)) +HTMLFILES = $(addsuffix .html,$(PACKAGES)) + +## Versions ########################################################## + +EMACS_VERSION = 26.1 + +EMACSOLD := $(shell $(BATCH) --eval \ + "(and (version< emacs-version \"$(EMACS_VERSION)\") (princ \"true\"))") +ifeq "$(EMACSOLD)" "true" + $(error At least version $(EMACS_VERSION) of Emacs is required) +endif + +###################################################################### + +.PHONY: default +default: info ## Build ############################################################# -info: $(INFOPAGES) dir -html: $(HTMLFILES) -pdf: $(PDFFILES) -epub: $(EPUBFILES) +.PHONY: info +info: dir + +dir: $(INFOPAGES) + @printf "Generating dir\n" + @echo $^ | xargs -n 1 $(INSTALL_INFO) --dir=$@ %.info: %.texi @printf "Generating $@\n" @$(MAKEINFO) --no-split $< -o $@ -dir: org-roam.info - @printf "Generating dir\n" - @echo $^ | xargs -n 1 $(INSTALL_INFO) --dir=$@ +.PHONY: html +html: $(HTMLFILES) + mv $(PKG).html manual.html %.html: %.texi @printf "Generating $@\n" @$(MAKEINFO) --html --no-split $(MANUAL_HTML_ARGS) $< -html-dir: - @$(MAKEINFO) --html --no-split $(MANUAL_HTML_ARGS) org-roam.texi - mv org-roam.html manual.html - -%.pdf: %.texi - @printf "Generating $@\n" - @texi2pdf --clean $< > /dev/null - -%.epub: %.texi - @printf "Generating $@\n" - @$(MAKEINFO) --docbook $< -o epub.xml - @xsltproc $(DOCBOOK_XSL) epub.xml 2> /dev/null - @echo "application/epub+zip" > mimetype - @zip -X --quiet --recurse-paths -0 $@ mimetype - @zip -X --quiet --recurse-paths -9 --no-dir-entries $@ META-INF OEBPS - @$(RMDIR) $(EPUBTRASH) - -## Install ########################################################### - -install: install-info install-docs - -install-docs: install-info - @$(MKDIR) $(DESTDIR)$(docdir) - $(CP) AUTHORS.md $(DESTDIR)$(docdir) - -install-info: info - @$(MKDIR) $(DESTDIR)$(infodir) - $(CP) $(INFOPAGES) $(DESTDIR)$(infodir) - -## Clean ############################################################# - -clean: - @printf "Cleaning doc/*...\n" - @$(RMDIR) dir $(INFOPAGES) $(HTMLFILES) $(HTMLDIRS) $(PDFFILES) - @$(RMDIR) $(EPUBFILES) $(EPUBTRASH) - -## Release management ################################################ - -ORG_ARGS = --batch -Q $(ORG_LOAD_PATH) -ORG_ARGS += -l ox-extra -l ox-texinfo+ -ORG_ARGS += --eval "(or (require 'org-man nil t) (require 'ol-man))" -ORG_EVAL = --eval "(ox-extras-activate '(ignore-headlines))" ORG_EVAL += --eval "(setq indent-tabs-mode nil)" ORG_EVAL += --eval "(setq org-src-preserve-indentation nil)" ORG_EVAL += --funcall org-texinfo-export-to-texinfo -# This target first bumps version strings in the Org source. The -# necessary tools might be missing so other targets do not depend -# on this target and it has to be run explicitly when appropriate. -# -# AMEND=t make texi Update manual to be amended to HEAD. -# VERSION=N make texi Update manual for release. -# -texi: - @$(EMACSBIN) $(ORG_ARGS) $(PKG).org $(ORG_EVAL) - @printf "\n" >> $(PKG).texi - @rm -f $(PKG).texi~ +# NOTE: %.org is not a prerequisite since package archives can’t generate texi +# from org. texi is generated on org save and committed to repo +%.texi: + @echo "Generating $@" + @$(BATCH) $*.org $(ORG_EVAL) -stats: - @printf "Generating statistics\n" - @gitstats -c style=/assets/stats.css -c max_authors=999 $(TOP) $(statsdir) +## Install ########################################################### -authors: AUTHORS.md +.PHONY: install +install: install-info -AUTHORS.md: - @printf "Generating AUTHORS.md..." - @test -e $(TOP).git \ - && (printf "$$AUTHORS_HEADER\n" > $@ \ - && git log --pretty=format:'- %aN <%aE>' | sort -u >> $@ \ - && printf "done\n" ; ) \ - || printf "FAILED (non-fatal)\n" +.PHONY: install-info +install-info: info + install -p -m 755 -d $(DESTDIR)$(infodir) + install -p -m 644 $(INFOPAGES) $(DESTDIR)$(infodir) -# Templates ########################################################## +## Clean ############################################################# -define AUTHORS_HEADER -Authors -======= +.PHONY: clean +clean: + @echo "Cleaning doc/*..." + @rm -rf dir $(INFOPAGES) $(HTMLFILES) -The following people have contributed to Org-Roam. +## Release management ################################################ -Names below are sorted alphabetically. - -Author ------- - -- Jethro Kuan - -Maintainers ----------- - -- Jethro Kuan -- Leo Vivier - -Contributors ------------- - -endef -export AUTHORS_HEADER +# Run VERSION=N make -C doc release-texi to explicitly set version when releasing +.PHONY: release-texi +release-texi: + VERSION=$(VERSION) $(MAKE) -B $(PKG).texi diff --git a/doc/org-roam.org b/doc/org-roam.org index f4bdf94..3792c46 100644 --- a/doc/org-roam.org +++ b/doc/org-roam.org @@ -1,23 +1,25 @@ #+title: Org-roam User Manual #+author: Jethro Kuan #+email: jethrokuan95@gmail.com -#+date: 2020-2025 +#+date: 2020-{{{year}}} #+language: en -#+texinfo_deffn: t #+texinfo_dir_category: Emacs -#+texinfo_dir_title: Org-roam: (org-roam). +#+texinfo_dir_name: Org-roam: (org-roam). #+texinfo_dir_desc: Roam Research for Emacs. -#+subtitle: for version 2.3.1 +#+subtitle: for {{{version}}} #+options: H:4 num:3 toc:nil creator:t ':t #+property: header-args :eval never +#+macro: version (eval (concat "version " (or (getenv "VERSION") (if-let* ((tag (ignore-errors (car (process-lines "git" "describe" "--tags" "--dirty=-devel" "--abbrev=0"))))) (replace-regexp-in-string "^v" "" tag) "")))) +#+macro: year (eval (format-time-string "%Y")) #+texinfo: @noindent -This manual is for Org-roam version 2.3.1. +This manual is for Org-roam {{{version}}}. #+BEGIN_QUOTE -Copyright (C) 2020-2025 Jethro Kuan +Copyright (C) 2020-{{{year}}} Jethro Kuan and the +Org-roam contributors 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 @@ -378,7 +380,7 @@ Node selection is achieved via the ~completing-read~ interface, typically through ~org-roam-node-read~. The presentation of these nodes are governed by ~org-roam-node-display-template~. -- Variable: org-roam-node-display-template +- Variable: org-roam-node-display-template :: Configures display formatting for Org-roam node. @@ -458,7 +460,7 @@ additionally trying to process these links. Use ~org-roam-db-extra-links-elements~ to specify which additional Org AST element types to consider. -- Variable: org-roam-db-extra-links-elements +- Variable: org-roam-db-extra-links-elements :: The list of Org element types to include for parsing by Org-roam. @@ -472,7 +474,7 @@ property drawers. For example, we would not want ~ROAM_REFS~ links to be self-referential. Hence, to exclude specific keys, we use ~org-roam-db-extra-links-exclude-keys~. -- Variable: org-roam-db-extra-links-exclude-keys +- Variable: org-roam-db-extra-links-exclude-keys :: Keys to ignore when mapping over links. @@ -491,7 +493,7 @@ However, depending on how large your Org files are, database updating can be a slow operation. You can disable the automatic updating of the database by setting ~org-roam-db-update-on-save~ to ~nil~. -- Variable: org-roam-db-update-on-save +- Variable: org-roam-db-update-on-save :: If t, update the Org-roam database upon saving the file. Disable this if your files are large and updating the database is slow. @@ -513,14 +515,14 @@ two main commands to use here: To bring up a buffer that tracks the current node at point, call ~M-x org-roam-buffer-toggle~. -- Function: org-roam-buffer-toggle +- Function: org-roam-buffer-toggle :: Toggle display of the ~org-roam-buffer~. To bring up a buffer that's dedicated for a specific node, call ~M-x org-roam-buffer-display-dedicated~. -- Function: org-roam-buffer-display-dedicated +- Function: org-roam-buffer-display-dedicated :: Launch node dedicated Org-roam buffer without visiting the node itself. @@ -649,12 +651,12 @@ To assign an alias to a node, add the "ROAM_ALIASES" property to the node: Alternatively, Org-roam provides some functions to add or remove aliases. -- Function: org-roam-alias-add alias +- Function: org-roam-alias-add alias :: Add ALIAS to the node at point. When called interactively, prompt for the alias to add. -- Function: org-roam-alias-remove +- Function: org-roam-alias-remove :: Remove an alias from the node at point. @@ -696,12 +698,12 @@ key and a URL at the same time. Org-roam also provides some functions to add or remove refs. -- Function: org-roam-ref-add ref +- Function: org-roam-ref-add ref :: Add REF to the node at point. When called interactively, prompt for the ref to add. -- Function: org-roam-ref-remove +- Function: org-roam-ref-remove :: Remove a ref from the node at point. @@ -798,7 +800,7 @@ to ~t~: (setq org-roam-completion-everywhere t) #+end_src -- Variable: org-roam-completion-everywhere +- Variable: org-roam-completion-everywhere :: When non-nil, provide link completion matching outside of Org links. @@ -1129,7 +1131,7 @@ generating images using [[https://graphviz.org/][Graphviz]]. The graph can also The entry point to graph creation is ~org-roam-graph~. -- Function: org-roam-graph & optional arg node +- Function: org-roam-graph & optional arg node :: Build and display a graph for NODE. ARG may be any of the following values: @@ -1138,7 +1140,7 @@ ARG may be any of the following values: - ~integer~ an integer argument ~N~ will show the graph for the connected components to node up to ~N~ steps away. -- User Option: org-roam-graph-executable +- User Option: org-roam-graph-executable :: Path to the graphing executable (in this case, Graphviz). Set this if Org-roam is unable to find the Graphviz executable on your system. @@ -1146,7 +1148,7 @@ ARG may be any of the following values: You may also choose to use ~neato~ in place of ~dot~, which generates a more compact graph layout. -- User Option: org-roam-graph-viewer +- User Option: org-roam-graph-viewer :: Org-roam defaults to using Firefox (located on PATH) to view the SVG, but you may choose to set it to: @@ -1172,22 +1174,22 @@ Graphviz provides many options for customizing the graph output, and Org-roam supports some of them. See https://graphviz.gitlab.io/_pages/doc/info/attrs.html for customizable options. -- User Option: org-roam-graph-filetype +- User Option: org-roam-graph-filetype :: The file type to generate for graphs. This defaults to ~"svg"~. -- User Option: org-roam-graph-extra-config +- User Option: org-roam-graph-extra-config :: Extra options passed to graphviz for the digraph (The "G" attributes). Example: ~'~(("rankdir" . "LR"))~ -- User Option: org-roam-graph-node-extra-config +- User Option: org-roam-graph-node-extra-config :: An alist of options to style the nodes. The car of the alist node type such as ~"id"~, or ~"http"~. The cdr of the list is another alist of Graphviz node options (the "N" attributes). -- User Option: org-roam-graph-edge-extra-config +- User Option: org-roam-graph-edge-extra-config :: Extra options for edges in the graphviz output (The "E" attributes). Example: ~'(("dir" . "back"))~ @@ -1201,11 +1203,11 @@ Org-journal with ~org-roam-dailies~. For ~org-roam-dailies~ to work, you need to define two variables: -- Variable: ~org-roam-dailies-directory~ +- Variable: org-roam-dailies-directory :: Path to daily-notes. This path is relative to ~org-roam-directory~. -- Variable: ~org-roam-dailies-capture-templates~ +- Variable: org-roam-dailies-capture-templates :: Capture templates for daily-notes in Org-roam. @@ -1227,31 +1229,31 @@ See [[*The Templating System][The Templating System]] for creating new templates ~org-roam-dailies~ provides these interactive functions: -- Function: ~org-roam-dailies-capture-today~ &optional goto +- Function: org-roam-dailies-capture-today &optional goto :: Create an entry in the daily note for today. When ~goto~ is non-nil, go to the note without creating an entry. -- Function: ~org-roam-dailies-goto-today~ +- Function: org-roam-dailies-goto-today :: Find the daily note for today, creating it if necessary. There are variants of those commands for ~-yesterday~ and ~-tomorrow~: -- Function: ~org-roam-dailies-capture-yesterday~ n &optional goto +- Function: org-roam-dailies-capture-yesterday n &optional goto :: Create an entry in the daily note for yesterday. With numeric argument ~n~, use the daily note ~n~ days in the past. -- Function: ~org-roam-dailies-goto-yesterday~ +- Function: org-roam-dailies-goto-yesterday :: With numeric argument N, use the daily-note N days in the future. There are also commands which allow you to use Emacs’s ~calendar~ to find the date -- Function: ~org-roam-dailies-capture-date~ +- Function: org-roam-dailies-capture-date :: Create an entry in the daily note for a date using the calendar. @@ -1260,21 +1262,21 @@ There are also commands which allow you to use Emacs’s ~calendar~ to find the With a 'C-u' prefix or when ~goto~ is non-nil, go the note without creating an entry. -- Function: ~org-roam-dailies-goto-date~ +- Function: org-roam-dailies-goto-date :: Find the daily note for a date using the calendar, creating it if necessary. Prefer past dates, unless ~prefer-future~ is non-nil. -- Function: ~org-roam-dailies-find-directory~ +- Function: org-roam-dailies-find-directory :: Find and open ~org-roam-dailies-directory~. -- Function: ~org-roam-dailies-goto-previous-note~ +- Function: org-roam-dailies-goto-previous-note :: When in an daily-note, find the previous one. -- Function: ~org-roam-dailies-goto-next-note~ +- Function: org-roam-dailies-goto-next-note :: When in an daily-note, find the next one. ** org-roam-export @@ -1664,13 +1666,12 @@ that extensions/customizations are robust to change, extensions should only use The node interface is cleanly defined using ~cl-defstruct~. The primary method to access nodes is ~org-roam-node-at-point~ and ~org-roam-node-read~: -- Function: org-roam-node-at-point &optional assert +- Function: org-roam-node-at-point &optional assert :: Return the node at point. If ASSERT, throw an error if there is no node at point. -- Function: org-roam-node-read &optional initial-input filter-fn sort-fn - require-match +- Function: org-roam-node-read &optional initial-input filter-fn sort-fn require-match :: Read and return an `org-roam-node'. INITIAL-INPUT is the initial minibuffer prompt value. FILTER-FN @@ -1705,7 +1706,7 @@ Org-roam applies some patching over Org's capture system to smooth out the user experience, and sometimes it is desirable to use Org-roam's capturing system instead. The exposed function to be used in extensions is ~org-roam-capture-~: -- Function: org-roam-capture- &key goto keys node info props templates +- Function: org-roam-capture- &key goto keys node info props templates :: Main entry point. GOTO and KEYS correspond to `org-capture' arguments. @@ -1735,7 +1736,8 @@ When GOTO is non-nil, go the note without creating an entry." :END: #+BEGIN_QUOTE -Copyright (C) 2020-2025 Jethro Kuan +Copyright (C) 2020-{{{year}}} Jethro Kuan and the +Org-roam contributors You can redistribute this document and/or modify it under the terms of the GNU General Public License as published by the Free Software @@ -1796,9 +1798,8 @@ an Org file code block (like =#+BEGIN_SRC emacs-lisp=). # Local Variables: # eval: (require 'ol-info) -# eval: (require 'ox-texinfo+ nil t) # eval: (auto-fill-mode +1) -# after-save-hook: (lambda nil (progn (require 'ox-texinfo nil t) (org-texinfo-export-to-info))) +# after-save-hook: org-texinfo-export-to-info # indent-tabs-mode: nil # org-src-preserve-indentation: nil # End: diff --git a/doc/org-roam.texi b/doc/org-roam.texi index 1238a7a..5fd5a41 100644 --- a/doc/org-roam.texi +++ b/doc/org-roam.texi @@ -8,7 +8,8 @@ @copying @quotation -Copyright (C) 2020-2025 Jethro Kuan +Copyright (C) 2020-2025 Jethro Kuan and the +Org-roam contributors You can redistribute this document and/or modify it under the terms of the GNU General Public License as published by the Free Software @@ -31,7 +32,7 @@ General Public License for more details. @finalout @titlepage @title Org-roam User Manual -@subtitle for version 2.3.1 +@subtitle for version 2.3.1-devel @author Jethro Kuan @page @vskip 0pt plus 1filll @@ -44,10 +45,11 @@ General Public License for more details. @noindent -This manual is for Org-roam version 2.3.1. +This manual is for Org-roam version 2.3.1-devel. @quotation -Copyright (C) 2020-2025 Jethro Kuan +Copyright (C) 2020-2025 Jethro Kuan and the +Org-roam contributors 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 @@ -626,10 +628,7 @@ Node selection is achieved via the @code{completing-read} interface, typically through @code{org-roam-node-read}. The presentation of these nodes are governed by @code{org-roam-node-display-template}. -@itemize -@item -Variable: org-roam-node-display-template - +@defvar org-roam-node-display-template Configures display formatting for Org-roam node. Patterns of form ``$@{field-name:length@}'' are interpolated based @@ -658,7 +657,7 @@ as many characters as possible and will be aligned accordingly. A closure can also be assigned to this variable in which case the closure is evaluated and the return value is used as the template. The closure must evaluate to a valid template string. -@end itemize +@end defvar If you're using a vertical completion framework, such as Ivy and Selectrum, Org-roam supports the generation of an aligned, tabular completion interface. @@ -720,33 +719,27 @@ additionally trying to process these links. Use @code{org-roam-db-extra-links-elements} to specify which additional Org AST element types to consider. -@itemize -@item -Variable: org-roam-db-extra-links-elements - +@defvar org-roam-db-extra-links-elements The list of Org element types to include for parsing by Org-roam. By default, when parsing Org's AST, links within keywords and property drawers are not parsed as links. Sometimes however, it is desirable to parse and cache these links (e.g. hiding links in a property drawer). -@end itemize +@end defvar Additionally, one may want to ignore certain keys from being excluded within property drawers. For example, we would not want @code{ROAM_REFS} links to be self-referential. Hence, to exclude specific keys, we use @code{org-roam-db-extra-links-exclude-keys}. -@itemize -@item -Variable: org-roam-db-extra-links-exclude-keys - +@defvar org-roam-db-extra-links-exclude-keys Keys to ignore when mapping over links. The car of the association list is the Org element type (e.g. keyword). The cdr is a list of case-insensitive strings to exclude from being treated as links. -@end itemize +@end defvar @node When to cache @section When to cache @@ -760,11 +753,8 @@ However, depending on how large your Org files are, database updating can be a slow operation. You can disable the automatic updating of the database by setting @code{org-roam-db-update-on-save} to @code{nil}. -@itemize -@item -Variable: org-roam-db-update-on-save -@end itemize - +@defvar org-roam-db-update-on-save +@end defvar If t, update the Org-roam database upon saving the file. Disable this if your files are large and updating the database is slow. @@ -790,22 +780,16 @@ new node at point. To bring up a buffer that tracks the current node at point, call @code{M-x org-roam-buffer-toggle}. -@itemize -@item -Function: org-roam-buffer-toggle - +@defun org-roam-buffer-toggle Toggle display of the @code{org-roam-buffer}. -@end itemize +@end defun To bring up a buffer that's dedicated for a specific node, call @code{M-x org-roam-buffer-display-dedicated}. -@itemize -@item -Function: org-roam-buffer-display-dedicated - +@defun org-roam-buffer-display-dedicated Launch node dedicated Org-roam buffer without visiting the node itself. -@end itemize +@end defun @menu * Navigating the Org-roam Buffer:: @@ -978,18 +962,14 @@ To assign an alias to a node, add the ``ROAM@math{_ALIASES}'' property to the no Alternatively, Org-roam provides some functions to add or remove aliases. -@itemize -@item -Function: org-roam-alias-add alias - +@defun org-roam-alias-add alias Add ALIAS to the node at point. When called interactively, prompt for the alias to add. +@end defun -@item -Function: org-roam-alias-remove - +@defun org-roam-alias-remove Remove an alias from the node at point. -@end itemize +@end defun @node Tags @section Tags @@ -1031,18 +1011,14 @@ key and a URL at the same time. Org-roam also provides some functions to add or remove refs. -@itemize -@item -Function: org-roam-ref-add ref - +@defun org-roam-ref-add ref Add REF to the node at point. When called interactively, prompt for the ref to add. +@end defun -@item -Function: org-roam-ref-remove - +@defun org-roam-ref-remove Remove a ref from the node at point. -@end itemize +@end defun @node Citations @chapter Citations @@ -1155,11 +1131,8 @@ to @code{t}: (setq org-roam-completion-everywhere t) @end lisp -@itemize -@item -Variable: org-roam-completion-everywhere -@end itemize - +@defvar org-roam-completion-everywhere +@end defvar When non-nil, provide link completion matching outside of Org links. @node Encryption @@ -1574,11 +1547,8 @@ generating images using @uref{https://graphviz.org/, Graphviz}. The graph can al The entry point to graph creation is @code{org-roam-graph}. -@itemize -@item -Function: org-roam-graph & optional arg node -@end itemize - +@defun org-roam-graph & optional arg node +@end defun Build and display a graph for NODE@. ARG may be any of the following values: @@ -1590,19 +1560,15 @@ ARG may be any of the following values: components to node up to @code{N} steps away. @end itemize -@itemize -@item -User Option: org-roam-graph-executable - +@defopt org-roam-graph-executable Path to the graphing executable (in this case, Graphviz). Set this if Org-roam is unable to find the Graphviz executable on your system. You may also choose to use @code{neato} in place of @code{dot}, which generates a more compact graph layout. +@end defopt -@item -User Option: org-roam-graph-viewer - +@defopt org-roam-graph-viewer Org-roam defaults to using Firefox (located on PATH) to view the SVG, but you may choose to set it to: @@ -1624,7 +1590,7 @@ the second option to set the browser and network file path: (let ((org-roam-graph-viewer "/mnt/c/Program Files/Mozilla Firefox/firefox.exe")) (org-roam-graph--open (concat "file://///wsl$/Ubuntu" file))))) @end lisp -@end itemize +@end defopt @menu * Graph Options:: @@ -1637,31 +1603,25 @@ Graphviz provides many options for customizing the graph output, and Org-roam supports some of them. See @uref{https://graphviz.gitlab.io/_pages/doc/info/attrs.html} for customizable options. -@itemize -@item -User Option: org-roam-graph-filetype - +@defopt org-roam-graph-filetype The file type to generate for graphs. This defaults to @code{"svg"}. +@end defopt -@item -User Option: org-roam-graph-extra-config - +@defopt org-roam-graph-extra-config Extra options passed to graphviz for the digraph (The ``G'' attributes). Example: @code{'~(("rankdir" . "LR"))} +@end defopt -@item -User Option: org-roam-graph-node-extra-config - +@defopt org-roam-graph-node-extra-config An alist of options to style the nodes. The car of the alist node type such as @code{"id"}, or @code{"http"}. The cdr of the list is another alist of Graphviz node options (the ``N'' attributes). +@end defopt -@item -User Option: org-roam-graph-edge-extra-config - +@defopt org-roam-graph-edge-extra-config Extra options for edges in the graphviz output (The ``E'' attributes). Example: @code{'(("dir" . "back"))} -@end itemize +@end defopt @node org-roam-dailies @section org-roam-dailies @@ -1679,17 +1639,13 @@ Org-journal with @code{org-roam-dailies}. For @code{org-roam-dailies} to work, you need to define two variables: -@itemize -@item -Variable: @code{org-roam-dailies-directory} - +@defvar org-roam-dailies-directory Path to daily-notes. This path is relative to @code{org-roam-directory}. +@end defvar -@item -Variable: @code{org-roam-dailies-capture-templates} - +@defvar org-roam-dailies-capture-templates Capture templates for daily-notes in Org-roam. -@end itemize +@end defvar Here is a sane default configuration: @@ -1710,71 +1666,56 @@ See @ref{The Templating System} for creating new templates. @code{org-roam-dailies} provides these interactive functions: -@itemize -@item -Function: @code{org-roam-dailies-capture-today} &optional goto - +@defun org-roam-dailies-capture-today &optional goto Create an entry in the daily note for today. When @code{goto} is non-nil, go to the note without creating an entry. +@end defun -@item -Function: @code{org-roam-dailies-goto-today} - +@defun org-roam-dailies-goto-today Find the daily note for today, creating it if necessary. -@end itemize +@end defun There are variants of those commands for @code{-yesterday} and @code{-tomorrow}: -@itemize -@item -Function: @code{org-roam-dailies-capture-yesterday} n &optional goto - +@defun org-roam-dailies-capture-yesterday n &optional goto Create an entry in the daily note for yesterday. With numeric argument @code{n}, use the daily note @code{n} days in the past. +@end defun -@item -Function: @code{org-roam-dailies-goto-yesterday} - +@defun org-roam-dailies-goto-yesterday With numeric argument N, use the daily-note N days in the future. -@end itemize +@end defun There are also commands which allow you to use Emacs’s @code{calendar} to find the date -@itemize -@item -Function: @code{org-roam-dailies-capture-date} - +@defun org-roam-dailies-capture-date Create an entry in the daily note for a date using the calendar. Prefer past dates, unless @code{prefer-future} is non-nil. With a 'C-u' prefix or when @code{goto} is non-nil, go the note without creating an entry. +@end defun -@item -Function: @code{org-roam-dailies-goto-date} - +@defun org-roam-dailies-goto-date Find the daily note for a date using the calendar, creating it if necessary. Prefer past dates, unless @code{prefer-future} is non-nil. +@end defun -@item -Function: @code{org-roam-dailies-find-directory} - +@defun org-roam-dailies-find-directory Find and open @code{org-roam-dailies-directory}. +@end defun -@item -Function: @code{org-roam-dailies-goto-previous-note} - +@defun org-roam-dailies-goto-previous-note When in an daily-note, find the previous one. +@end defun -@item -Function: @code{org-roam-dailies-goto-next-note} - +@defun org-roam-dailies-goto-next-note When in an daily-note, find the next one. -@end itemize +@end defun @node org-roam-export @section org-roam-export @@ -2283,17 +2224,12 @@ that extensions/customizations are robust to change, extensions should only use The node interface is cleanly defined using @code{cl-defstruct}. The primary method to access nodes is @code{org-roam-node-at-point} and @code{org-roam-node-read}: -@itemize -@item -Function: org-roam-node-at-point &optional assert - +@defun org-roam-node-at-point &optional assert Return the node at point. If ASSERT, throw an error if there is no node at point. +@end defun -@item -Function: org-roam-node-read &optional initial-input filter-fn sort-fn -require-match - +@defun org-roam-node-read &optional initial-input filter-fn sort-fn require-match Read and return an `org-roam-node'. INITIAL-INPUT is the initial minibuffer prompt value. FILTER-FN is a function to filter out nodes: it takes a single argument (an @@ -2302,7 +2238,7 @@ filtered out. SORT-FN is a function to sort nodes. See @code{org-roam-node-read-sort-by-file-mtime} for an example sort function. If REQUIRE-MATCH, the minibuffer prompt will require a match. -@end itemize +@end defun Once you obtain the node, you can use the accessors for the node, e.g. @code{org-roam-node-id} or @code{org-roam-node-todo}. @@ -2329,17 +2265,14 @@ Org-roam applies some patching over Org's capture system to smooth out the user experience, and sometimes it is desirable to use Org-roam's capturing system instead. The exposed function to be used in extensions is @code{org-roam-capture-}: -@itemize -@item -Function: org-roam-capture- &key goto keys node info props templates - +@defun org-roam-capture- &key goto keys node info props templates Main entry point. GOTO and KEYS correspond to `org-capture' arguments. INFO is a plist for filling up Org-roam's capture templates. NODE is an `org-roam-node' construct containing information about the node. PROPS is a plist containing additional Org-roam properties for each template. TEMPLATES is a list of org-roam templates. -@end itemize +@end defun An example of an extension using @code{org-roam-capture-} is @code{org-roam-dailies} itself: @@ -2421,5 +2354,5 @@ When GOTO is non-nil, go the note without creating an entry." @printindex vr -Emacs 30.1 (Org mode 9.7.29) +Emacs 30.1.90 (Org mode 9.7.25) @bye