Imenu and structured documents

Imenu and structured documents

[Daniele Nicolodi]

Hello,

an user of a major-mode I co-maintain
https://bitbucket.org/blais/beancount/src/default/editors/emacs/beancount.el
asked for supporting imenu: the major mode allows to section the file
leveraging outline-minor-mode and the user would like to see the list of
sections in imenu.

I don't use imenu myself, but reading the documentation it seems that
the use case at hand is not very well supported. The problem is that the
sections in a beancount input file can contain beancount directives AND
subsections. A typical example:

;;; 2017

2016-12-31 balance Assets:Savings 1000000.00 USD
2017-01-01 open Assets:Checking

;;;; 2017 January

2019-01-01 * "Foo"
  Expenses:Foo   20.00 USD
  Assets:Checking

;;;; 2017 February

2019-02-01 * "Foo"
  Expenses:Foo   30.00 USD
  Assets:Checking

where section headings have prefix ";;;+\s+".

The problem is that while imenu allows for defining entries and
submenus, submenus cannot be entries themselves. Thus, using submenus
for headings deep in the hierarchy, in the example above, there is no
way to have a menu entry jumping to "2017" because the menu structure
would be:

2017 -- 2017 January
        2017 February

I had a look at what other modes do I there isn't an unique way to
handle this. org-mode uses submenus, while latex-mode uses a flat menu
structure with prefixes, that in the example above would result in menu
entries like:

. 2017
. . 2017 January
. . 2017 February

I haven't looked at other modes (and at the top of my head I cannot
think about other modes that support buffers with similar structure).

What is the best way to handle this?

I am tempted to go the latex-mode way because it feels more complete,
but it is also a bit ugly.

Thank you!

Cheers,
Dan

Re: Imenu and structured documents

[Stefan Monnier]

> . 2017
> . . 2017 January
> . . 2017 February

In Imenu, the submenu structure usually doesn't reflect the document
structure, but instead it is just a fixed structure for different
*categories* of entries (e.g. functions-vs-classes-vs-variables), so I'd
expect all the sections and subsections to just be placed within the
same "level".

I use Imenu via the minibuffer (with completion) rather than via mouse
selection in a GUI menu (or via Speedbar).  I'm not sure if it's the
more common way to use Imenu, but it's one where this flat structure
works fairly well.


        Stefan

Re: Imenu and structured documents

[Daniele Nicolodi]

On 28/09/2019 16:16, Stefan Monnier wrote:
>> . 2017
>> . . 2017 January
>> . . 2017 February
> 
> In Imenu, the submenu structure usually doesn't reflect the document
> structure, but instead it is just a fixed structure for different
> *categories* of entries (e.g. functions-vs-classes-vs-variables), so I'd
> expect all the sections and subsections to just be placed within the
> same "level".
> 
> I use Imenu via the minibuffer (with completion) rather than via mouse
> selection in a GUI menu (or via Speedbar).  I'm not sure if it's the
> more common way to use Imenu, but it's one where this flat structure
> works fairly well.

Thanks Stefan, this is useful information.

Do you use imenu with latex-mode? From the description of your use case
I think you do not use it with org-mode. Is prefixing sublevels with an
indicator that represent the hierarchy as done in latex-mode something
desirable? I may imagine that it can be annoying is the goal is
completion in the minibuffer.

Thank you.

Cheers,
Dan

Re: Imenu and structured documents

[Stefan Monnier]

> Do you use imenu with latex-mode?

No, I use reftex instead of imenu (handles the multi-file case better).

> From the description of your use case
> I think you do not use it with org-mode.

No, indeed.

> Is prefixing sublevels with an indicator that represent the hierarchy
> as done in latex-mode something desirable?

For my use case, it's not desirable, no.  But I use a custom-made
completion table, with which I use substring completion, so they don't
really hurt either.

> I may imagine that it can be annoying is the goal is completion in
> the minibuffer.

I haven't tried the normal completion table lately, but if we want to
use this ". . " kind of prefixing, we should make sure substring
completion works for it.


        Stefan