> Hello Hanspeter, Protesilaos
> 
> I suggest we keep the concern of converting non-Denote notes to Denote
> separate from that of modifying an existing note. Quoting myself from
> issue #48 on Github:
> 
> > Since `denote-dired-rename-file` already does a lot, I think I would
> create a distinct function for conversion purpose. The purpose of a
> function like `denote-dired-rename-file` is really just to change
> the title and add/remove keywords. Overloading it with code that
> does file conversion might make it hard to maintain and its
> docstring would have to explain its dual purpose, which could be
> confusing to users.
> 
> I have noticed this in a previous message:
> 
> We also have a question of ergonomics. Two commands are overkill.
> They can confuse the user and are harder to explain. Can we
> consolidate all three of the "rewrite", "complement", "add"
> operations? If yes, then this is the right thing to do. Too many
> options end up being to our detriment.
> 
> At one point, we had two distinct functions `denote-dired-rename-file`
> and `denote-dired-convert-file-to-denote`, but the latter got renamed
> to `denote-dired-rename-file-and-add-front-matter` (by me in fact). I
> think we are slowly going back to one big function with two distinct
> purposes.
> 
> I propose the following functions to handle the task of modifying
> existing Denote notes:
> 
> denote-rename-file (current note, using prompts)
> denote-rename-file-using-front-matter (curr note, using front matter)
> denote-rename-marked-files (using prompts)
> denote-rename-marked-files-using-front-matter (using front matter)
> denote-rename-files-dwim (Calls the previous functions depending
> on the context (marked files or current file). I prefer the
> "front matter" route, but we can make it use the "prompts"
> route.)
> 
> For the task of converting a non-Denote file to Denote, I think we
> could have:
> 
> denote-convert-file-to-denote
> denote-convert-marked-files-to-denote
> 
> A typical user would probably just use `denote-rename-files-dwim` and
> `denote-convert-file-to-denote` (for the two distinct use-cases
> specified above), but the other commands would be available for more
> control. All commands would be implemented using common building
> blocks, so none of them would be that big.
> 
> ----
> 
> In the original message of this thread, Hanspeter asked:
> 
> > Perhaps, I do not understand the intended use-cases of the current
> > solution?
> 
> I hope this message is helping you understand the history behind
> the current commands.
> 
> In the original message, Hanspeter also asked how a given file with
> possibly missing information (such as a missing #'identifier) in the
> front matter can be fixed. My solution to this would be that we will
> have to be smarter when implementing `denote-convert-file-to-denote`
> and not simply "add a front matter unconditionally", but instead use
> the existing data, when available.

Hello Jean-Philippe

Thank you very much for your detailed explanation.

Regarding the importance of not overloading the functionality and thus
the complexity of individual functions in order to keep them maintainable:

I totally agree with you!

However, I think it is paramount to keep two things clearly separate in
our minds:

a) the provisioning of meaningful use-cases by Denote to the user
b) the implementation of Denotes' code, realizing said use-cases (a)

By the way:
I believe, for both of them we should persue minimum complexity. 

To hopefully make myself clearer:

I believe, the number of user-facing functions should be as small as
possible and thus do as much automagic [sic] user-intention guessing as
possible - usually by help of the user's current context.

However, by this I do *not* mean, that the actual underlying/inner/private functions
are huge, hard to maintain, monolitic code blocks, but more in the
sense - as you described above (and in earlier posts):
meaningful small functions, which can be assembled to various 'dwim'
user-facing-functions. 

(I know, I simplify matters greatly here for myself, as I do not dare
to dive into the intricacies of the actual code implementation, but
rather want to stay at the high-level on the user-facing functionality.
Please forgive my for my simplifications)

Referring to your function examples above:

To make a simple example:
For me (as a user) it is not so clear what the difference is between, e.g.:

- denote-convert-file-to-denote
- denote-rename-file

Because - for example - if I call denote-rename-file on 'test.org'
then 'test.org' is also 'converted' to a valid denote named file,
e.g. '20220730T150629--test__tagt.org'
(albeit w/o frontmatter).


Summing up:

(IMHO)
- we should strive for as few but powerful user-facing functions
  as possible (based on well defined use cases) i.e. 'dwim'

- implement them with as many simple functional blocks
  (low level functions) as required.
  
Sorry for this lengthy treatise and perhaps sounding a little
academic & educational.. this is not my intention.
I just try to make my thinking in this matter clearer.

Best Regards and thank you very much for all your work on Denote!
It is very much appreciated.
Hanspeter

> From: Hanspeter Gisler <hpgisleropen@bluewin.ch>
> Date: Sat, 30 Jul 2022 15:39:32 +0200

Hello Hanspeter, Jean-Philippe!

> Thank you very much for your detailed explanation.
>
> Regarding the importance of not overloading the functionality and thus
> the complexity of individual functions in order to keep them maintainable:
>
> I totally agree with you!

I also agree on the importance of clean code.  Functions must be small
and composable, which is how our code generally is---and should remain
that way.

