[elpa] externals/denote 47d7d02503 5/7: Add subsections to the manual's documentation of developer-facing symbols

[ELPA Syncer]

branch: externals/denote
commit 47d7d02503fd676afdc7b4d671963ac39d091076
Author: Protesilaos Stavrou <info@protesilaos.com>
Commit: Protesilaos Stavrou <info@protesilaos.com>

    Add subsections to the manual's documentation of developer-facing symbols
---
 README.org | 305 ++++++++++++++++++++++++++++++++++---------------------------
 1 file changed, 171 insertions(+), 134 deletions(-)

diff --git a/README.org b/README.org
index fb8d3e7b80..d724dbb3cc 100644
--- a/README.org
+++ b/README.org
@@ -4735,6 +4735,13 @@ By contradistinction, a "private" form is declared with 
two hyphens in
 its symbol such as ~denote--file-extension~.  Do not use those as we
 might change them without further notice.
 
+The following sections cover the specifics.
+
+** Common building blocks for developers or advanced users
+:PROPERTIES:
+:CUSTOM_ID: h:c98aed45-341a-40a0-91ce-347a29c98ab4
+:END:
+
 #+vindex: denote-id-format
 + Variable ~denote-id-format~ :: Format of ID prefix of a note's
   filename.  The note's ID is derived from the date and time of its
@@ -4870,19 +4877,16 @@ might change them without further notice.
   ~denote-directory~ accepts a directory-local value for what we call
   "silos" ([[#h:15719799-a5ff-4e9a-9f10-4ca03ef8f6c5][Maintain separate 
directories for notes]]).
 
+** File path interface for developers or advanced users
+:PROPERTIES:
+:CUSTOM_ID: h:08e696e4-c9e1-48b4-8349-e53451aed1df
+:END:
+
 #+findex: denote-file-name-relative-to-denote-directory
 + Function ~denote-file-name-relative-to-denote-directory~ :: Return
   name of =FILE= relative to the variable ~denote-directory~.  =FILE=
   must be an absolute path.
 
-#+findex: denote-get-path-by-id
-+ Function ~denote-get-path-by-id~ :: Return absolute path of =ID=
-  string in ~denote-directory-files~.
-
-#+findex: denote-get-identifier-at-point
-+ Function ~denote-get-identifier-at-point~ :: Return the identifier
-  at point or =POINT=.
-
 #+findex: denote-slug-keep-only-ascii
 + Function ~denote-slug-keep-only-ascii~ :: Remove all non-ASCII
   characters from =STR= and replace them with spaces. This is useful
@@ -4912,18 +4916,6 @@ might change them without further notice.
 + Function ~denote-sluggify-keywords~ :: Sluggify =KEYWORDS=, which is
   a list of strings ([[#h:ae8b19a1-7f67-4258-96b3-370a72c43f4e][Sluggification 
of file name components]]).
 
-#+findex: denote-filetype-heuristics
-+ Function ~denote-filetype-heuristics~ :: Return likely file type of
-  =FILE=. If in the process of ~org-capture~, consider the file type to
-  be that of Org. Otherwise, use the file extension to detect the file
-  type of =FILE=.
-
-  If more than one file type correspond to this file extension, use
-  the first file type for which the :title-key-regexp in
-  ~denote-file-types~ matches in the file.
-
-  Return nil if the file type is not recognized.
-
 #+findex: denote-use-date
 + Function ~denote-use-date~ :: The date to be used in a note creation
   command. See the documentation of ~denote~ for acceptable values.
@@ -5003,6 +4995,19 @@ might change them without further notice.
   type extension. It can be an empty string or a nil value, in which
   case it is not added to the base file name.
 
+** Data retrieval interface for developers or advanced users
+:PROPERTIES:
+:CUSTOM_ID: h:9b32bf7d-1569-4495-801c-8835f022d72e
+:END:
+
+#+findex: denote-get-path-by-id
++ Function ~denote-get-path-by-id~ :: Return absolute path of =ID=
+  string in ~denote-directory-files~.
+
+#+findex: denote-get-identifier-at-point
++ Function ~denote-get-identifier-at-point~ :: Return the identifier
+  at point or =POINT=.
+
 #+findex: denote-extract-keywords-from-path
 + Function ~denote-extract-keywords-from-path~ :: Extract keywords
   from =PATH= and return them as a list of strings.  =PATH= must be a
