~protesilaos/denote

13 2

Adding denote-org.el

Details
Message ID
<m2sfisexx7.fsf@MBA21.fritz.box>
DKIM signature
missing
Download raw message
Hi all

We've been discussing the potential benefits of a separate denote-org.el
file in the past. I've made such a branch and have used it in my
personal configuration for the last couple of weeks. It is included in
the patch in attachment.

Currently, denote-org.el introduces:
 1. denote-org-extract-subtree (copied from the manual)
 2. Org-mode Dynamic blocks, in two types:
    - 'denote-links' (similar to denote-link-add-links, with the option
       to only include missing links)
    - 'denote-backlinks' (to include all backlinks)

I hope this can be included in Denote proper (rather than a separate
package). It can then be loaded via (require 'denote-org) after denote &
Org-mode. 

The Org Dynamic blocks are particularly useful to collect different
notes and prepare them for export, as Org-mode source blocks can be used
to act on the lists the dynamic blocks generate. I'll include a note of
my own at the bottom of this message that illustrates its potential.

I hope this is useful to others and look forward to further discussion.

Cheers
Elias
Details
Message ID
<87y1si50sv.fsf@protesilaos.com>
In-Reply-To
<m2sfisexx7.fsf@MBA21.fritz.box> (view parent)
DKIM signature
missing
Download raw message
> From: Elias Storms <elias.storms@gmail.com>
> Date: Wed,  9 Nov 2022 20:12:10 +0100
>
> Hi all

Hello Elias,

> We've been discussing the potential benefits of a separate denote-org.el
> file in the past. I've made such a branch and have used it in my
> personal configuration for the last couple of weeks. It is included in
> the patch in attachment.
>
> Currently, denote-org.el introduces:
>  1. denote-org-extract-subtree (copied from the manual)
>  2. Org-mode Dynamic blocks, in two types:
>     - 'denote-links' (similar to denote-link-add-links, with the option
>        to only include missing links)
>     - 'denote-backlinks' (to include all backlinks)
>
> I hope this can be included in Denote proper (rather than a separate
> package). It can then be loaded via (require 'denote-org) after denote &
> Org-mode. 

Yes, I will include it and thank you for doing this!

> The Org Dynamic blocks are particularly useful to collect different
> notes and prepare them for export, as Org-mode source blocks can be used
> to act on the lists the dynamic blocks generate. I'll include a note of
> my own at the bottom of this message that illustrates its potential.
>
> I hope this is useful to others and look forward to further discussion.

I will review everything tonight and install your patch.  Will also make
updates to the manual, which you are always welcome to amend.

In general, I find it helpful to deal with the documentation myself as I
get the chance to tinker with the code and understand what it going on.
Thus I have an overview of the project.

Till later,
Prot

-- 
Protesilaos Stavrou
https://protesilaos.com
Details
Message ID
<875yfm1uap.fsf@protesilaos.com>
In-Reply-To
<87y1si50sv.fsf@protesilaos.com> (view parent)
DKIM signature
missing
Download raw message
> From: Protesilaos Stavrou <info@protesilaos.com>
> Date: Thu, 10 Nov 2022 16:41:52 +0200

> [... 26 lines elided]

>> The Org Dynamic blocks are particularly useful to collect different
>> notes and prepare them for export, as Org-mode source blocks can be used
>> to act on the lists the dynamic blocks generate. I'll include a note of
>> my own at the bottom of this message that illustrates its potential.
>>
>> I hope this is useful to others and look forward to further discussion.
>
> I will review everything tonight and install your patch.  Will also make
> updates to the manual, which you are always welcome to amend.

Hello again Elias,

I installed your patch and made some more changes to denote-org.el.
Everything is now in Denote's git repo.  Please take a look.  I added
some comments to denote-org.el that need to be reviewed.  Find them
with:

    M-x occur RET TODO\|FIXME

A couple of comments:

* How about we rename denote-org.el to denote-org-dblock.el?  This makes
  the scope more specific and avoids misunderstandings.  The problem I
  see right now is that it is not clear what Org-specific functionality
  belongs to denote.el and what to denote-org.el (I can justify it, but
  I am thinking in terms of how a user sees this).

* I say we remove 'denote-org-extract-subtree' and leave it where it
  was.  It does not belong with the rest of the code.  Perhaps we can
  add it to denote.el directly, though I prefer we do so once we have a
  general solution.

What do you think?

All the best,
Prot

P.S. Note that due to the exceptional circumstances in my life I may be
slow to respond.  I still have lots of messages to read and reply to.
But I am here.  All my projects continue as they were.

-- 
Protesilaos Stavrou
https://protesilaos.com
Details
Message ID
<m2cz9u8tvv.fsf@MBA21.fritz.box>
In-Reply-To
<875yfm1uap.fsf@protesilaos.com> (view parent)
DKIM signature
missing
Download raw message
Hello Prot

> P.S. Note that due to the exceptional circumstances in my life I may be
> slow to respond.

Please take your time! None of this is urgent.

> * How about we rename denote-org.el to denote-org-dblock.el?  This makes
>   the scope more specific and avoids misunderstandings.  The problem I
>   see right now is that it is not clear what Org-specific functionality
>   belongs to denote.el and what to denote-org.el (I can justify it, but
>   I am thinking in terms of how a user sees this).
>
> * I say we remove 'denote-org-extract-subtree' and leave it where it
>   was.  It does not belong with the rest of the code.  Perhaps we can
>   add it to denote.el directly, though I prefer we do so once we have a
>   general solution.

Excellent ideas. It makes sense to keep the scope specific, and
the main functionality is the dblock one. Moreover, 'denote-org.el'
might give the impression that it only works with Denote setups geared
towards Org-mode, while the functions work with any type of setup (as
long as the Org dblock is in an Org-mode file, obviously). Even better:
this doesn't need to be used from within a Denote note at all.
So yes, great idea. And we'll leave the extract-subtree function in the manual.


To respond to your changes & remarks:

(1)

You renamed 'org-dblock-write:denote-links' to
'denote-org-dblock-write-links', but it is important to keep the
original name. I tried to explain this in the comment: by using
`org-dblock-write:' as the first part of the name, Org-mode knows which
function to call when the dynamic block is computed.

This is related to the following:
   ;; FIXME 2022-11-10: The `denote-org-dblock-write-links' is not used
   ;; anywhere.  We need to check again.
The explanation is that this is indeed not called anywhere within this
codebase, but is what Org-mode uses when you hit C-c C-c on a
'denote-links' code block.

The same is applicable to the 'org-dblock-write:backlinks' function.


(2)

   ;; TODO 2022-11-10: Should we make this a `read-regexp' as is the
   ;; case with `denote-link-add-missing-links'?  Also add the
   ;; minibuffer history.

That makes sense indeed, and is more in line with the rest of Denote.


(3)

  ;; TODO 2022-11-10: check doc string.  I simply added something here
  ;; to placate the compiler.

Yes, I didn't really know what to write either. I checked and the other
'org-dblock-write:' functions don't have any docstring at all. Perhaps
in this docstring we can mention that this function is only called by
Org-mode itself?


(4)

    ;; TODO 2022-11-10: Perhaps we can tweak the code so that instead
    ;; of `join-line' we delete empty lines within the affected
    ;; region.

Sorry, I forgot about that (join-line) when I submitted the patch. It's
something that I added for my own convenience, but shouldn't be here.
The empty line is added by 'denote-link-add-links' and
'denote-link-add-missing-links' as well, so is perhaps best addressed
elsewhere in the codebase. Let's remove these lines.


Take care!
Elias
Details
Message ID
<87mt8yuord.fsf@protesilaos.com>
In-Reply-To
<m2cz9u8tvv.fsf@MBA21.fritz.box> (view parent)
DKIM signature
missing
Download raw message
> From: Elias Storms <elias.storms@gmail.com>
> Date: Thu, 10 Nov 2022 20:55:42 +0100
>
> Hello Prot

Hello Elias,

>> P.S. Note that due to the exceptional circumstances in my life I may be
>> slow to respond.
>
> Please take your time! None of this is urgent.

You are right!  Though certain habits are hard to change and I still
care.  Plus, I need a break from that loop.

>> * How about we rename denote-org.el to denote-org-dblock.el?  This makes
>>   the scope more specific and avoids misunderstandings.  The problem I
>>   see right now is that it is not clear what Org-specific functionality
>>   belongs to denote.el and what to denote-org.el (I can justify it, but
>>   I am thinking in terms of how a user sees this).
>>
>> * I say we remove 'denote-org-extract-subtree' and leave it where it
>>   was.  It does not belong with the rest of the code.  Perhaps we can
>>   add it to denote.el directly, though I prefer we do so once we have a
>>   general solution.
>
> Excellent ideas. It makes sense to keep the scope specific, and
> the main functionality is the dblock one. Moreover, 'denote-org.el'
> might give the impression that it only works with Denote setups geared
> towards Org-mode, while the functions work with any type of setup (as
> long as the Org dblock is in an Org-mode file, obviously). Even better:
> this doesn't need to be used from within a Denote note at all.
> So yes, great idea. And we'll leave the extract-subtree function in the manual.

Very well!  Please prepare a new patch that renames the file and makes
the other changes, including the corrections to the renaming mistakes I
made.

> To respond to your changes & remarks:
>
> (1)
>
> You renamed 'org-dblock-write:denote-links' to
> 'denote-org-dblock-write-links', but it is important to keep the
> original name.

> [... 14 lines elided]

Oh, I see.  You tried to explain but I failed to understand.  Sorry!

> (2)
>
>    ;; TODO 2022-11-10: Should we make this a `read-regexp' as is the
>    ;; case with `denote-link-add-missing-links'?  Also add the
>    ;; minibuffer history.
>
> That makes sense indeed, and is more in line with the rest of Denote.

Okay.  Please use that style.  It is fine to share the same minibuffer
history, unless you think we really need a new history variable (which I
am happy with).

> (3)
>
>   ;; TODO 2022-11-10: check doc string.  I simply added something here
>   ;; to placate the compiler.
>
> Yes, I didn't really know what to write either. I checked and the other
> 'org-dblock-write:' functions don't have any docstring at all. Perhaps
> in this docstring we can mention that this function is only called by
> Org-mode itself?

In this case, write something like:

    Used by `the-org-function' with PARAMS.

This is enough to tell us where to look in case we need to.

> (4)
>
>     ;; TODO 2022-11-10: Perhaps we can tweak the code so that instead
>     ;; of `join-line' we delete empty lines within the affected
>     ;; region.
>
> Sorry, I forgot about that (join-line) when I submitted the patch. It's
> something that I added for my own convenience, but shouldn't be here.
> The empty line is added by 'denote-link-add-links' and
> 'denote-link-add-missing-links' as well, so is perhaps best addressed
> elsewhere in the codebase. Let's remove these lines.

In principle, I am fine with applying the change elsewhere as you
suggested.  Though we need to make sure not to introduce subtle breaking
changes.  The function that does the work is 'denote-link--prepare-links'.
And the beauty here is that the format is not hardcoded but is declared
with 'denote-link--prepare-links-format'.  As such, you can simply 'let'
bind the latter to not have the newline character (or, anyhow, to
produce the presentation you want).

Though, again, I have no problem making changes elsewhere if those are
appropriate.

All the best,
Prot

-- 
Protesilaos Stavrou
https://protesilaos.com
Details
Message ID
<m28rkh94vu.fsf@MBA21.fritz.box>
In-Reply-To
<87mt8yuord.fsf@protesilaos.com> (view parent)
DKIM signature
missing
Download raw message
Hi Prot

I've prepared some commits (attached here as separate patches -- not
sure if I can create a single patch with multiple commints that are not
squashed?).

The file is renamed and the points you mentioned are addressed.

Two remaining things:
 - I haven't done anything about the 'join-line' issue yet. This is
   still a TODO.
 - I'm unsure whether the 'org-dblock-write:' functions need an
   ;;;###autoload. I think they do, but I'm not sure yet.

RE: The join-line TODO

> In principle, I am fine with applying the change elsewhere as you
> suggested.  Though we need to make sure not to introduce subtle breaking
> changes.  The function that does the work is 'denote-link--prepare-links'.
> And the beauty here is that the format is not hardcoded but is declared
> with 'denote-link--prepare-links-format'.  As such, you can simply 'let'
> bind the latter to not have the newline character (or, anyhow, to
> produce the presentation you want).

If this is 'let' to something else (without a newline char at the end),
won't the output be all on a single line? (Thus not really producing a
list.) Anyway, this is something to look into in the future.

All the best
Elias
Details
Message ID
<87sfiniiei.fsf@protesilaos.com>
In-Reply-To
<m28rkh94vu.fsf@MBA21.fritz.box> (view parent)
DKIM signature
missing
Download raw message
> From: Elias Storms <elias.storms@gmail.com>
> Date: Fri, 11 Nov 2022 11:05:27 +0100
>
> Hi Prot

Hello Elias,

> I've prepared some commits (attached here as separate patches -- not
> sure if I can create a single patch with multiple commints that are not
> squashed?).

Don't worry about it.  I find a series of commits to be easier to read.
I installed them and pushed the changes.

> The file is renamed and the points you mentioned are addressed.
>
> Two remaining things:
>  - I haven't done anything about the 'join-line' issue yet. This is
>    still a TODO.

The 'join-line' is not a problem, anyway.  I don't mind if it stays that
way.  Whatever you prefer.

>  - I'm unsure whether the 'org-dblock-write:' functions need an
>    ;;;###autoload. I think they do, but I'm not sure yet.

I think they will be needed.  There can be a scenario where the user has
not yet loaded 'denote-org-dblock' but is working on an Org file that
has dynamic blocks.  Right?

The only remaining issue is the PARAMS argument of the function
org-dblock-write:denote-backlinks.  It is not used anywhere.  Is PARAMS
needed?  If yes, then the function needs to make use of it.  If we do
not need it, then we can declare the function thus:

    (defun org-dblock-write:denote-backlinks (_params)

The underscore tells the compiler to ignore the fact that this argument
is unused.

> RE: The join-line TODO
>
>> In principle, I am fine with applying the change elsewhere as you
>> suggested.  Though we need to make sure not to introduce subtle breaking
>> changes.  The function that does the work is 'denote-link--prepare-links'.
>> And the beauty here is that the format is not hardcoded but is declared
>> with 'denote-link--prepare-links-format'.  As such, you can simply 'let'
>> bind the latter to not have the newline character (or, anyhow, to
>> produce the presentation you want).
>
> If this is 'let' to something else (without a newline char at the end),
> won't the output be all on a single line? (Thus not really producing a
> list.) Anyway, this is something to look into in the future.

Oh, I see.  I misunderstood the intent.

Once we finalise this, I will write an entry in the manual.

All the best,
Prot

-- 
Protesilaos Stavrou
https://protesilaos.com
Details
Message ID
<m2edu5o01m.fsf@MBA21.fritz.box>
In-Reply-To
<87sfiniiei.fsf@protesilaos.com> (view parent)
DKIM signature
missing
Download raw message
Hello Prot

> The only remaining issue is the PARAMS argument of the function
> org-dblock-write:denote-backlinks.  It is not used anywhere.  Is PARAMS
> needed?

The write function needs to take one argument, else Org-mode will
complain when computing the block. But the _ solution seems to work just
fine (just tested it).

Let me know if you need input when writing the entry for the manual.

All the best
Elias
Details
Message ID
<87iljesv4m.fsf@protesilaos.com>
In-Reply-To
<m2edu5o01m.fsf@MBA21.fritz.box> (view parent)
DKIM signature
missing
Download raw message
> From: Elias Storms <elias.storms@gmail.com>
> Date: Mon, 14 Nov 2022 19:31:27 +0100
>
> Hello Prot

Hello Elias,

>> The only remaining issue is the PARAMS argument of the function
>> org-dblock-write:denote-backlinks.  It is not used anywhere.  Is PARAMS
>> needed?
>
> The write function needs to take one argument, else Org-mode will
> complain when computing the block. But the _ solution seems to work just
> fine (just tested it).

Okay, I will make the change right now.

> Let me know if you need input when writing the entry for the manual.

Thank you!  I plan to write it over the weekend.

All the best,
Prot

-- 
Protesilaos Stavrou
https://protesilaos.com
Details
Message ID
<87bkp3ey2t.fsf@protesilaos.com>
In-Reply-To
<87iljesv4m.fsf@protesilaos.com> (view parent)
DKIM signature
missing
Download raw message
> From: Protesilaos Stavrou <info@protesilaos.com>
> Date: Wed, 16 Nov 2022 18:48:41 +0200

> [... 18 lines elided]

>> Let me know if you need input when writing the entry for the manual.
>
> Thank you!  I plan to write it over the weekend.

Hello again Elias!

As promised, I wrote the entry in the manual:
<https://protesilaos.com/emacs/denote#h:8b542c50-dcc9-4bca-8037-a36599b22779>.

You are welcome to suggest changes to it.

All the best,
Prot

-- 
Protesilaos Stavrou
https://protesilaos.com
Details
Message ID
<m2iljakdhs.fsf@MBA21.fritz.box>
In-Reply-To
<87bkp3ey2t.fsf@protesilaos.com> (view parent)
DKIM signature
missing
Download raw message
Hi Prot

> As promised, I wrote the entry in the manual:
> <https://protesilaos.com/emacs/denote#h:8b542c50-dcc9-4bca-8037-a36599b22779>.
>
> You are welcome to suggest changes to it.

Thanks for this! I think it is concise and fairly clear. In the patch in
attachment I make some suggestions for minor changes, fix a typo, and
correct a small misunderstanding about the :missing-only option.

All the best
Elias
Details
Message ID
<87leo6guvy.fsf@protesilaos.com>
In-Reply-To
<m2iljakdhs.fsf@MBA21.fritz.box> (view parent)
DKIM signature
missing
Download raw message
> From: Elias Storms <elias.storms@gmail.com>
> Date: Sat, 19 Nov 2022 19:12:15 +0100
>
> Hi Prot

Good day Elias,

>> As promised, I wrote the entry in the manual:
>> <https://protesilaos.com/emacs/denote#h:8b542c50-dcc9-4bca-8037-a36599b22779>.
>>
>> You are welcome to suggest changes to it.
>
> Thanks for this! I think it is concise and fairly clear. In the patch in
> attachment I make some suggestions for minor changes, fix a typo, and
> correct a small misunderstanding about the :missing-only option.

I installed your patch and pushed the change.  Thank you!

Note that I cannot find 'denote-link-add-backlinks'.  You mention it in
the manual and in the Commentary of the file.  Maybe this is a command
you maintain in your own config?  We could have it in denote.el.

All the best,
Prot

-- 
Protesilaos Stavrou
https://protesilaos.com
Details
Message ID
<m2ilj88y7r.fsf@MBA21.fritz.box>
In-Reply-To
<87leo6guvy.fsf@protesilaos.com> (view parent)
DKIM signature
missing
Download raw message
Hi Prot

> Note that I cannot find 'denote-link-add-backlinks'.  You mention it in
> the manual and in the Commentary of the file.  Maybe this is a command
> you maintain in your own config?  We could have it in denote.el.

Oh wow, thats a mistake on my part -- I was convinced it was there but
it's not even part of my personal config.

Backlinks change so often, that I don't think it makes sense to include
them as a list without keeping this list up to date (which the Org
dynamic block achieves) -- or it's more logical to simply use
denote-link-find-backlink.

In any case, I've removed any references to this non-existing function.
Please see the patch in attachment, and sorry for any confusion...

All the best
Elias
Details
Message ID
<87cz9f4qxt.fsf@protesilaos.com>
In-Reply-To
<m2ilj88y7r.fsf@MBA21.fritz.box> (view parent)
DKIM signature
missing
Download raw message
> From: Elias Storms <elias.storms@gmail.com>
> Date: Mon, 21 Nov 2022 10:05:30 +0100
>
> Hi Prot

Hello Elias,

>> Note that I cannot find 'denote-link-add-backlinks'.  You mention it in
>> the manual and in the Commentary of the file.  Maybe this is a command
>> you maintain in your own config?  We could have it in denote.el.
>
> Oh wow, thats a mistake on my part -- I was convinced it was there but
> it's not even part of my personal config.

That's okay!  I installed your patch and pushed the changes.  Thank you!

All the best,
Prot

-- 
Protesilaos Stavrou
https://protesilaos.com
Reply to thread Export thread (mbox)