ENB: About headline numbers

[Edward K. Ream]

PR #3227 contains a draft implementation of issue #3121: headline numbers.

While working on this PR, several problems became apparent. This Engineering Notebook post will discuss my present thoughts. I encourage all comments.

Undo/Redo

My first thought was that undo/redo is not necessary. For example, delete-all-headline-numbers will undo add-all-headline numbers. And in fact, the PR passes this round-trip test.

But my first thought was wrong:

- It's easier to type Ctrl-Z than to invoke the command that would undo the previous command.

- Undo/Redo methods for headlines will be valuable all by themselves.

- These undo/redo methods won't depend on how the headlines change.

Happily, Félix has volunteered to add these undo/redo methods.

The following sections discuss several nasty problems with headline numbers.

The format of numbers

Should numbers be one-based or zero-based? One-based seems less nerdy, but there is another question. Should line numbers be local or global?

At present, all numbers are global. Headline numbers are unique within the entire outline. But the (non-existent) number-headlines-locally or number-child-headlines-locally commands could create numbers relative to c.p. Alas, both these commands seem clumsy for various reasons. Details omitted.

Problems with clones

Clones appear in multiple places in an outline, but all clones have the same headline. Therefore the headline number for clones will be incorrect in some positions. This problem has no perfect solution.

Leo could associate headline numbers with positions instead of vnodes. Details omitted. I'm not going to consider such an heroic solution.

The numbering commands must use either the first or last number for all clones. But neither choice will be entirely satisfactory.

Headline numbers in @<file> trees

These commands must avoid numbering @<file> and section definitions nodes. The present code can mistakenly number section definition nodes. Avoiding this mistake is non-trivial.

Summary

I'm not sure that a fixed set of outline-numbering commands can overcome all these problems. Perhaps Leo should provide only the promised undo/redo routines for headlines. Otoh, the PR seems like a reasonable compromise.

Please let me know your thoughts.

Edward

[Thomas Passin]

On Tuesday, March 28, 2023 at 9:08:01 AM UTC-4 Edward K. Ream wrote:

PR #3227 contains a draft implementation of issue #3121: headline numbers.

While working on this PR, several problems became apparent. This Engineering Notebook post will discuss my present thoughts. I encourage all comments.

Undo/Redo

My first thought was that undo/redo is not necessary. For example, delete-all-headline-numbers will undo add-all-headline numbers. And in fact, the PR passes this round-trip test.

But my first thought was wrong:

- It's easier to type Ctrl-Z than to invoke the command that would undo the previous command.

- Undo/Redo methods for headlines will be valuable all by themselves.

- These undo/redo methods won't depend on how the headlines change.

Happily, Félix has volunteered to add these undo/redo methods.

The following sections discuss several nasty problems with headline numbers.

The format of numbers

Should numbers be one-based or zero-based? One-based seems less nerdy, but there is another question. Should line numbers be local or global?

1-based!  And local to the selected subtree.  Anything else would be disastrously confusing.

People like different formats for outline numbers.  Maybe there could be a setting to select one of a small number of possibilities (it's not worth it to implement an fprint-style formatting  scheme, IMHO).

 

At present, all numbers are global. Headline numbers are unique within the entire outline. But the (non-existent) number-headlines-locally or number-child-headlines-locally commands could create numbers relative to c.p. Alas, both these commands seem clumsy for various reasons. Details omitted.

Problems with clones

Clones appear in multiple places in an outline, but all clones have the same headline. Therefore the headline number for clones will be incorrect in some positions. This problem has no perfect solution.

A headline-user is just going to have to know this and adapt to it, I would say.

 

Leo could associate headline numbers with positions instead of vnodes. Details omitted. I'm not going to consider such an heroic solution.

Hmm, maybe the headline string could become a property instead of an attribute.  The property code could figure out what to do when a node has clones.  Not that I know what should be done!  But the question of what to do when a node is relocated is a real one, even if no clones are involved.  Even if it is possible to re-run the numbering command, it's not very feasible.  Besides, any references to the headline number, for example it it's some kind of documentation, well be obsoleted when  a node gets moved.

This makes me think that the original requester has not thought out his use cases very carefully.  Maybe a better solution would be for the commands to become scripts which a user could install in the @settings tree of an outline if he planned to use numbering in it.

 

The numbering commands must use either the first or last number for all clones. But neither choice will be entirely satisfactory.

Headline numbers in @<file> trees

These commands must avoid numbering @<file> and section definitions nodes. The present code can mistakenly number section definition nodes. Avoiding this mistake is non-trivial.

There is a kind of proof-of-concept in the line numbering plugin that displays absolute line numbers in the gutter.  I've used this but it seemed to be a little off from time to time.  A difficult task!

 

[Edward K. Ream]

On Tue, Mar 28, 2023 at 8:54 AM Thomas Passin <tbp1...@gmail.com> wrote:

Thanks for your comments, Thomas.  I think we are pretty much saying the same things. Here are few clarifications...

Should numbers be one-based or zero-based? One-based seems less nerdy, but there is another question. Should line numbers be local or global?

1-based!  And local to the selected subtree.  Anything else would be disastrously confusing.

I pretty much agree. There are some edge cases that might benefit from starting with zero, but I'd rather not discuss the details.

 

People like different formats for outline numbers.  Maybe there could be a setting to select one of a small number of possibilities (it's not worth it to implement an fprint-style formatting  scheme, IMHO).

Let's leave this for (much) later. Getting the simplest numbering to work will be complicated enough.

Clones appear in multiple places in an outline, but all clones have the same headline. Therefore the headline number for clones will be incorrect in some positions. This problem has no perfect solution.

A headline-user is just going to have to know this and adapt to it, I would say.

I agree. The (heroic) alternative is to let Leo's drawing code add numbers on the fly. This makes headline numbers extrinsic. Let's not go there.

Hmm, maybe the headline string could become a property instead of an attribute.  The property code could figure out what to do when a node has clones. 

Yes, it can be done by analogy with how Leo can expand some positions without expanding cloned positions. Again, there is no real point in considering this now.

This makes me think that the original requester has not thought out his use cases very carefully.  Maybe a better solution would be for the commands to become scripts which a user could install in the @settings tree of an outline if he planned to use numbering in it.

I said much the same thing in the summary. But I would like to hear other comments before choosing what to do next.

Edward

[Edward K. Ream]

On Tuesday, March 28, 2023 at 8:08:01 AM UTC-5 Edward K. Ream wrote:

PR #3227 contains a draft implementation of issue #3121: headline numbers.

While working on this PR, several problems became apparent. This Engineering Notebook post will discuss my present thoughts. I encourage all comments.

My concerns are less important than I thought. The OP proposed only two commands, which the PR calls hn-add-subtree and hn-delete-subtree. Clones should not a big problem for the hn-add-subtree command. The user can simply avoid duplicate clones in the subtree.

In short, these commands are valuable. I'll merge the PR as soon as it is ready.

Edward