@@ -5063,6 +5068,11 @@ might change them without further notice.
 + Function ~denote-retrieve-front-matter-keywords-line~ :: Return keywords line
   from =FILE= front matter per =FILE-TYPE=.
 
+** Prompt interface for developers or advanced users
+:PROPERTIES:
+:CUSTOM_ID: h:e9d05541-bd00-43b9-8146-8c4445f78f07
+:END:
+
 #+findex: denote-add-prompts
 + Function ~denote-add-prompts~ :: Add list of =ADDITIONAL-PROMPTS= to
   ~denote-prompts~. This is best done inside of a ~let~ to create a
@@ -5160,53 +5170,96 @@ might change them without further notice.
   completion category (so it works with packages such as ~marginalia~
   and ~embark~).
 
-#+findex: denote-rename-file-prompt
-- Function ~denote-rename-file-prompt~ :: Prompt to rename file named
-  =OLD-NAME= to =NEW-NAME=. If ~denote-rename-confirmations~ does not
-  contain ~modify-file-name~, return t without prompting.
+** Front matter interface for developers or advanced users
+:PROPERTIES:
+:CUSTOM_ID: h:80ddc044-5c64-4fb3-b4f4-2eaf6bceda3b
+:END:
 
-#+findex: denote-rename-file-and-buffer
-+ Function ~denote-rename-file-and-buffer~ :: Rename file named
-  =OLD-NAME= to =NEW-NAME=, updating buffer name.
+#+findex: denote-filetype-heuristics
++ Function ~denote-filetype-heuristics~ :: Return likely file type of
+  =FILE=. If in the process of ~org-capture~, consider the file type to
+  be that of Org. Otherwise, use the file extension to detect the file
+  type of =FILE=.
 
-#+findex: denote-prepend-front-matter
-+ Function ~denote-prepend-front-matter~ :: Prepend front matter to
-  =FILE=. The =TITLE=, =KEYWORDS=, =DATE=, =ID=, =SIGNATURE=, and
-  =FILE-TYPE= are passed from the renaming command and are used to
-  construct a new front matter block if appropriate. [ This function
-  is available as part of {{{development-version}}}. ]
+  If more than one file type correspond to this file extension, use
+  the first file type for which the :title-key-regexp in
+  ~denote-file-types~ matches in the file.
 
-#+findex: denote-rewrite-front-matter
-+ Function ~denote-rewrite-front-matter~ :: Rewrite front matter of
-  note after ~denote-rename-file~ (or related) The =FILE=, =TITLE=,
-  =KEYWORDS=, =SIGNATURE=, =DATE=, =IDENTIFIER=, and =FILE-TYPE=
-  arguments are given by the renaming command and are used to construct
-  new front matter values if appropriate. If ~denote-rename-confirmations~
-  contains ~rewrite-front-matter~, prompt to confirm the rewriting of
-  the front matter. Otherwise produce a ~y-or-n-p~ prompt to that
-  effect. [ This function is changed as part of {{{development-version}}}. ]
+  Return nil if the file type is not recognized.
 
-#+findex: denote-add-front-matter-prompt
-+ Function ~denote-add-front-matter-prompt~ :: Prompt to add a
-  front-matter to =FILE=. Return non-nil if a new front matter should
-  be added. If ~denote-rename-confirmations~ does not contain
-  ~add-front-matter~, return t without prompting.
+#+vindex: denote-org-front-matter
++ Variable ~denote-org-front-matter~ :: Specifies the Org front
+  matter.  It is passed to ~format~ with arguments =TITLE=, =DATE=,
+  =KEYWORDS=, =ID= ([[#h:7f918854-5ed4-4139-821f-8ee9ba06ad15][Change the 
front matter format]])
 
