emacs/protesilaos.denote
1
0
Fork 0
mirror of https://github.com/protesilaos/denote.git synced 2026-09-10 07:16:20 -04:00
Code Issues Actions Packages Projects Releases Wiki Activity

Update to version 1.1.0

Browse source
This commit is contained in:
Protesilaos Stavrou 2022-10-20 13:40:01 +03:00
parent 7b39592605
commit d9a1b0c0b8
No known key found for this signature in database
GPG key ID: 99BD6459CD5CA3EA
3 changed files with 213 additions and 27 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

203
CHANGELOG.org
View file

@ -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

35
README.org
View file

@ -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: release-date 2022-09-30
#+macro: development-version 1.1.0-dev
#+macro: stable-version 1.1.0
#+macro: release-date 2022-10-20
#+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
~denote-link~ to use the region is part of {{{development-version}}}].
identifier, as with the =C-u= prefix mentioned above.
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
command is ~denote-link-find-backlink~, which is part of
{{{development-version}}} ([[#h:1bc2adad-dca3-4878-b9f0-b105d5dec6f4][Visiting linked files via the minibuffer]]).
Backlinks to the current file can also be visited by using the
minibuffer completion interface with the ~denote-link-find-backlink~
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
part of {{{development-version}}}. ]
~denote-directory-files~ using ~denote-file-is-note-p~.
#+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
part of {{{development-version}}}. ]
to prepopulate the minibuffer.
#+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~.

2
denote.el
View file

@ -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.