branch: externals/denote
commit c1b0fecc701c42112997d933946ed8eb8b412c91
Author: Protesilaos Stavrou <i...@protesilaos.com>
Commit: Protesilaos Stavrou <i...@protesilaos.com>
Document new linking commands for direct links to files with content match
(per commit ba08101)
---
README.org | 186 +++++++++++++++++++++++++++++++++++++++++--------------------
1 file changed, 125 insertions(+), 61 deletions(-)
diff --git a/README.org b/README.org
index 140bcd193f..e4cc905322 100644
--- a/README.org
+++ b/README.org
@@ -2592,7 +2592,7 @@ by Denote:
The following sections cover all the details
([[#h:4f354db1-aa78-47fd-ac60-c3d1e0f0b0a4][Why are some Org links opening
outside Emacs?]]).
-** Adding a single direct link
+** Add a single direct link using a file name prompt
:PROPERTIES:
:CUSTOM_ID: h:5e5e3370-12ab-454f-ba09-88ff44214324
:END:
@@ -2622,6 +2622,13 @@ By default, the description of the link is determined
thus:
name.
- If the target file has no signature, the title is used.
+To insert multiple such links at once, use the command
+~denote-add-links~ ([[#h:9bec2c83-36ca-4951-aefc-7187c5463f90][Insert links
matching a regexp in their file name]]).
+
+If you want to directly link to a single file whose contents match a
+given query, then use the command ~denote-link-to-file-with-contents~
+([[#h:25a983ca-049e-43d4-8f6e-06a2325e2c3c][Adding a direct link to a file
whose contents include the given query]]).
+
#+vindex: denote-faces-link
Links are styled with the ~denote-faces-link~ face, which looks
exactly like an ordinary link by default.
@@ -2631,7 +2638,33 @@ exactly like an ordinary link by default.
Other file types do not have the features of Org, so we cannot
generalise this. ]
-** Adding a query link
+** Add a direct link to a file whose contents include the given query
+:PROPERTIES:
+:CUSTOM_ID: h:25a983ca-049e-43d4-8f6e-06a2325e2c3c
+:END:
+
+[ The ~denote-link-to-file-with-contents~ is part of
{{{development-version}}}. ]
+
+#+findex: denote-link-to-file-with-contents
+The ~denote-link~ command that we covered before prompts to select a
+file among those in the ~denote-directory~
([[#h:5e5e3370-12ab-454f-ba09-88ff44214324][Adding a single direct link using a
file name prompt]]).
+The match is done against the file's name. Users may, however, be
+interested to create a link to a file whose contents include some
+text, regardless of how the file name is called. To this end, the
+command ~denote-link-to-file-with-contents~, (i) prompts for a query
+which is a plain string or regular expression, (ii) if there are
+matching files, asks to select one among them, and (iii) inserts the
+direct link at point.
+
+When called with an optional prefix argument (=C-u= by default), the
+command ~denote-link-to-file-with-contents~ creates a link that does
+not include a description for the target file: it just has the file's
+identifier (same as with ~denote-link~).
+
+The command ~denote-link-to-file-with-contents~ is the counterpart of
+~denote-link-to-all-files-with-contents~
([[#h:299d3aeb-9946-489e-bd91-e06f8c4ae2a9][Insert links to all files matching
a query in their contents]]).
+
+** Add a query link
:PROPERTIES:
:CUSTOM_ID: h:d9a84289-2f73-4ef9-b4f0-9a0aa3e9bf0d
:END:
@@ -2671,6 +2704,94 @@ The user option
~denote-query-links-display-buffer-action~ controls
the placement of query link buffers. By default, they are designed to
appear below the current window.
+#+vindex: denote-faces-query-link
+Query links are styled with the ~denote-faces-query-link~ face, which
+looks a bit different that ~denote-faces-link~ (though this depends on
+the active theme).
+
+** Insert links to all files matching a query in their file name
+:PROPERTIES:
+:CUSTOM_ID: h:9bec2c83-36ca-4951-aefc-7187c5463f90
+:END:
+
+#+findex: denote-add-links
+The command ~denote-add-links~ adds links at point to all file names
+in the ~denote-directory~ that match a regular expression or plain
+string. This is similar to the ~denote-link~ command, which
+establishes a direct link to a specified file
([[#h:5e5e3370-12ab-454f-ba09-88ff44214324][Adding a single direct link]]).
+Links to files whose names match the given search terms are inserted
+as a typographic list, such as:
+
+#+begin_example
+- link1
+- link2
+- link3
+#+end_example
+
+Each link is formatted according to the file type of the current note,
+as explained further above about the ~denote-link~ command. The current
+note is excluded from the matching entries (adding a link to itself is
+pointless).
+
+When called with a prefix argument (=C-u=) ~denote-add-links~ will
+format all links as =[[denote:IDENTIFIER]]=, hence a typographic list:
+
+#+begin_example
+- [[denote:IDENTIFIER-1]]
+- [[denote:IDENTIFIER-2]]
+- [[denote:IDENTIFIER-3]]
+#+end_example
+
+Same examples of a regular expression that can be used with this
+command:
+
+- =journal= match all files which include =journal= anywhere in their
+ name.
+
+- =_journal= match all files which include =journal= as a keyword.
+
+- =^2022.*_journal= match all file names starting with =2022= and
+ including the keyword =journal=.
+
+- =\.txt= match all files including =.txt=. In practical terms, this
+ only applies to the file extension, as Denote automatically removes
+ dots (and other characters) from the base file name.
+
+If files are created with ~denote-sort-keywords~ as non-nil (the
+default), then it is easy to write a regexp that includes multiple
+keywords in alphabetic order:
+
+- =_denote.*_package= match all files that include both the =denote= and
+ =package= keywords, in this order.
+
+- =\(.*denote.*package.*\)\|\(.*package.*denote.*\)= is the same as
+ above, but out-of-order.
+
+Remember that regexp constructs only need to be escaped once (like =\|=)
+when done interactively but twice when called from Lisp. What we show
+above is for interactive usage.
+
+Links are created only for files which qualify as a "note" for our
+purposes ([[#h:fc913d54-26c8-4c41-be86-999839e8ad31][Linking notes]]).
+
+** Insert links to all files matching a query in their contents
+:PROPERTIES:
+:CUSTOM_ID: h:299d3aeb-9946-489e-bd91-e06f8c4ae2a9
+:END:
+
+[ The command ~denote-link-to-all-files-with-contents~ is part of
{{{development-version}}}. ]
+
+#+findex: denote-link-to-all-files-with-contents
+The aforementioned ~denote-add-links~ command takes a query that
+matches it against file names
([[#h:9bec2c83-36ca-4951-aefc-7187c5463f90][Insert links to all files matching
a query in their file name]]).
+It then creates a typographic list (bullet list) with direct links to
+all the matching files. Users who wish to achieve the same result but
+have the query be matched against file contents (not file names), can
+use the command ~denote-link-to-all-files-with-contents~.
+
+The command ~denote-link-to-all-files-with-contents~ is the
+counterpart of ~denote-link-to-file-with-contents~
([[#h:25a983ca-049e-43d4-8f6e-06a2325e2c3c][Add a direct link to a file whose
contents include the given query]]).
+
** The ~denote-open-link-function~ user option
:PROPERTIES:
:CUSTOM_ID: h:6aa22a2d-3338-433e-ab9f-ba272417aab9
@@ -2758,68 +2879,11 @@ navigates to that heading.
invoked in one such file, it captures only the Denote identifier of
the file, even if this user option is set to a non-nil value. ]
-** Insert links matching a regexp
+** Adding direct links to files matching contents
:PROPERTIES:
-:CUSTOM_ID: h:9bec2c83-36ca-4951-aefc-7187c5463f90
+:CUSTOM_ID: h:28cb8d14-cf56-4d73-b126-8ff269dbaa64
:END:
-#+findex: denote-add-links
-The command ~denote-add-links~ adds links at point matching a
-regular expression or plain string. The links are inserted as a
-typographic list, such as:
-
-#+begin_example
-- link1
-- link2
-- link3
-#+end_example
-
-Each link is formatted according to the file type of the current note,
-as explained further above about the ~denote-link~ command. The current
-note is excluded from the matching entries (adding a link to itself is
-pointless).
-
-When called with a prefix argument (=C-u=) ~denote-add-links~ will
-format all links as =[[denote:IDENTIFIER]]=, hence a typographic list:
-
-#+begin_example
-- [[denote:IDENTIFIER-1]]
-- [[denote:IDENTIFIER-2]]
-- [[denote:IDENTIFIER-3]]
-#+end_example
-
-Same examples of a regular expression that can be used with this
-command:
-
-- =journal= match all files which include =journal= anywhere in their
- name.
-
-- =_journal= match all files which include =journal= as a keyword.
-
-- =^2022.*_journal= match all file names starting with =2022= and
- including the keyword =journal=.
-
-- =\.txt= match all files including =.txt=. In practical terms, this
- only applies to the file extension, as Denote automatically removes
- dots (and other characters) from the base file name.
-
-If files are created with ~denote-sort-keywords~ as non-nil (the
-default), then it is easy to write a regexp that includes multiple
-keywords in alphabetic order:
-
-- =_denote.*_package= match all files that include both the =denote= and
- =package= keywords, in this order.
-
-- =\(.*denote.*package.*\)\|\(.*package.*denote.*\)= is the same as
- above, but out-of-order.
-
-Remember that regexp constructs only need to be escaped once (like =\|=)
-when done interactively but twice when called from Lisp. What we show
-above is for interactive usage.
-
-Links are created only for files which qualify as a "note" for our
-purposes ([[#h:fc913d54-26c8-4c41-be86-999839e8ad31][Linking notes]]).
-
** Insert links from marked files in Dired
:PROPERTIES:
:CUSTOM_ID: h:9cbb692e-5d8a-44a6-9193-899a07872a07