-#+findex: denote-rewrite-keywords
-+ Function ~denote-rewrite-keywords~ :: Rewrite =KEYWORDS= in =FILE=
-  outright according to =FILE-TYPE=. Do the same as
-  ~denote-rewrite-front-matter~ for keywords, but do not ask for
-  confirmation. With optional =SAVE-BUFFER=, save the buffer
-  corresponding to =FILE=. This function is for use in the commands
-  ~denote-keywords-add~, ~denote-keywords-remove~,
-  ~denote-dired-rename-files~, or related.
+#+vindex: denote-yaml-front-matter
++ Variable ~denote-yaml-front-matter~ :: Specifies the YAML (Markdown)
+  front matter.  It is passed to ~format~ with arguments =TITLE=,
+  =DATE=, =KEYWORDS=, =ID= ([[#h:7f918854-5ed4-4139-821f-8ee9ba06ad15][Change 
the front matter format]])
 
-#+findex: denote-update-dired-buffers
-+ Function ~denote-update-dired-buffers~ :: Update Dired buffers of
-  variable ~denote-directory~. Also revert the current Dired buffer
-  even if it is not inside the ~denote-directory~. Note that the
-  ~denote-directory~ accepts a directory-local value for what we
-  internally refer to as "silos" 
([[#h:15719799-a5ff-4e9a-9f10-4ca03ef8f6c5][Maintain separate directories for 
notes]]).
+#+vindex: denote-toml-front-matter
++ Variable ~denote-toml-front-matter~ :: Specifies the TOML (Markdown)
+  front matter.  It is passed to ~format~ with arguments =TITLE=,
+  =DATE=, =KEYWORDS=, =ID= ([[#h:7f918854-5ed4-4139-821f-8ee9ba06ad15][Change 
the front matter format]])
+
+#+vindex: denote-text-front-matter
++ Variable ~denote-text-front-matter~ :: Specifies the plain text
+  front matter.  It is passed to ~format~ with arguments =TITLE=,
+  =DATE=, =KEYWORDS=, =ID= ([[#h:7f918854-5ed4-4139-821f-8ee9ba06ad15][Change 
the front matter format]])
+
+#+findex: denote-date-org-timestamp
++ Function ~denote-date-org-timestamp~ :: Format =DATE= using the Org
+  inactive timestamp notation.
+
+#+findex: denote-date-rfc3339
++ Function ~denote-date-rfc3339~ :: Format =DATE= using the RFC3339
+  specification.
+
+#+findex: denote-date-iso-8601
++ Function ~denote-date-iso-8601~ :: Format =DATE= according to ISO
+  8601 standard.
+
+#+findex: denote-trim-whitespace
++ Function ~denote-trim-whitespace~ :: Trim whitespace around string
+  =S=.  This can be used in ~denote-file-types~ to format front
+  mattter.
+
+#+findex: denote-trim-whitespace-then-quotes
++ Function ~denote-trim-whitespace-then-quotes~ :: Trim whitespace
+  then quotes around string =S=.  This can be used in
+  ~denote-file-types~ to format front mattter.
+
+#+findex: denote-format-string-for-org-front-matter
++ Function ~denote-format-string-for-org-front-matter~ :: Return
+  string =S= as-is for Org or plain text front matter. If =S= is not a
+  string, return an empty string.
+
+#+findex: denote-format-string-for-md-front-matter
++ Function ~denote-format-string-for-md-front-matter~ :: Surround
+  string =S= with quotes. If =S= is not a string, return a literal
+  emptry string. This can be used in ~denote-file-types~ to format
+  front mattter.
+
+#+findex: denote-format-keywords-for-md-front-matter
++ Function ~denote-format-keywords-for-md-front-matter~ :: Format
+  front matter =KEYWORDS= for markdown file type.  =KEYWORDS= is a
+  list of strings.  Consult the ~denote-file-types~ for how this is
+  used.
+
+#+findex: denote-format-keywords-for-text-front-matter
++ Function ~denote-format-keywords-for-text-front-matter~ :: Format
+  front matter =KEYWORDS= for text file type.  =KEYWORDS= is a list of
+  strings.  Consult the ~denote-file-types~ for how this is used.
+
+#+findex: denote-format-keywords-for-org-front-matter
++ Function ~denote-format-keywords-for-org-front-matter~ :: Format
+  front matter =KEYWORDS= for org file type.  =KEYWORDS= is a list of
+  strings.  Consult the ~denote-file-types~ for how this is used.
+
+#+findex: denote-extract-keywords-from-front-matter
++ Function ~denote-extract-keywords-from-front-matter~ :: Format front
+  matter =KEYWORDS= for org file type.  =KEYWORDS= is a list of
+  strings.  Consult the ~denote-file-types~ for how this is used.
 
 #+vindex: denote-file-types
 + Variable ~denote-file-types~ :: Alist of ~denote-file-type~ and
