branch: externals/denote
commit e20511b0fe54d4f348593d4d106dbc8bf77a873c
Author: Elias Storms <elias.sto...@gmail.com>
Commit: Protesilaos Stavrou <i...@protesilaos.com>
Update manual on Org Dynamic blocks
---
README.org | 37 +++++++++++++++++++------------------
1 file changed, 19 insertions(+), 18 deletions(-)
diff --git a/README.org b/README.org
index 6aa38ce8bd..da2d9d6ab4 100644
--- a/README.org
+++ b/README.org
@@ -1664,20 +1664,21 @@ facility. Start by loading the relevant library:
(require 'denote-org-dblock)
#+end_src
-A dynamic block gets its contents by evaluating a given function. The
-function and its parameters are stated in the opening =#+BEGIN= line
-of the block. Typing =C-c C-c= with point on that line runs the
-function, with the given arguments, and populates the block's contents
-accordingly.
+A dynamic block gets its contents by evaluating a given function,
+depending on the type of block. The type of block and its parameters
+are stated in the opening =#+BEGIN= line of the block. Typing =C-c C-c=
+with point on that line runs the function, with the given arguments,
+and populates the block's contents accordingly.
Denote leverages Org dynamic blocks to streamline the inclusion of (i)
-links that match a given search query and (ii) backlinks to the
-current note.
+links to notes whose name matches a given search query (like
+~denote-link-add-links~) and (ii) backlinks to the current note (like
+~denote-link-add-backlinks~).
-The two blocks that Denote registers are named =denote-links= and
-=denote-backlinks=. The latter does not accept any parameters, while
-the former does, which we explain below by also demonstrating how
-dynamic blocks are written.
+These two types of blocks are named =denote-links= and =denote-backlinks=
+respectively. The latter does not accept any parameters, while the
+former does, which we explain below by also demonstrating how dynamic
+blocks are written.
A dynamic block looks like this:
@@ -1686,7 +1687,7 @@ A dynamic block looks like this:
: #+END:
Here we have the =denote-links= type, with the =:regexp= parameter.
-The value of the =:regexp= parameter iss the same as that of the
+The value of the =:regexp= parameter is the same as that of the
command ~denote-link-add-links~
([[#h:9bec2c83-36ca-4951-aefc-7187c5463f90][Insert links matching a regexp]]).
The
linked entry provides practical examples of patterns that make good
use of Denote's file-naming scheme
([[#h:4e9c7512-84dc-4dfb-9fa9-e15d51178e5d][The file-naming scheme]]).
@@ -1708,13 +1709,13 @@ Becomes something like this once we type =C-c C-c= with
point on the
: #+END:
The dynamic block takes care to keep the list in order and to add any
-missing links.
+missing links when the block is evaluated anew.
-Depending on one's workflow, an additional dynamic block can be
-included in the file to list only those links which are missing from
-the original dynamic block (e.g. due to new notes being added over
-time). Adding the =:missing-only= parameter with a non-~nil~ value
-achieves this effect. The =#+BEGIN= line looks like this:
+Depending on one's workflow, the dynamic block can be instructed to
+list only those links which are missing from the current buffer
+(similar to ~denote-link-add-missing-links~). Adding the =:missing-only=
+parameter with a non-~nil~ value achieves this effect. The =#+BEGIN= line
+looks like this:
: #+BEGIN: denote-links :regexp "_journal" :missing-only t
