Update to version 1.1.0

CHANGELOG.org

@@ -9,6 +9,209 @@ project's main git repository: <https://git.sr.ht/~protesilaos/denote>.
 The newest release is at the top.  For further details, please consult
 the manual: <https://protesilaos.com/emacs/denote>.
 
+* Version 1.1.0 on 2022-10-20
+:PROPERTIES:
+:CUSTOM_ID: h:8e0f536a-ab3b-4cab-82f7-529bc0e40dbd
+:END:
+
+** New commands or refinements to common use-cases
+:PROPERTIES:
+:CUSTOM_ID: h:5665e7ec-4f3a-4de3-8cb0-63d25a0db8c1
+:END:
+
++ The ~denote-link-add-missing-links~ is a companion to what we
+  already provide to produce a list of links to Denote files matching
+  a regular expression (the ~denote-link-add-links~).  This new
+  command adds links that are not already present in the current file.
+  So if you have a metanote that references, say, your journal entries
+  but have not updated it in a month, you can revisit the metanote,
+  invoke ~denote-link-add-missing-links~, and then type the search
+  terms (e.g. =_journal=) to include what remains.
+
+  Thanks to Elias Storms for the initial contribution, which was done
+  in pull request 108 on the GitHub mirror:
+  <https://github.com/protesilaos/denote/pull/108>.
+
+  Elias has assigned copyright to the Free Software Foundation.  It is
+  required for changes that exceed 15 lines in total.
+
++ The ~denote-link-find-backlink~ provides a minibuffer interface that
+  shows all backlinks to the current note.  It complements the
+  existing ~denote-link-backlinks~ command (which also has the alias
+ ~denote-link-show-backlinks-buffer~).  Each command has its own
+  niche: the minibuffer lets the user leverage powerful pattern
+  matching styles, such as those provided by the =orderless= package,
+  while the bespoke buffer provides an easy overview of what links to
+  the current note.
+
+  Thanks to Elias Storms for the original patch:
+  <https://lists.sr.ht/~protesilaos/denote/%3Cm2fsg6o2t6.fsf%40MBA21.fritz.box%3E#%3Cm2pmfam7yi.fsf@MBA21.fritz.box%3E>.
+
++ The ~denote-keywords-add~ and ~denote-keywords-remove~ are two
+  commands that interactively operate on the current note's front
+  matter to add or remove keywords.  They use the familiar keywords'
+  prompt which means, among others, that they can read more than one
+  keyword at a time.  To specify multiple keywords, separate each
+  input with a comma (or whatever the value of ~crm-separator~ is,
+  which should be a comma unless something out-of-the-ordinary is in
+  force).
+
+  Thanks to Elias Storms for the original patch, which was done as
+  part of a discussion on the mailing list and then iterated on:
+  <https://lists.sr.ht/~protesilaos/denote/%3Cm24jwvpbt2.fsf%40MBA21.fritz.box%3E#%3Cm28rlik0tc.fsf@MBA21.fritz.box%3E>.
+
++ The ~denote-link~ command will now recognise an active region and
+  use its text as the description of the inserted link.  The default
+  behaviour is to use the file's title from its front matter or file
+  name.  Thanks to Charanjit Singh for the original contribution,
+  which was done as part of pull request 109 on the GitHub mirror:
+  <https://github.com/protesilaos/denote/pull/109>.  A subsequent
+  tweak was implemented in pull request 110, following a discussion
+  with me: <https://github.com/protesilaos/denote/pull/110>.
+
+  Charanjit's contribution is below the ~15 line threshold and thus
+  does not require copyright assignment to the Free Software
+  Foundation.
+
++ The renaming operations are now aware of the underlying version
+  control system and will use the appropriate command when a VCS is
+  available.  In practice, renaming a file under, say, Git will
+  register it as a "rename" instead of two separate actions of
+  deletion and addition.
+
+  Thanks to Florian for the patch.  It was discussed on the mailing
+  list and then underwent some changes:
+  <https://lists.sr.ht/~protesilaos/denote/%3C166547153518.8.941129310186454444.68125516@aboulafia.org%3E>.
+
++ The ~denote-rename-file-using-front-matter~ no longer fails to carry
+  out its intended task when the front matter has no keywords.  If no
+  keywords are available, this is interpreted as a request to remove
+  the KEYWORDS component of the file name.  This was always
+  technically possible and could be achieved with various permutations
+  of the user option ~denote-prompts~ (as explained in its doc string
+  or the manual).  Denote only needs an identifier in the file name to
+  establish unique links (although I strongly encourage you to stick
+  to the standard file-naming scheme as it is informative, reliable,
+  and can work even if you access your data without Emacs).
+
+** For more advanced use-cases
+:PROPERTIES:
+:CUSTOM_ID: h:505c84dd-2959-4bd4-8af4-78d75592a6d5
+:END:
+
++ The variable ~denote-file-types~ has been tweaked to respond
+  directly to changes in its value done with ~setq~.  Thanks to Noboru
+  Ota for the patch: <https://lists.sr.ht/~protesilaos/denote/%3C86k05gsqsg.fsf%40nobiot.com%3E>.
+
+  Noboru has assigned copyright to the Free Software Foundation.
+
++ The =:front-matter= property of the ~denote-file-types~ now accepts
+  a nil value.  Denote could always work without front matter, but
+  this was not implemented flexibly in the ~denote-file-types~.
+  Thanks to Noboru Ota (nobiot) for pointing this out on the mailing
+  list: <https://lists.sr.ht/~protesilaos/denote/%3C86k05gsqsg.fsf%40nobiot.com%3E>.
+
++ The ~denote-file-prompt~ function now reads an optional
+ =INITIAL-TEXT= argument.  This is a string that prepopulates the
+  minibuffer.  It is useful for custom commands the user may have
+  where, for example, there is a need to automatically filter to
+  entries matching =_journal=.  Thanks to Alan Schmitt for suggesting
+  the idea: <https://lists.sr.ht/~protesilaos/denote/%3C87pmf676n1.fsf@m4x.org%3E>.
+
++ The ~denote-rename-file-using-front-matter~ accepts an optional
+ =AUTO-CONFIRM= argument.  It can either be passed interactively or
+  via Lisp.  The doc string (or the manual) explains the details.
+  Thanks to Elias Storms for the initial patch:
+  <https://lists.sr.ht/~protesilaos/denote/%3Cm2a667aeku.fsf%40gmail.com%3E>.
+
++ The ~denote-prompt-for-date-return-id~ function uses the familiar
+ ~denote-date-prompt~ and returns the appropriate identifier.  It is
+  used internally by some of our function, but we also provide it for
+  anyone who wants to write their own custom code.
+
++ The ~denote-retrieve-or-create-file-identifier~ function reads and
+  option =DATE= argument to its mandatory =FILE= argument.  If =FILE=
+  does not have an identifier and optional =DATE= is non-nil, the
+  function invokes the ~denote-prompt-for-date-return-id~, as
+  mentioned above.
+
++ The ~denote-rename-file~ command accepts an optional =DATE=
+  argument.  It functionally does what is described right above, with
+  the exception that this is for an interactive function (a
+  "command").  Read the detailed doc string or the manual for
+  everything that pertains to this powerful command.
+
+  Thanks to Florian for suggesting the idea on the mailing list:
+  <https://lists.sr.ht/~protesilaos/denote/%3C166521684647.7.5483179875879361874.67576870%40aboulafia.org%3E>.
+
++ The ~denote-directory-text-only-files~ function filters the
+ ~denote-directory-files~ to only return a list of text files.  This
+  leaves out, say, mp3 files.  The function is used internally, though
+  it may also prove useful in custom user code.
+  
+** Miscellaneous refinements
+:PROPERTIES:
+:CUSTOM_ID: h:0531047f-ef15-412e-b265-886c55526d57
+:END:
+
++ Implemented a ~revert-buffer-function~ for the backlinks' buffer,
+  which is produced by the command ~denote-link-backlinks~.  This
+  revert function is what the =g= key invokes with the default key
+  bindings (the command is ~revert-buffer~).  It produces the buffer
+  anew, updating the list of backlinks accordingly.
+
++ Documented how to speed up the creation of the backlinks' buffer.
+  As this depends on the built-in =xref= library, the change is done
+  by specifying the value of the user option ~xref-search-program~ in
+  Emacs 28 or higher.  For example:
+
+  #+begin_src emacs-lisp
+  (setq xref-search-program 'ripgrep)
+  #+end_src
+
+  For something more elaborate:
+
+  #+begin_src emacs-lisp
+  ;; Prefer ripgrep, then ugrep, and fall back to regular grep.
+  (setq xref-search-program
+        (cond
+         ((or (executable-find "ripgrep")
+              (executable-find "rg"))
+          'ripgrep)
+         ((executable-find "ugrep")
+          'ugrep)
+         (t
+          'grep)))
+  #+end_src
+
++ Removed some minor duplication of effort in how the buttonisation of
+  links is done (what makes them clickable).
+
++ Made refinements to the definition of functions such as
+ ~denote-link-add-links~.  There should be no noticeable change for
+  users, though this shows we care about code quality.
+
++ With Eshel Yaron, we tried to remove the empty indices for functions
+  and variables from the HTML version of the manual.  These indices
+  are useful in the Info version, which can be accessed directly from
+  Emacs when the =denote= package is installed (for example, evaluate
+ =(info "(denote) Top")=), but they do not work with HTML.  Alas,
+  what we tried to do did not work.  Maybe Org has a way to control
+  what is exported where.  We shall see.  At any rate, thanks to Eshel
+  for the effort: <https://lists.sr.ht/~protesilaos/denote/patches/36028>.
+
++ All code that integrates the =denote:= custom hyperlink type with
+  Org's link facility is now assigned =autoload= cookies.  These are
+  done to ensure that =denote= is loaded and is available in cases
+  where Org needs to access a =denote:= link at some early stage
+  (e.g. at startup before using Denote).  Thanks to Sven Seebeck for
+  reporting the problem: <https://lists.sr.ht/~protesilaos/denote/%3C87r0zovwix.fsf%40svenseebeck.me%3E>.
+  Although Sven could not reproduce a bug reliably, I believe this
+  prevents such an eventuality.
+
++ Expanded or otherwise updated the manual to account for all of the
+  above, where appropriate.
+
 * Version 1.0.0 on 2022-09-30
 :PROPERTIES:
 :CUSTOM_ID: h:053975d7-3fe2-49e5-96a0-336483e5861c

README.org

@@ -4,9 +4,9 @@
 #+language:              en
 #+options:               ':t toc:nil author:t email:t num:t
 #+startup:               content
-#+macro:                 stable-version 1.0.0
+#+macro:                 stable-version 1.1.0
-#+macro:                 release-date 2022-09-30
+#+macro:                 release-date 2022-10-20
-#+macro:                 development-version 1.1.0-dev
+#+macro:                 development-version 1.2.0-dev
 #+export_file_name:      denote.texi
 #+texinfo_filename:      denote.info
 #+texinfo_dir_category:  Emacs misc features
@@ -467,8 +467,6 @@ that is common in interactions with Org mode, can set the user option
 :CUSTOM_ID: h:ad4dde4a-8e88-470a-97ae-e7b9d4b41fb4
 :END:
 
-[ Part of {{{development-version}}}. ]
-
 #+findex: denote-keywords-add
 #+findex: denote-keywords-remove
 The commands ~denote-keywords-add~ and ~denote-keywords-remove~
@@ -625,9 +623,6 @@ all the mechanisms to facilitate the task of renaming them.
 :CUSTOM_ID: h:7cc9e000-806a-48da-945c-711bbc7426b0
 :END:
 
-[ The ~denote-rename-file~ accepts an optional =DATE= argument as part
-  of {{{development-version}}}. ]
-
 #+findex: denote-rename-file
 The ~denote-rename-file~ command renames a file and updates existing
 front matter if appropriate.
@@ -771,7 +766,6 @@ new names, just so the user is certain about the change.
 
 If called interactively with a prefix argument =C-u= or from Lisp with
 a non-nil =AUTO-CONFIRM= argument, this "yes or no" prompt is skipped.
-[ This is part of {{{development-version}}}. ]
 
 The identifier of the file, if any, is never modified even if it is
 edited in the front matter: Denote considers the file name to be the
@@ -1161,8 +1155,7 @@ The description of the link is taken from the target file's front
 matter or, if that is not available, from the file name.  If the
 region is active, its text is used as the link's description instead.
 If the active region has no text, the inserted link used just the
-identifier, as with the =C-u= prefix mentioned above [the ability of
+identifier, as with the =C-u= prefix mentioned above.
-~denote-link~ to use the region is part of {{{development-version}}}].
 
 Inserted links are automatically buttonized and remain active for as
 long as the buffer is available.  In Org this is handled by the major
@@ -1402,9 +1395,9 @@ certain executables to the relevant environment variable.
 
 [[#h:42f6b07e-5956-469a-8294-17f9cf62eb2b][Why do I get "Search failed with status 1" when I search for backlinks?]]
 
-Backlinks can also be visited by using minibuffer completion.  The
+Backlinks to the current file can also be visited by using the
-command is ~denote-link-find-backlink~, which is part of
+minibuffer completion interface with the ~denote-link-find-backlink~
-{{{development-version}}} ([[#h:1bc2adad-dca3-4878-b9f0-b105d5dec6f4][Visiting linked files via the minibuffer]]).
+command ([[#h:1bc2adad-dca3-4878-b9f0-b105d5dec6f4][Visiting linked files via the minibuffer]]).
 
 ** Writing metanotes
 :PROPERTIES:
@@ -1465,8 +1458,6 @@ To visit backlinks to the current note via the minibuffer, use
 ~denote-link-find-backlink~.  This is an alternative to placing
 backlinks in a dedicated buffer ([[#h:c73f1f68-e214-49d5-b369-e694f6a5d708][The backlinks' buffer]]).
 
-[ The ~denote-link-find-backlink~ is part of {{{development-version}}}. ]
-
 ** Miscellaneous information about links
 :PROPERTIES:
 :CUSTOM_ID: h:dd8f2231-8d77-49b9-acc4-af525c68b271
@@ -2420,8 +2411,7 @@ might change them without further notice.
 #+findex: denote-directory-text-only-files
 + Function ~denote-directory-text-only-files~ :: Return list of text
   files in variable ~denote-directory~.  Filter
- ~denote-directory-files~ using ~denote-file-is-note-p~. [ This is
+ ~denote-directory-files~ using ~denote-file-is-note-p~.
-  part of {{{development-version}}}. ]
 
 #+findex: denote-directory-subdirectories
 + Function ~denote-directory-subdirectories~ :: Return list of
@@ -2498,9 +2488,6 @@ might change them without further notice.
   one, refer to the ~denote-retrieve-or-create-file-identifier~
   function.
 
-[ The ~denote-retrieve-or-create-file-identifier~ accepts an optional
- =DATE= argument as part of {{{development-version}}}. ]
-
 #+findex: denote-retrieve-or-create-file-identifier
 + Function ~denote-retrieve-or-create-file-identifier~ :: Return
  =FILE= identifier, generating one if appropriate.  The conditions
@@ -2544,8 +2531,7 @@ might change them without further notice.
 #+findex: denote-file-prompt
 + Function ~denote-file-prompt~ :: Prompt for file with identifier in
   variable ~denote-directory~.  With optional =INITIAL-TEXT=, use it
-  to prepopulate the minibuffer.  [ The optional =INITIAL-TEXT= is
+  to prepopulate the minibuffer.
-  part of {{{development-version}}}. ]
 
 #+findex: denote-keywords-prompt
 + Function ~denote-keywords-prompt~ :: Prompt for one or more
@@ -2570,9 +2556,6 @@ might change them without further notice.
  ~denote-date-prompt-use-org-read-date~ is non-nil.  It requires Org
   ([[#h:e7ef08d6-af1b-4ab3-bb00-494a653e6d63][The denote-date-prompt-use-org-read-date option]]).
 
-[ The ~denote-prompt-for-date-return-id~ is part of
-  {{{development-version}}}. ]
-
 #+findex: denote-prompt-for-date-return-id
 + Function ~denote-prompt-for-date-return-id~ :: Use
  ~denote-date-prompt~ and return it as ~denote-id-format~.

denote.el

@@ -6,7 +6,7 @@
 ;; Maintainer: Denote Development <~protesilaos/denote@lists.sr.ht>
 ;; URL: https://git.sr.ht/~protesilaos/denote
 ;; Mailing-List: https://lists.sr.ht/~protesilaos/denote
-;; Version: 1.0.0
+;; Version: 1.1.0
 ;; Package-Requires: ((emacs "27.2"))
 
 ;; This file is NOT part of GNU Emacs.