@@ -5267,25 +5320,10 @@ might change them without further notice.
   If ~denote-file-type~ is nil, use the first element of this list for
   new note creation.  The default is ~org~.
 
-#+vindex: denote-org-front-matter
-+ Variable ~denote-org-front-matter~ :: Specifies the Org front
-  matter.  It is passed to ~format~ with arguments =TITLE=, =DATE=,
-  =KEYWORDS=, =ID= ([[#h:7f918854-5ed4-4139-821f-8ee9ba06ad15][Change the 
front matter format]])
-
-#+vindex: denote-yaml-front-matter
-+ Variable ~denote-yaml-front-matter~ :: Specifies the YAML (Markdown)
-  front matter.  It is passed to ~format~ with arguments =TITLE=,
-  =DATE=, =KEYWORDS=, =ID= ([[#h:7f918854-5ed4-4139-821f-8ee9ba06ad15][Change 
the front matter format]])
-
-#+vindex: denote-toml-front-matter
-+ Variable ~denote-toml-front-matter~ :: Specifies the TOML (Markdown)
-  front matter.  It is passed to ~format~ with arguments =TITLE=,
-  =DATE=, =KEYWORDS=, =ID= ([[#h:7f918854-5ed4-4139-821f-8ee9ba06ad15][Change 
the front matter format]])
-
-#+vindex: denote-text-front-matter
-+ Variable ~denote-text-front-matter~ :: Specifies the plain text
-  front matter.  It is passed to ~format~ with arguments =TITLE=,
-  =DATE=, =KEYWORDS=, =ID= ([[#h:7f918854-5ed4-4139-821f-8ee9ba06ad15][Change 
the front matter format]])
+** Link interface for developers or advanced users
+:PROPERTIES:
+:CUSTOM_ID: h:97b8eb9e-07e1-4992-8b59-2a0e3b65574b
+:END:
 
 #+vindex: denote-org-link-format
 + Variable ~denote-org-link-format~ :: Format of Org link to note.
@@ -5316,60 +5354,6 @@ might change them without further notice.
   an identifier-only link in its context.  The format of such links is
   ~denote-id-only-link-format~.
 
-#+findex: denote-date-org-timestamp
-+ Function ~denote-date-org-timestamp~ :: Format =DATE= using the Org
-  inactive timestamp notation.
-
-#+findex: denote-date-rfc3339
-+ Function ~denote-date-rfc3339~ :: Format =DATE= using the RFC3339
-  specification.
-
-#+findex: denote-date-iso-8601
-+ Function ~denote-date-iso-8601~ :: Format =DATE= according to ISO
-  8601 standard.
-
-#+findex: denote-trim-whitespace
-+ Function ~denote-trim-whitespace~ :: Trim whitespace around string
-  =S=.  This can be used in ~denote-file-types~ to format front
-  mattter.
-
-#+findex: denote-trim-whitespace-then-quotes
-+ Function ~denote-trim-whitespace-then-quotes~ :: Trim whitespace
-  then quotes around string =S=.  This can be used in
-  ~denote-file-types~ to format front mattter.
-
-#+findex: denote-format-string-for-org-front-matter
-+ Function ~denote-format-string-for-org-front-matter~ :: Return
-  string =S= as-is for Org or plain text front matter. If =S= is not a
-  string, return an empty string.
-
-#+findex: denote-format-string-for-md-front-matter
-+ Function ~denote-format-string-for-md-front-matter~ :: Surround
-  string =S= with quotes. If =S= is not a string, return a literal
-  emptry string. This can be used in ~denote-file-types~ to format
-  front mattter.
-
-#+findex: denote-format-keywords-for-md-front-matter
-+ Function ~denote-format-keywords-for-md-front-matter~ :: Format
-  front matter =KEYWORDS= for markdown file type.  =KEYWORDS= is a
-  list of strings.  Consult the ~denote-file-types~ for how this is
-  used.
-
-#+findex: denote-format-keywords-for-text-front-matter
-+ Function ~denote-format-keywords-for-text-front-matter~ :: Format
-  front matter =KEYWORDS= for text file type.  =KEYWORDS= is a list of
-  strings.  Consult the ~denote-file-types~ for how this is used.
-
-#+findex: denote-format-keywords-for-org-front-matter
-+ Function ~denote-format-keywords-for-org-front-matter~ :: Format
-  front matter =KEYWORDS= for org file type.  =KEYWORDS= is a list of
-  strings.  Consult the ~denote-file-types~ for how this is used.
-
-#+findex: denote-extract-keywords-from-front-matter
-+ Function ~denote-extract-keywords-from-front-matter~ :: Format front
-  matter =KEYWORDS= for org file type.  =KEYWORDS= is a list of
-  strings.  Consult the ~denote-file-types~ for how this is used.
-
 #+findex: denote-select-linked-file-prompt
 + Function ~denote-select-linked-file-prompt~ :: Prompt for linked
   file among =FILES=.
