[FR] Enhancing footnote managment (via indirect buffer)?

[FR] Enhancing footnote managment (via indirect buffer)?

[Andrea Lazzarini]

I am writing to you because I have recently published a simple package called
org-footnote-assistant [https://github.com/lazzalazza/org-footnote-assistant],
which aims at improving the overall functionality and user experience of footnotes
within Org Mode.

The current management of footnotes has certain limitations that can sometimes
hinder the overall user experience. One major limitation is the limited inline
viewing of footnotes, which makes it challenging to review and modify footnote
content precisely and without disrupting the workflow.

Org-footnote-assistant addresses the limitations of inline viewing of footnotes
by using an indirect buffer.The package also provides commands for easy
navigation between footnote references, enabling quick jumps to the next or
previous reference.

On Reddit I have been encouraged to seek your feedback and explore the
possibility of integrating some of these features upstream to prevent bitrot and
ensure wider accessibility, and I am of course open to any suggestion or input.

Best,

Andrea Lazzarini
GitHub: lazzalazza

Re: [FR] Enhancing footnote managment (via indirect buffer)?

[Ihor Radchenko]

Andrea Lazzarini <andrea.lazzarini1@gmail.com> writes:

> I am writing to you because I have recently published a simple package called
> org-footnote-assistant [https://github.com/lazzalazza/org-footnote-assistant],
> which aims at improving the overall functionality and user experience of footnotes
> within Org Mode.

Thanks for your interest to contribute to Org mode!

> The current management of footnotes has certain limitations that can sometimes
> hinder the overall user experience. One major limitation is the limited inline
> viewing of footnotes, which makes it challenging to review and modify footnote
> content precisely and without disrupting the workflow.
>
> Org-footnote-assistant addresses the limitations of inline viewing of footnotes
> by using an indirect buffer.

I am not sure if indirect buffer is the right approach for _previews_.
It is more common in Emacs to either use eldoc or tooltips.
You may use
https://www.masteringemacs.org/article/seamlessly-merge-multiple-documentation-sources-eldoc
as reference about eldoc.

> The package also provides commands for easy
> navigation between footnote references, enabling quick jumps to the next or
> previous reference.

This sounds like something we can extend `org-forward-element' and
`org-backward-element' with - it may not only jump to the next element,
but also jump to the next element of the same type. Jumping to next/previous
footnote might will useful as a separate command as well though, as a
complement to the existing `org-next-item', `org-next-link',
`org-next-block', etc.

"Footnote Editing Window" sounds like a duplicate of the existing C-c '
functionality (`org-edit-special').

"Customized Footnote Definition Jumping" does not sound too different
from editing window. May you elaborate why it is useful?

I am not sure if I understand what "Enhanced Footnote Reference
Searching" does from its description.

"Eeasier Footnote Deletion": How is it different from `org-footnote-delete'?

-- 
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at <https://orgmode.org/>.
Support Org development at <https://liberapay.com/org-mode>,
or support my work at <https://liberapay.com/yantar92>

Re: [FR] Enhancing footnote managment (via indirect buffer)?

[Andrea Lazzarini]

> Il giorno 22 mag 2023, alle ore 13:45, Ihor Radchenko <yantar92@posteo.net> ha scritto:
> 
> Andrea Lazzarini <andrea.lazzarini1@gmail.com> writes:
> 
>> I am writing to you because I have recently published a simple package called
>> org-footnote-assistant [https://github.com/lazzalazza/org-footnote-assistant],
>> which aims at improving the overall functionality and user experience of footnotes
>> within Org Mode.
> 
> Thanks for your interest to contribute to Org mode!

Thank you for your kind reply, for the consideration and the great tips!

> 
>> The current management of footnotes has certain limitations that can sometimes
>> hinder the overall user experience. One major limitation is the limited inline
>> viewing of footnotes, which makes it challenging to review and modify footnote
>> content precisely and without disrupting the workflow.
>> 
>> Org-footnote-assistant addresses the limitations of inline viewing of footnotes
>> by using an indirect buffer.
> 
> I am not sure if indirect buffer is the right approach for _previews_.
> It is more common in Emacs to either use eldoc or tooltips.
> You may use
> https://www.masteringemacs.org/article/seamlessly-merge-multiple-documentation-sources-eldoc
> as reference about eldoc.
> 

Eldoc (or tooltips) could be great for previewing: I'm going to give them a try
and to see how they might be integrated in an academic writing workflow.
I wander if they would maintain buffer-specific highlighting though...

>> The package also provides commands for easy
>> navigation between footnote references, enabling quick jumps to the next or
>> previous reference.
> 
> This sounds like something we can extend `org-forward-element' and
> `org-backward-element' with - it may not only jump to the next element,
> but also jump to the next element of the same type. Jumping to next/previous
> footnote might will useful as a separate command as well though, as a
> complement to the existing `org-next-item', `org-next-link',
> `org-next-block', etc.
> 

Yes, this actually sounds great, and would make it really easier to implement
focused jumping.

> "Footnote Editing Window" sounds like a duplicate of the existing C-c '
> functionality (`org-edit-special').
> 

Yep! It is, and that's also very good to know: I am sorry but this totally flew
over my head in these years of using org... 

> "Customized Footnote Definition Jumping" does not sound too different
> from editing window. May you elaborate why it is useful?
> 
> I am not sure if I understand what "Enhanced Footnote Reference
> Searching" does from its description.
> 
> "Eeasier Footnote Deletion": How is it different from `org-footnote-delete'?
> 

That was nothing more than a simple wrapper for org-footnote-delete, which
is not an interactive function: btw, I am curious to know if there is a reason for
that. Why should users re-implement org-footnote-delete with wrappers if 
they want to use it interactively?

Many thanks!

Andrea Lazzarini

> -- 
> Ihor Radchenko // yantar92,
> Org mode contributor,
> Learn more about Org mode at <https://orgmode.org/>.
> Support Org development at <https://liberapay.com/org-mode>,
> or support my work at <https://liberapay.com/yantar92>

Re: [FR] Enhancing footnote managment (via indirect buffer)?

[Ihor Radchenko]

Andrea Lazzarini <andrea.lazzarini1@gmail.com> writes:

> Eldoc (or tooltips) could be great for previewing: I'm going to give them a try
> and to see how they might be integrated in an academic writing workflow.
> I wander if they would maintain buffer-specific highlighting though...

AFAIK, Eldoc expects a function that will return the string to be
displayed. You can use `font-lock-ensure' to fontify the footnote
definition you need to display. Then, the copied string will hold the
fontification as it would be in Org mode buffer.

>> "Eeasier Footnote Deletion": How is it different from `org-footnote-delete'?
>> 
>
> That was nothing more than a simple wrapper for org-footnote-delete, which
> is not an interactive function: btw, I am curious to know if there is a reason for
> that. Why should users re-implement org-footnote-delete with wrappers if 
> they want to use it interactively?

I see nothing in git history and mailing list.
I think that it makes sense to convert org-footnote-delete into
interactive function.

-- 
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at <https://orgmode.org/>.
Support Org development at <https://liberapay.com/org-mode>,
or support my work at <https://liberapay.com/yantar92>

Re: [FR] Enhancing footnote managment (via indirect buffer)?

[Andrea Lazzarini]

> Il giorno 22 mag 2023, alle ore 17:30, Ihor Radchenko <yantar92@posteo.net> ha scritto:
> 
> Andrea Lazzarini <andrea.lazzarini1@gmail.com> writes:
> 
>> Eldoc (or tooltips) could be great for previewing: I'm going to give them a try
>> and to see how they might be integrated in an academic writing workflow.
>> I wander if they would maintain buffer-specific highlighting though...
> 
> AFAIK, Eldoc expects a function that will return the string to be
> displayed. You can use `font-lock-ensure' to fontify the footnote
> definition you need to display. Then, the copied string will hold the
> fontification as it would be in Org mode buffer.
> 

Ok, very good. This is my first attempt at it and, apparently, it works.

(setq eldoc-echo-area-use-multiline-p nil)

(defun org-footnote-eldoc-function (callback &rest _ignored)
  "Return the definition of the footnote at point for Eldoc."
  (when (org-footnote-at-reference-p)
    (let* ((footnote-label (car (org-footnote-at-reference-p)))
           (footnote-definition (org-footnote-get-definition footnote-label))
           (start-def (nth 1 footnote-definition))
           (end-def (nth 2 footnote-definition)))
      (when footnote-definition
        (font-lock-ensure start-def end-def)
        (format "%s"  (buffer-substring start-def end-def))))))

(defun org-footnote-enable-eldoc ()
  "Enable Eldoc support for Org Mode footnotes."
  (add-hook 'eldoc-documentation-functions #'org-footnote-eldoc-function nil t))

(add-hook 'org-mode-hook #'org-footnote-enable-eldoc)

I now wonder if there is a way to prevent changing eldoc-echo-area-use-multiline-p
to nil globally to prevent footnotes from appearing there and not only in the
eldoc-doc-buffer.

Provided this might be considered useful, where could such a feature be
implemented? I checked org-eldoc.el, but it looks like it aims at
providing programming documentation inside org-mode rather than
implementing specific org-oriented features.


>>> "Eeasier Footnote Deletion": How is it different from `org-footnote-delete'?
>>> 

>> That was nothing more than a simple wrapper for org-footnote-delete, which
>> is not an interactive function: btw, I am curious to know if there is a reason for
>> that. Why should users re-implement org-footnote-delete with wrappers if 
>> they want to use it interactively?
> 
> I see nothing in git history and mailing list.
> I think that it makes sense to convert org-footnote-delete into
> interactive function.

That would be great.

I've fiddled with org-edit-special and I see it has a major flaw, at least in my opinion.
It inserts all changes without keeping track of the undos, as opposed to the indirect
buffer solution, which also had the advantage of doing everything from a single buffer:
it operates as some sort of 'window' on a part of the file, rather than feeling as some
sort of out-of-the-normal operation. Aren't there other possibile use cases for indirect
buffers in org mode? Why are they considered inferior to other solutions? I ask just
for my understanding.

(A combination of eldoc + org-edit-special might be rather affecting on the
seamlessness of the workflow, but this is of course my simple personal opinion).


> Il giorno 22 mag 2023, alle ore 13:45, Ihor Radchenko <yantar92@posteo.net> ha scritto:
> 
> This sounds like something we can extend `org-forward-element' and
> `org-backward-element' with - it may not only jump to the next element,
> but also jump to the next element of the same type. Jumping to next/previous
> footnote might will useful as a separate command as well though, as a
> complement to the existing `org-next-item', `org-next-link',
> `org-next-block', etc.


Functions that make navigation between similar elements easier would simply be great.

Re: [FR] Enhancing footnote managment (via indirect buffer)?

[Payas Relekar]

Andrea Lazzarini <andrea.lazzarini1@gmail.com> writes:

> I've fiddled with org-edit-special and I see it has a major flaw, at least in my opinion.
> It inserts all changes without keeping track of the undos, as opposed to the indirect
> buffer solution, which also had the advantage of doing everything from a single buffer:
> it operates as some sort of 'window' on a part of the file, rather than feeling as some
> sort of out-of-the-normal operation. Aren't there other possibile use cases for indirect
> buffers in org mode? Why are they considered inferior to other solutions? I ask just
> for my understanding.
>
> (A combination of eldoc + org-edit-special might be rather affecting on the
> seamlessness of the workflow, but this is of course my simple personal opinion).

I've been playing with org-footnote-assistance, and this is again just
another opinion, but I'm also preferring the indirect buffer. It just
puts things in better perspective.


--

Re: [FR] Enhancing footnote managment (via indirect buffer)?

[Ihor Radchenko]

Payas Relekar <relekarpayas@gmail.com> writes:

> I've been playing with org-footnote-assistance, and this is again just
> another opinion, but I'm also preferring the indirect buffer. It just
> puts things in better perspective.

I'd prefer to integrate things with `org-edit-special', if possible.
Possibly extending `org-edit-special' functionality.

The pros for `org-edit-special' are that we can escape certain edge
cases. In particular, there is a known edge case when footnote
definition contains an src block with 2+ blank lines. The blank lines
are treated as the end of the footnote definition and src block is not
recognized. Also, `org-edit-footnote-reference' takes care about
removing common indentation.

-- 
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at <https://orgmode.org/>.
Support Org development at <https://liberapay.com/org-mode>,
or support my work at <https://liberapay.com/yantar92>

Re: [FR] Enhancing footnote managment (via indirect buffer)?

[Ihor Radchenko]

Andrea Lazzarini <andrea.lazzarini1@gmail.com> writes:

> I now wonder if there is a way to prevent changing eldoc-echo-area-use-multiline-p
> to nil globally to prevent footnotes from appearing there and not only in the
> eldoc-doc-buffer.

See the docstring for `eldoc-documentation-functions' - you can call the
CALLBACK directly, telling what to show in the echo area (:echo).

> Provided this might be considered useful, where could such a feature be
> implemented? I checked org-eldoc.el, but it looks like it aims at
> providing programming documentation inside org-mode rather than
> implementing specific org-oriented features.

Note that org-eldoc is not a part of Org - it is a third-party package
from org-contrib.

The right place to configure eldoc is org-mode definition in org.el - we
setup a number of major-mode specific settings. Configuring eldoc can be
considered a part of org-mode major mode setup.

-- 
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at <https://orgmode.org/>.
Support Org development at <https://liberapay.com/org-mode>,
or support my work at <https://liberapay.com/yantar92>

Re: [FR] Enhancing footnote managment (via indirect buffer)?

[Ihor Radchenko]

Andrea Lazzarini <andrea.lazzarini1@gmail.com> writes:

> I've tried to use org-edit-special with a src block with 2+ blank lines and the second #+end_src is not seen as part of the footnote.
> Is this the edge problem you were addressing? I get the same result with the indirect buffer.

Yup, it is one of the edge problems that org-edit-special could (though
currently does not) address. Indirect buffer cannot easily address such
problems.

-- 
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at <https://orgmode.org/>.
Support Org development at <https://liberapay.com/org-mode>,
or support my work at <https://liberapay.com/yantar92>

Re: [FR] Enhancing footnote managment (via indirect buffer)?

[Andrea Lazzarini]

[-- Attachment #1: Type: text/plain, Size: 837 bytes --]


> Il giorno 2 lug 2023, alle ore 12:56, Ihor Radchenko <yantar92@posteo.net> ha scritto:
> 
> Hello,
> 
> It has been over one month since the last message in this thread.
> Are you still interested to work on this feature? Do you need any help?


Hi,

I was busy with work and had less time to focus on this, sorry!
Well, sorry for the noob question but how do you suggest I fork the org.el file to start tinkering with it?
I would pass through the Org repository on Savannah, as specified here: https://orgmode.org/worg/org-contribute.html <https://orgmode.org/worg/org-contribute.html>.
What do you suggest for testing the changes? Should I then send a diff?

I guess I can manage to have the code I already produced working in org.el. In what section of it should the eldoc package be required?

Thank you so much.

[-- Attachment #2: Type: text/html, Size: 2197 bytes --]

Re: [FR] Enhancing footnote managment (via indirect buffer)?

[Ihor Radchenko]

Andrea Lazzarini <andrea.lazzarini1@gmail.com> writes:

> I was busy with work and had less time to focus on this, sorry!

No problem. Just wanted to make sure that this thread did not fall
through the cracks.

> Well, sorry for the noob question but how do you suggest I fork the org.el file to start tinkering with it?
> I would pass through the Org repository on Savannah, as specified here: https://orgmode.org/worg/org-contribute.html <https://orgmode.org/worg/org-contribute.html>.

You can just use git version of Org:
https://orgmode.org/manual/Installation.html

Then, you can edit the files directly there.

> What do you suggest for testing the changes? Should I then send a diff?

Depends on your familiarity with git.
The easiest for us would be attaching a patch, but you can also send a
diff, if it is easier for you.
We have all the details in
https://orgmode.org/worg/org-contribute.html#org0d9c39b

You can also use Magit (https://www.youtube.com/watch?v=7ywEgcbaiys).

> I guess I can manage to have the code I already produced working in org.el. In what section of it should the eldoc package be required?

The eldoc setup should be somewhere inside

  (define-derived-mode org-mode outline-mode "Org"


-- 
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at <https://orgmode.org/>.
Support Org development at <https://liberapay.com/org-mode>,
or support my work at <https://liberapay.com/yantar92>

Re: [FR] Enhancing footnote managment (via indirect buffer)?

[Ihor Radchenko]

Ihor Radchenko <yantar92@posteo.net> writes:

> Andrea Lazzarini <andrea.lazzarini1@gmail.com> writes:
>
>> I was busy with work and had less time to focus on this, sorry!
>
> No problem. Just wanted to make sure that this thread did not fall
> through the cracks.

It has been two months since the last message here.
If you encounter any difficulties, feel free to ask me anything.

-- 
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at <https://orgmode.org/>.
Support Org development at <https://liberapay.com/org-mode>,
or support my work at <https://liberapay.com/yantar92>

Re: [FR] Enhancing footnote managment (via indirect buffer)?

[Ihor Radchenko]

Ihor Radchenko <yantar92@posteo.net> writes:

> It has been two months since the last message here.

Closing due to inactivity.
Canceled.

"Closing" does not mean that this feature will not be accepted. I am
just removing it from the list of tracked tasks that require maintainer
attention.

-- 
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at <https://orgmode.org/>.
Support Org development at <https://liberapay.com/org-mode>,
or support my work at <https://liberapay.com/yantar92>