> However, I think it is paramount to keep two things clearly separate in
> our minds:
>
> a) the provisioning of meaningful use-cases by Denote to the user
> b) the implementation of Denotes' code, realizing said use-cases (a)
>
> By the way:
> I believe, for both of them we should persue minimum complexity. 
>
> To hopefully make myself clearer:
>
> I believe, the number of user-facing functions should be as small as
> possible and thus do as much automagic [sic] user-intention guessing as
> possible - usually by help of the user's current context.
>
> However, by this I do *not* mean, that the actual underlying/inner/private functions
> are huge, hard to maintain, monolitic code blocks, but more in the
> sense - as you described above (and in earlier posts):
> meaningful small functions, which can be assembled to various 'dwim'
> user-facing-functions. 

A do-what-I-mean command would provide the point of entry I had in mind.
I am looking at this from the perspective of documentation.  It is
easier to explain how one command will "just work" in all scenaria than
to detail the technical differences between two or more commands.  The
user who has not enough experience with Denote will not be able to
relate to the technicalities.  Though yes, we don't want to eliminate
useful functionality in the interest of simpler docs.

> (I know, I simplify matters greatly here for myself, as I do not dare
> to dive into the intricacies of the actual code implementation, but
> rather want to stay at the high-level on the user-facing functionality.
> Please forgive my for my simplifications)

No worries!  I think the discussion thus far has been fecund and we
should now move to the coding side of things.  Once we have something in
place, we can comment on it and check if we can refine it and how.

> Referring to your function examples above:
>
> To make a simple example:
> For me (as a user) it is not so clear what the difference is between, e.g.:
>
> - denote-convert-file-to-denote
> - denote-rename-file
>
> Because - for example - if I call denote-rename-file on 'test.org'
> then 'test.org' is also 'converted' to a valid denote named file,
> e.g. '20220730T150629--test__tagt.org'
> (albeit w/o frontmatter).

Strictly speaking, the front matter does not count towards the
"validity" of a note.  The check we perform is if it starts with our
identifier and if it is one of our supported file types.  That is all we
need to create a link.

Notice that we do not require a title and keywords in the file name.
This is the same principle for not requiring front matter: those are
variable and are anyhow irrelevant to the validity of the links we
establish.

Our links break only if the user manually edits the identifiers in the
file name or deletes/removes the underlying file.  In other words, our
implementation is robust on the code side of things.

We do want the front matter though for the convenience and extended
functionality it provides, as we have already covered.

> Summing up:
>
> (IMHO)
> - we should strive for as few but powerful user-facing functions
>   as possible (based on well defined use cases) i.e. 'dwim'
>
> - implement them with as many simple functional blocks
>   (low level functions) as required.

Agreed!

> Sorry for this lengthy treatise and perhaps sounding a little
> academic & educational.. this is not my intention.
> I just try to make my thinking in this matter clearer.

I think it is better to make things clear than labour under all sorts of
assumptions which may lead to misunderstandings.

I suggest we now switch to coding instead of writing, produce an
implementation that conforms with what we have covered, and review it
later.

> Best Regards and thank you very much for all your work on Denote!
> It is very much appreciated.

You are welcome!

All the best,
Prot

-- 
Protesilaos Stavrou
https://protesilaos.com

Protesilaos Stavrou <info@protesilaos.com> writes:


>> From: Hanspeter Gisler <hpgisleropen@bluewin.ch>
>> Date: Sat, 30 Jul 2022 15:39:32 +0200
>
> Hello Hanspeter, Jean-Philippe!
>

Hello Prot,


>
> I think it is better to make things clear than labour under all sorts of
> assumptions which may lead to misunderstandings.
>
> I suggest we now switch to coding instead of writing, produce an
> implementation that conforms with what we have covered, and review it
> later.
>

Great!

Unfortunately, I'm no elisp expert by any means;
so any possible contribution from my side in this regard will be
neglectable - or even harmful .. ;-) 
However, if it helps to have an additional tester, let me know.


>> Best Regards and thank you very much for all your work on Denote!
>> It is very much appreciated.
>
> You are welcome!
>
> All the best,
> Prot

Best Regards
Hanspeter

>
> -- 
> Protesilaos Stavrou
> https://protesilaos.com

> From: Hanspeter Gisler <hpgisleropen@bluewin.ch>
> Date: Sun, 31 Jul 2022 21:41:28 +0200
>
> Hello Prot,

Hello Hanspeter,

>>
>> I think it is better to make things clear than labour under all sorts of
>> assumptions which may lead to misunderstandings.
>>
>> I suggest we now switch to coding instead of writing, produce an
>> implementation that conforms with what we have covered, and review it
>> later.
>>
>
> Great!
>
> Unfortunately, I'm no elisp expert by any means;
> so any possible contribution from my side in this regard will be
> neglectable - or even harmful .. ;-) 
> However, if it helps to have an additional tester, let me know.

The feedback alone is very helpful!  In my short experience with the
subject, I have learnt that the real difficulty in programming is to
elucidate the concepts: to understand and spell out clearly what it is
that you want (which is, of course, not specific to programming).  The
rest follows from there---even smart machines can write code now.

I will keep this thread updated with information about the new features.
We have already made some changes together with Jean-Philippe, though
the user-facing part is not there yet.

All the best,
Prot

-- 
Protesilaos Stavrou
https://protesilaos.com