@@ -5422,6 +5406,59 @@ might change them without further notice.
   ~denote-directory-files~). At all times limit the search to text
   files.
 
+** Renaming files interface for developers or advanced users
+:PROPERTIES:
+:CUSTOM_ID: h:66d31f42-6092-493a-97db-83b217db9d96
+:END:
+
+#+findex: denote-rename-file-prompt
+- Function ~denote-rename-file-prompt~ :: Prompt to rename file named
+  =OLD-NAME= to =NEW-NAME=. If ~denote-rename-confirmations~ does not
+  contain ~modify-file-name~, return t without prompting.
+
+#+findex: denote-rename-file-and-buffer
++ Function ~denote-rename-file-and-buffer~ :: Rename file named
+  =OLD-NAME= to =NEW-NAME=, updating buffer name.
+
+#+findex: denote-prepend-front-matter
++ Function ~denote-prepend-front-matter~ :: Prepend front matter to
+  =FILE=. The =TITLE=, =KEYWORDS=, =DATE=, =ID=, =SIGNATURE=, and
+  =FILE-TYPE= are passed from the renaming command and are used to
+  construct a new front matter block if appropriate. [ This function
+  is available as part of {{{development-version}}}. ]
+
+#+findex: denote-rewrite-front-matter
++ Function ~denote-rewrite-front-matter~ :: Rewrite front matter of
+  note after ~denote-rename-file~ (or related) The =FILE=, =TITLE=,
+  =KEYWORDS=, =SIGNATURE=, =DATE=, =IDENTIFIER=, and =FILE-TYPE=
+  arguments are given by the renaming command and are used to construct
+  new front matter values if appropriate. If ~denote-rename-confirmations~
+  contains ~rewrite-front-matter~, prompt to confirm the rewriting of
+  the front matter. Otherwise produce a ~y-or-n-p~ prompt to that
+  effect. [ This function is changed as part of {{{development-version}}}. ]
+
+#+findex: denote-add-front-matter-prompt
++ Function ~denote-add-front-matter-prompt~ :: Prompt to add a
+  front-matter to =FILE=. Return non-nil if a new front matter should
+  be added. If ~denote-rename-confirmations~ does not contain
+  ~add-front-matter~, return t without prompting.
+
+#+findex: denote-rewrite-keywords
++ Function ~denote-rewrite-keywords~ :: Rewrite =KEYWORDS= in =FILE=
+  outright according to =FILE-TYPE=. Do the same as
+  ~denote-rewrite-front-matter~ for keywords, but do not ask for
+  confirmation. With optional =SAVE-BUFFER=, save the buffer
+  corresponding to =FILE=. This function is for use in the commands
+  ~denote-keywords-add~, ~denote-keywords-remove~,
+  ~denote-dired-rename-files~, or related.
+
+#+findex: denote-update-dired-buffers
++ Function ~denote-update-dired-buffers~ :: Update Dired buffers of
+  variable ~denote-directory~. Also revert the current Dired buffer
+  even if it is not inside the ~denote-directory~. Note that the
+  ~denote-directory~ accepts a directory-local value for what we
+  internally refer to as "silos" 
([[#h:15719799-a5ff-4e9a-9f10-4ca03ef8f6c5][Maintain separate directories for 
notes]]).
+
 * Troubleshoot Denote in a pristine environment
 :PROPERTIES:
 :CUSTOM_ID: h:9c4467d5-6480-4681-80fb-cd9717bf8b3b