~protesilaos/denote

4 2

Intended use-cases for renaming denote-files

Details
Message ID
<87k081l6vw.fsf@silverstone.mail-host-address-is-not-set>
DKIM signature
missing
Download raw message
Hello Prot

I've got a use-case question regarding the 2 available functions for
renaming files, namely:

- denote-dired-rename-file
- denote-dired-rename-file-and-add-front-matter

Let's say I have a file to rename, containing the following front-matter:

#+title:      Life - a definition
#+date:       [2022-06-30 Do]
#+filetags:   philosphy

(Note: #+identifier: is missing)

then neither of the two functions 'cleans-up' the front-matter.
In either case, I have to manually 'fix' it.

Wouldn't it be nice, if there was only 1 'rename' command,
which in all cases completes the front-matter?

e.g. always completes all 4 four properties, i.e.:
- adds the missing ones
- updates the existing ones

Perhaps, I do not understand the intended use-cases of the current
solution?

Thank you for your thoughts - and for Denote!
HP.
Details
Message ID
<87bktd2wr9.fsf@protesilaos.com>
In-Reply-To
<87k081l6vw.fsf@silverstone.mail-host-address-is-not-set> (view parent)
DKIM signature
pass
Download raw message
> From: Hanspeter Gisler <hpgisleropen@bluewin.ch>
> Date: Mon, 25 Jul 2022 14:21:55 +0200
>
> Hello Prot

Hello Hanspeter,

> I've got a use-case question regarding the 2 available functions for
> renaming files, namely:
>
> - denote-dired-rename-file
> - denote-dired-rename-file-and-add-front-matter
>
> Let's say I have a file to rename, containing the following front-matter:
>
> #+title:      Life - a definition
> #+date:       [2022-06-30 Do]
> #+filetags:   philosphy
>
> (Note: #+identifier: is missing)
>
> then neither of the two functions 'cleans-up' the front-matter.
> In either case, I have to manually 'fix' it.

You are right.  That's an inconvenience.

> Wouldn't it be nice, if there was only 1 'rename' command,
> which in all cases completes the front-matter?
>
> e.g. always completes all 4 four properties, i.e.:
> - adds the missing ones
> - updates the existing ones

If we can unify everything in a single command that always does the
right thing, then yes I am happy to do so.

What we need to consider is that users can add arbitrary front matter
either manually or by tweaking the relevant variable such as
'denote-org-front-matter' (I can elaborate on this, if you want, though
check the doc string to get an idea).  These tweaks may change over
time, so notes will not be uniform.  Some may have one extra entry,
others three, in some the order may be different, and so on.

For example, an Org note may include a #+macro: like those found in the
README.org of Denote or even something more elaborate.  If our function
were to remove that, it would break the desired functionality in the
file.

We thus need to account for all possible permutations and guard against
overwrites of potentially valuable information.  The two approaches we
have now are basically what we currently have for guarding against that
possible outcome.

> Perhaps, I do not understand the intended use-cases of the current
> solution?

Maybe the above answers your question.  Please let me know if something
is unclear and I will explain it further.

My general approach to everything: if we can do it, without prejudice to
the principles of the project, then I am happy to see it happen.

> Thank you for your thoughts - and for Denote!

You are welcome!

All the best,
Prot


-- 
Protesilaos Stavrou
https://protesilaos.com
Details
Message ID
<a8c29537e2c57009dea225e352d38af7@prevos.net>
In-Reply-To
<87bktd2wr9.fsf@protesilaos.com> (view parent)
DKIM signature
pass
Download raw message
Hi Hanspeter and Prot,

Lets look at this from a higher level.

A file is a Denote file by virtue of its filename and the associated 
front matter. The collection of file names and associated title front 
matter lines constitute the collection of denotes. However, the link 
between the file name and its font matter is fragile. A user can 
manually change either of these, breaking the symmetry. As I understand 
it, only the title line in the front matter is used by any denote 
function as the rest can be extracted from the file name.

As such, renaming Denote can have three use cases:
1. Change the title or tags for a valid Denote file
2. Correct the symmetry between file name and front matter
3. Convert a non-Denote file to a Denote file by renaming it to the 
Denote convention, and adding associated front matter items for 
registered file types (txt,md, org).

Renaming use cases can either occur on a single file (1) or on multiple 
files (2, 3).

Question: Should Denote include a 'find-file' or dired hook that 
synchronises file names and associated front matter for all files in the 
'denote-directory'? That would cover use case 2 and 3.



Regards

P:)

---
Dr Peter Prevos
  ---------------
peterprevos.com

On 25-07-2022 22:38, Protesilaos Stavrou wrote:
>> From: Hanspeter Gisler <hpgisleropen@bluewin.ch>
>> Date: Mon, 25 Jul 2022 14:21:55 +0200
>> 
>> Hello Prot
> 
> Hello Hanspeter,
> 
>> I've got a use-case question regarding the 2 available functions for
>> renaming files, namely:
>> 
>> - denote-dired-rename-file
>> - denote-dired-rename-file-and-add-front-matter
>> 
>> Let's say I have a file to rename, containing the following 
>> front-matter:
>> 
>> #+title:      Life - a definition
>> #+date:       [2022-06-30 Do]
>> #+filetags:   philosphy
>> 
>> (Note: #+identifier: is missing)
>> 
>> then neither of the two functions 'cleans-up' the front-matter.
>> In either case, I have to manually 'fix' it.
> 
> You are right.  That's an inconvenience.
> 
>> Wouldn't it be nice, if there was only 1 'rename' command,
>> which in all cases completes the front-matter?
>> 
>> e.g. always completes all 4 four properties, i.e.:
>> - adds the missing ones
>> - updates the existing ones
> 
> If we can unify everything in a single command that always does the
> right thing, then yes I am happy to do so.
> 
> What we need to consider is that users can add arbitrary front matter
> either manually or by tweaking the relevant variable such as
> 'denote-org-front-matter' (I can elaborate on this, if you want, though
> check the doc string to get an idea).  These tweaks may change over
> time, so notes will not be uniform.  Some may have one extra entry,
> others three, in some the order may be different, and so on.
> 
> For example, an Org note may include a #+macro: like those found in the
> README.org of Denote or even something more elaborate.  If our function
> were to remove that, it would break the desired functionality in the
> file.
> 
> We thus need to account for all possible permutations and guard against
> overwrites of potentially valuable information.  The two approaches we
> have now are basically what we currently have for guarding against that
> possible outcome.
> 
>> Perhaps, I do not understand the intended use-cases of the current
>> solution?
> 
> Maybe the above answers your question.  Please let me know if something
> is unclear and I will explain it further.
> 
> My general approach to everything: if we can do it, without prejudice 
> to
> the principles of the project, then I am happy to see it happen.
> 
>> Thank you for your thoughts - and for Denote!
> 
> You are welcome!
> 
> All the best,
> Prot
Details
Message ID
<874jz4a6cp.fsf@protesilaos.com>
In-Reply-To
<a8c29537e2c57009dea225e352d38af7@prevos.net> (view parent)
DKIM signature
pass
Download raw message
> From: Peter Prevos <peter@prevos.net>
> Date: Tue, 26 Jul 2022 06:36:08 +1000
>
> Hi Hanspeter and Prot,

Hello Peter and Hanspeter,

> Lets look at this from a higher level.
>
> A file is a Denote file by virtue of its filename and the associated 
> front matter.

Our definition at the code level is limited to the file name.  The
heuristic:

    (defun denote--only-note-p (file)
      "Make sure FILE is an actual Denote note."
      (let ((file-name (file-name-nondirectory file)))
        (and (not (file-directory-p file))
             (file-regular-p file)
             (string-match-p (concat "\\`" denote--id-regexp
                                     ".*" denote--extension-regexp "\\'")
                             file-name)
             (not (string-match-p "[#~]\\'" file)))))

We basically consider a "note" any regular file that starts with our
identifier and ends in {md,org,txt}.

This is for practical purposes due to the possibility of writing file
names that exclude the TITLE and/or KEYWORDS fields.  For example:

* One is writing a daily diary in the "diary" subdirectory.  It does not
  really need a title and keywords in the name as it is a stream of
  consciousness with no given structure.

* One is writing notes about some specific event in a subdirectory.
  They need the title, but not the keywords.

Personally, I always use the full name and do not rely on subdirectories
to infer meaning.  The full name makes the files more portable,
readable, and easier to filter.  Subdirectories are good for transient
or longer-term storage.

Though the implementation is flexible for those who need it in some
do-it-yourself code they maintain (typically a thin wrapper around the
'denote' command which complements the set of commands for note-creation
we already provide).

> The collection of file names and associated title front matter lines
> constitute the collection of denotes. However, the link between the
> file name and its font matter is fragile. A user can manually change
> either of these, breaking the symmetry. As I understand it, only the
> title line in the front matter is used by any denote function as the
> rest can be extracted from the file name.

For our purposes, the front matter is not strictly necessary.  The core
functionality of links/backlinks relies only on the file name,
specifically the identifier.

We only use the front matter for the user's convenience.  It is easier
to read and can be useful for other purposes such as an Org export.

You can check how front matter is not critical at the code level by
running a git grep for "denote-retrieve--value".  These are functions
that actually read the front matter.  They are only used for various
non-critical tasks.  Again: good to have, but not strictly necessary.

> As such, renaming Denote can have three use cases:
> 1. Change the title or tags for a valid Denote file
> 2. Correct the symmetry between file name and front matter
> 3. Convert a non-Denote file to a Denote file by renaming it to the 
> Denote convention, and adding associated front matter items for 
> registered file types (txt,md, org).
>
> Renaming use cases can either occur on a single file (1) or on multiple 
> files (2, 3).
>
> Question: Should Denote include a 'find-file' or dired hook that 
> synchronises file names and associated front matter for all files in the 
> 'denote-directory'? That would cover use case 2 and 3.

We would need to consider the specifics of such a hook.  What are we
trying to achieve and what are the associated downsides.  It would also
need to be an opt-in feature or generally be sufficiently flexible, as
the user may have a workflow where their notes do not change file names
and front matter.

In principle, I am not against such a hook.  I just haven't thought
about its modalities.  Perhaps you can elaborate?  Once we have a
concrete idea of the problem, we will figure out a solution.

As I already implied, there is no need for symmetry between the file
name and its front matter for Denote to work.  It is good for the user's
convenience, which we don't want to downplay (I like my front matter),
though still not strictly necessary.

All the best,
Prot

-- 
Protesilaos Stavrou
https://protesilaos.com
Details
Message ID
<ecd9f72563bbe41db77291a050b3de38@prevos.net>
In-Reply-To
<874jz4a6cp.fsf@protesilaos.com> (view parent)
DKIM signature
pass
Download raw message
Hi Prot and Hanspeter,

I agree there is no need from a code perspective to have symmetry 
between file name and the front matter. The power of Denote is its 
reliance on a file naming convention.

However, when renaming a file, the Denote does seem to retrieve data 
from the front matter. The 'denote-retrieve--*-front-matter-key-regexp' 
variables seem to look at the file content - assuming I read the source 
correctly.

Synchronising front matter and file name would be good data integrity 
practice and provide some convenience. It means that you only have to 
change the front matter and run the synchronise function.

The file name helps with heuristics, the front matter improves 
readability. For Org mode files it also means that you can use its 
functionality ('org-element-parse-buffer') to extract metadata about the 
file.

I crafted a function to create a file name from Org mode front matter:

   (defun denote-org-buffer-file-name ()
     "Generate filename Org mode keywords."
     (let* ((filename buffer-file-name)
            (keywords (org-element-map (org-element-parse-buffer) 
'keyword
                        (lambda (keyword)
                          (cons (org-element-property :key keyword)
                                (org-element-property :value keyword)))))
            (identifier (denote-retrieve--filename-identifier 
buffer-file-name))
            (filetags (cdr (assoc "FILETAGS" keywords))))
       (concat identifier
               "--" (denote--sluggify (cdr (assoc "TITLE" keywords)))
               "__" (denote--sluggify filetags) ".org")))


I can't get the tags right. Note that the canonical format for Org mode 
filetags is ":tag1:tag2" instead of "tag1  tag2". It would be nice if 
Denote can also follow this syntax. The Org function (org-split-string) 
takes care of tags.

Markdown mode has similar functionality to extract YAML or TOML 
metadata.

Synchronising front matter and file name would function as a text-only 
replacement for a database and allow for extensibility with Org and 
Markdown modes. One could, for example add '#+subtitle:' or #+status:' 
etc etc. There is only so much info you can shove into a file name ...



Regards

P:)


---
Dr Peter Prevos
  ---------------
peterprevos.com

On 26-07-2022 13:41, Protesilaos Stavrou wrote:
>> From: Peter Prevos <peter@prevos.net>
>> Date: Tue, 26 Jul 2022 06:36:08 +1000
>> 
>> Hi Hanspeter and Prot,
> 
> Hello Peter and Hanspeter,
> 
>> Lets look at this from a higher level.
>> 
>> A file is a Denote file by virtue of its filename and the associated
>> front matter.
> 
> Our definition at the code level is limited to the file name.  The
> heuristic:
> 
>     (defun denote--only-note-p (file)
>       "Make sure FILE is an actual Denote note."
>       (let ((file-name (file-name-nondirectory file)))
>         (and (not (file-directory-p file))
>              (file-regular-p file)
>              (string-match-p (concat "\\`" denote--id-regexp
>                                      ".*" denote--extension-regexp 
> "\\'")
>                              file-name)
>              (not (string-match-p "[#~]\\'" file)))))
> 
> We basically consider a "note" any regular file that starts with our
> identifier and ends in {md,org,txt}.
> 
> This is for practical purposes due to the possibility of writing file
> names that exclude the TITLE and/or KEYWORDS fields.  For example:
> 
> * One is writing a daily diary in the "diary" subdirectory.  It does 
> not
>   really need a title and keywords in the name as it is a stream of
>   consciousness with no given structure.
> 
> * One is writing notes about some specific event in a subdirectory.
>   They need the title, but not the keywords.
> 
> Personally, I always use the full name and do not rely on 
> subdirectories
> to infer meaning.  The full name makes the files more portable,
> readable, and easier to filter.  Subdirectories are good for transient
> or longer-term storage.
> 
> Though the implementation is flexible for those who need it in some
> do-it-yourself code they maintain (typically a thin wrapper around the
> 'denote' command which complements the set of commands for 
> note-creation
> we already provide).
> 
>> The collection of file names and associated title front matter lines
>> constitute the collection of denotes. However, the link between the
>> file name and its font matter is fragile. A user can manually change
>> either of these, breaking the symmetry. As I understand it, only the
>> title line in the front matter is used by any denote function as the
>> rest can be extracted from the file name.
> 
> For our purposes, the front matter is not strictly necessary.  The core
> functionality of links/backlinks relies only on the file name,
> specifically the identifier.
> 
> We only use the front matter for the user's convenience.  It is easier
> to read and can be useful for other purposes such as an Org export.
> 
> You can check how front matter is not critical at the code level by
> running a git grep for "denote-retrieve--value".  These are functions
> that actually read the front matter.  They are only used for various
> non-critical tasks.  Again: good to have, but not strictly necessary.
> 
>> As such, renaming Denote can have three use cases:
>> 1. Change the title or tags for a valid Denote file
>> 2. Correct the symmetry between file name and front matter
>> 3. Convert a non-Denote file to a Denote file by renaming it to the
>> Denote convention, and adding associated front matter items for
>> registered file types (txt,md, org).
>> 
>> Renaming use cases can either occur on a single file (1) or on 
>> multiple
>> files (2, 3).
>> 
>> Question: Should Denote include a 'find-file' or dired hook that
>> synchronises file names and associated front matter for all files in 
>> the
>> 'denote-directory'? That would cover use case 2 and 3.
> 
> We would need to consider the specifics of such a hook.  What are we
> trying to achieve and what are the associated downsides.  It would also
> need to be an opt-in feature or generally be sufficiently flexible, as
> the user may have a workflow where their notes do not change file names
> and front matter.
> 
> In principle, I am not against such a hook.  I just haven't thought
> about its modalities.  Perhaps you can elaborate?  Once we have a
> concrete idea of the problem, we will figure out a solution.
> 
> As I already implied, there is no need for symmetry between the file
> name and its front matter for Denote to work.  It is good for the 
> user's
> convenience, which we don't want to downplay (I like my front matter),
> though still not strictly necessary.
> 
> All the best,
> Prot
Reply to thread Export thread (mbox)