~protesilaos/denote

356b1b8e76f27a5d8f3fe68dee7839f1f467ef31 — Protesilaos Stavrou 3 months ago 9e3cf08
Rewrite the documentation of 'denote-rename-file' to be up-to-date
2 files changed, 62 insertions(+), 35 deletions(-)

M README.org
M denote.el
M README.org => README.org +34 -19
@@ 1047,6 1047,11 @@ line or switching between then with commands like ~switch-to-buffer~.
:CUSTOM_ID: h:7cc9e000-806a-48da-945c-711bbc7426b0
:END:

[ The ~denote-rename-file~ command is made more intuitive as part of
  {{{development-version}}}. All its prompts now include a hint that
  leaving them empty will ignore the given field if it does not exist
  or remove it if it does exist. ]

#+findex: denote-rename-file
The ~denote-rename-file~ command renames a file and updates existing
front matter if appropriate. It is possible to do the same with


@@ 1057,7 1062,7 @@ minibuffer completion for one. When called from Lisp, =FILE= is a
filesystem path represented as a string.

If =FILE= has a Denote-compliant identifier, retain it while updating
the TITLE and =KEYWORDS= fields of the file name.
the =TITLE=, =KEYWORDS=, and =SIGNATURE= components of the file name.

Else create an identifier based on the following conditions:



@@ 1074,28 1079,32 @@ Else create an identifier based on the following conditions:
   variable ~denote-directory~, increment it such that it becomes
   unique.

Use =TITLE= to construct the new name of =FILE=. In interactive use,
Add =TITLE= to =FILE=. In interactive use, prompt for user input and
retrieve the default =TITLE= value from a line starting with a title
field in the file's contents, depending on the given file type ([[#h:13218826-56a5-482a-9b91-5b6de4f14261][Front matter]]).
Else, use the file name as a default value at the minibuffer prompt.
When called from Lisp, =TITLE= is a string.

Add =SIGNATURE= to the file, using an existing one as the default
value at the minibuffer prompt. When called from Lisp, =SIGNATURE= is
a string. If the =SIGNATURE= is empty or ~nil~, it is not included in
the new file name or removed from an existing one. [ Made it
intuitive/consistent as part of {{{development-version}}}. ]
If =TITLE= is nil or an empty string, do not add it to a newly renamed
file or remove it from an existing file. [ This feature is part of
{{{development-version}}}. ]

As a final step after the =FILE=, =TITLE=, =KEYWORDS=, and =SIGNATURE=
are collected, ask for confirmation, showing the difference between
old and new file names. For example:
Add =SIGNATURE= to =FILE=. In interactive use, prompt for =SIGNATURE=,
using an existing one as the default value at the minibuffer prompt.
When called from Lisp, =SIGNATURE= is a string.

#+begin_example
Rename sample.txt to 20220612T052900--my-sample-title__testing.txt? (y or n)
#+end_example
If =SIGNATURE= is nil or an empty string, do not add it to a newly
renamed file or remove it from an existing file. [ Made consistent as
part of {{{development-version}}}. ]

Do not ask for confirmation if the ~denote-rename-no-confirm~ option
is set to a non-nil value ([[#h:a2ae9090-c49e-4b32-bcf5-eb8944241fd7][The ~denote-rename-no-confirm~ option]]).
Add =KEYWORDS= to =FILE=. In interactive use, prompt for =KEYWORDS=.
More than one keyword can be inserted when separated by the
`crm-sepator' (normally a comma). When called from Lisp, =KEYWORDS= is
a list of strings.

If =KEYWORDS= is nil or an empty string, do not add it to a newly
renamed file or remove it from an existing file. [ Part of
{{{development-version}}}. ]

Read the file type extension (like =.txt=) from the underlying file
and preserve it through the renaming process. Files that have no


@@ 1104,14 1113,21 @@ extension are left without one.
Renaming only occurs relative to the current directory. Files are not
moved between directories.

As a final step after the =FILE=, =TITLE=, =KEYWORDS=, and =SIGNATURE=
are collected, ask for confirmation, showing the difference between
old and new file names.

Do not ask for confirmation if the ~denote-rename-no-confirm~ option
is set to a non-nil value ([[#h:a2ae9090-c49e-4b32-bcf5-eb8944241fd7][The ~denote-rename-no-confirm~ option]]).

If the =FILE= has Denote-style front matter for the =TITLE= and
=KEYWORDS=, ask to rewrite their values in order to reflect the new
input (this step always requires confirmation and the underlying
buffer is not saved, so consider invoking ~diff-buffer-with-file~ to
double-check the effect). The rewrite of the =FILE= and =KEYWORDS= in
double-check the effect). The rewrite of the =TITLE= and =KEYWORDS= in
the front matter should not affect the rest of the front matter.

If the file doesn't have front matter but is among the supported file
If the file does not have front matter but is among the supported file
types (per ~denote-file-type~), add front matter at the top of it and
leave the buffer unsaved for further inspection.



@@ 1126,8 1142,7 @@ This command is intended to (i) rename existing Denote notes while
updating their title and keywords in the front matter, (ii) convert
existing supported file types to Denote notes, and (ii) rename
non-note files (e.g. PDF) that can benefit from Denote's file-naming
scheme. The latter is a convenience we provide, since we already have
all the requisite mechanisms in place.
scheme.

*** The ~denote-rename-no-confirm~ option
:PROPERTIES:

M denote.el => denote.el +28 -16
@@ 2402,7 2402,8 @@ with minibuffer completion for one.  When called from Lisp, FILE
is a filesystem path represented as a string.

If FILE has a Denote-compliant identifier, retain it while
updating the TITLE and KEYWORDS fields of the file name.
updating the TITLE, KEYWORDS, and SIGNATURE components of the
file name.

Else create an identifier based on the following conditions:



@@ 2420,23 2421,30 @@ Else create an identifier based on the following conditions:
   the variable `denote-directory', increment it such that it
   becomes unique.

Use TITLE to construct the new name of FILE.  In interactive use,
Add TITLE to FILE.  In interactive use, prompt for user input and
retrieve the default TITLE value from a line starting with a
title field in the file's contents, depending on the given file
type (e.g. #+title for Org).  Else, use the file name as a
default value at the minibuffer prompt.  When called from Lisp,
TITLE is a string.

Add SIGNATURE to the file, using an existing one as the default
value at the minibuffer prompt.  When called from Lisp, SIGNATURE
is a string.  If the SIGNATURE is empty or nil, it is not
included in the new file name or removed from an existing one.
If TITLE is nil or an empty string, do not add it to a newly
renamed file or remove it from an existing file.

As a final step after the FILE, TITLE, KEYWORDS, and SIGNATURE
are collected, ask for confirmation, showing the difference
between old and new file names.  Do not ask for confirmation if
the user option `denote-rename-no-confirm' is set to a non-nil
value.
Add SIGNATURE to FILE.  In interactive use, prompt for SIGNATURE,
using an existing one as the default value at the minibuffer
prompt.  When called from Lisp, SIGNATURE is a string.

If SIGNATURE is nil or an empty string, do not add it to a newly
renamed file or remove it from an existing file.

Add KEYWORDS to FILE.  In interactive use, prompt for KEYWORDS.
More than one keyword can be inserted when separated by the
`crm-sepator' (normally a comma).  When called from Lisp,
KEYWORDS is a list of strings.

If KEYWORDS is nil or an empty string, do not add it to a newly
renamed file or remove it from an existing file.

Read the file type extension (like .txt) from the underlying file
and preserve it through the renaming process.  Files that have no


@@ 2445,15 2453,21 @@ extension are left without one.
Renaming only occurs relative to the current directory.  Files
are not moved between directories.

As a final step after the FILE, TITLE, KEYWORDS, and SIGNATURE
are collected, ask for confirmation, showing the difference
between old and new file names.  Do not ask for confirmation if
the user option `denote-rename-no-confirm' is set to a non-nil
value.

If the FILE has Denote-style front matter for the TITLE and
KEYWORDS, ask to rewrite their values in order to reflect the new
input (this step always requires confirmation and the underlying
buffer is not saved, so consider invoking `diff-buffer-with-file'
to double-check the effect).  The rewrite of the FILE and
to double-check the effect).  The rewrite of the TITLE and
KEYWORDS in the front matter should not affect the rest of the
front matter.

If the file doesn't have front matter but is among the supported
If the file does not have front matter but is among the supported
file types (per `denote-file-type'), add front matter at the top
of it and leave the buffer unsaved for further inspection.



@@ 2468,9 2482,7 @@ This command is intended to (i) rename existing Denote notes
while updating their title and keywords in the front matter, (ii)
convert existing supported file types to Denote notes, and (ii)
rename non-note files (e.g. PDF) that can benefit from Denote's
file-naming scheme.  The latter is a convenience we provide,
since we already have all the requisite mechanisms in
place."
file-naming scheme."
  (interactive
   (let* ((file (denote--rename-dired-file-or-prompt))
          (file-type (denote-filetype-heuristics file))