Is the cascading logic of outlines a feature, or a design bug?

Is the cascading logic of outlines a feature, or a design bug?

[abq]

https://orgmode.org/worg/org-faq.html#closing-outline-sections answers 
the question:
"Can I close an outline section without starting a new section?"

The answer given is:
"no. Org-mode adheres to the cascading logic of outlines, in which a 
section is closed only by another section that occupies an equal or 
greater level."

Is that limitation a feature, or a design bug? E.g. if someone proposes 
enhancing the Unix directory system to support multiple files with the 
same filename in one directory, the proposal would be rejected, with the 
explanation that the limitation of only one file per filename is a 
feature, not a bug, since it enables the name to uniquely identify the 
file. (If you want to claim it's a bug, please at least edit your 
subject line, or preferably start a new thread.)

Likewise, is the inability to close an org-mode outline section without 
starting a new section really a feature? If so, what benefit does the 
restriction provide, that would be lost by relaxing the restriction? Or 
is the restriction really just a bug with seniority, and the difficulty 
of fixing it (or the compatibility headaches caused by fixing it) would 
outweigh the benefits?

Andy

Re: Is the cascading logic of outlines a feature, or a design bug?

[tomas]

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

On Mon, Dec 26, 2022 at 06:47:37AM +0000, abq@bitrot.link wrote:

> Likewise, is the inability to close an org-mode outline section without
> starting a new section really a feature? [...] Or is
> the restriction really just a bug with seniority, and the difficulty of
> fixing it (or the compatibility headaches caused by fixing it) would
> outweigh the benefits?

I guess the answer depends on your perspective. Try to reformulate
your question in another way, perhaps then it leads to something.

I must admit I've missed the possibility for Org to continue a
section after a deeper level one from time to time. I've resorted
to "local conventions" (e.g. a headline with "-" as a title).

But all in all, that's what Org's document model is, and you won't
change it because it's (sometimes) more convenient to you. What
you might try is to find enough people to agree in a common way
to work around it, if necessary.

Cheers
-- 
t

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 195 bytes --]

Re: Is the cascading logic of outlines a feature, or a design bug?

[Ihor Radchenko]

abq@bitrot.link writes:

> https://orgmode.org/worg/org-faq.html#closing-outline-sections answers 
> the question:
> "Can I close an outline section without starting a new section?"
>
> The answer given is:
> "no. Org-mode adheres to the cascading logic of outlines, in which a 
> section is closed only by another section that occupies an equal or 
> greater level."
>
> Is that limitation a feature, or a design bug?

A "bug" implies that it is something wrong.
Could you please elaborate?

> Likewise, is the inability to close an org-mode outline section without 
> starting a new section really a feature?

It is not a bug. It is not a feature. Just a design decision. With pros
and cons. Doing the opposite would also have pros and cons.

I suggest you to elaborate about what exact properties of outlines you
are missing.

-- 
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: Is the cascading logic of outlines a feature, or a design bug?

[Max Nikulin]

On 26/12/2022 13:47, abq@bitrot.link wrote:
> https://orgmode.org/worg/org-faq.html#closing-outline-sections answers 
> The answer given is:
> "no. Org-mode adheres to the cascading logic of outlines, in which a 
> section is closed only by another section that occupies an equal or 
> greater level."

> Is that limitation a feature, or a design bug?

You may guess that this item appeared in FAQ after numerous discussions 
on this mailing list. Search its archive for details.

The most close feature is inline tasks, there are other structures like 
#+begin_something/#+end_something blocks and :drawer:...:end: that have 
closing marker.

Some Org syntax limitations are imposed to be able efficiently determine 
current context using regexp searches. So "** Heading" lines must be 
escaped in comments, nested identical #+begin_block structures are not 
allowed. Another point is treating Org files with syntax errors.

Re: Is the cascading logic of outlines a feature, or a design bug?

[abq]

On 2022-12-26 12:38, Max Nikulin wrote:
> You may guess that this item appeared in FAQ after numerous
> discussions on this mailing list. Search its archive for details.
> 
> The most close feature is inline tasks, there are other structures
> like #+begin_something/#+end_something blocks and :drawer:...:end:
> that have closing marker.
> 
> Some Org syntax limitations are imposed to be able efficiently
> determine current context using regexp searches. So "** Heading" lines
> must be escaped in comments, nested identical #+begin_block structures
> are not allowed. Another point is treating Org files with syntax
> errors.

When I searched prior to posting, the only info I could find was how to 
work around the restriction. But my question isn't how to work around 
it; my question is, what is its purpose?

It doesn't affect regexp search efficiency.

Re: Is the cascading logic of outlines a feature, or a design bug?

[abq]

On 2022-12-26 10:12, Ihor Radchenko wrote:
> It is not a bug. It is not a feature. Just a design decision. With pros
> and cons. Doing the opposite would also have pros and cons.
> 
> I suggest you to elaborate about what exact properties of outlines you
> are missing.

OK, a design tradeoff was made, with a cost and a benefit.

The cost was the restriction at hand. Its mention in the FAQ is 
indication that it does actually affect people. Tomas also just replied 
that it's sometimes an obstacle for him, which he needs to work around.

So, that addresses the cost. What was the benefit?

Re: Is the cascading logic of outlines a feature, or a design bug?

[tomas]

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

On Mon, Dec 26, 2022 at 05:23:45PM +0000, abq@bitrot.link wrote:

[...]

> So, that addresses the cost. What was the benefit?

I think it's more elucidating to view that in terms of
(technical) path dependency [1]: Org inherits from Outline,
which doesn't think in terms of (recursive) sections
(as would, e.g. XML) but in terms of headlines. Sections
came as a secondary concept (whatever is "below" a headline).

Changing the model in-flight seems prohibitive at this
stage, with all the accumulated wetware.

Cheers

[1] sometimes called "hysterical raisins" around here

-- 
t

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 195 bytes --]

Re: Is the cascading logic of outlines a feature, or a design bug?

[Ihor Radchenko]

abq@bitrot.link writes:

> So, that addresses the cost. What was the benefit?

For example, export. Things like LaTeX or Markdown or ODT do not support
document section continuation.

-- 
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: Is the cascading logic of outlines a feature, or a design bug?

[tomas]

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

On Mon, Dec 26, 2022 at 05:36:06PM +0000, Ihor Radchenko wrote:
> abq@bitrot.link writes:
> 
> > So, that addresses the cost. What was the benefit?
> 
> For example, export. Things like LaTeX or Markdown or ODT do not support
> document section continuation.

Here's the LaTeX perspective, which perhaps illustrates that "print",
our grandmother, didn't necessarily think hierarchically:

  https://tex.stackexchange.com/questions/174651/latex-end-section-or-subsection

(Spoiler: LaTeX does as print and Org, as Ihor says -- and different
to XML).

At first it seems surprising that there are those two perspectives
and there's no "right" or "wrong", as the OP seems to assume.

Cheers
-- 
t

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 195 bytes --]

Re: Is the cascading logic of outlines a feature, or a design bug?

[Marcin Borkowski]

On 2022-12-26, at 19:37, tomas@tuxteam.de wrote:

> On Mon, Dec 26, 2022 at 05:36:06PM +0000, Ihor Radchenko wrote:
>> abq@bitrot.link writes:
>>
>> > So, that addresses the cost. What was the benefit?
>>
>> For example, export. Things like LaTeX or Markdown or ODT do not support
>> document section continuation.

Markdown being a very poor example, since it is basically a format for
first drafts (and it's bad even at that).

>
> Here's the LaTeX perspective, which perhaps illustrates that "print",
> our grandmother, didn't necessarily think hierarchically:
>
>   https://tex.stackexchange.com/questions/174651/latex-end-section-or-subsection
>
> (Spoiler: LaTeX does as print and Org, as Ihor says -- and different
> to XML).
>
> At first it seems surprising that there are those two perspectives
> and there's no "right" or "wrong", as the OP seems to assume.

FWIW, I think LaTeX also got this "wrong" (and perhaps surprisingly, XML
"right";-)).  AFAIR, ConTeXt (which I haven't used for several years, so
I might be mistaken) does "TRT" here.

OTOH, I agree that it looks surprising, and we mathematicians (and CS/IT
people) would like to have a nice, tree-like structure, but I suspect
that not allowing to continue the parent section after the subsection
ends is a wise decision.  I highly suspect this would be very confusing
for 99% people, which might be precisely the benefit the OP is asking
about.

Just my 2 cents,

-- 
Marcin Borkowski
http://mbork.pl

Re: Is the cascading logic of outlines a feature, or a design bug?

[tomas]

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

On Tue, Dec 27, 2022 at 08:21:28AM +0100, Marcin Borkowski wrote:

[...]

> > At first it seems surprising that there are those two perspectives
> > and there's no "right" or "wrong", as the OP seems to assume.
> 
> FWIW, I think LaTeX also got this "wrong" (and perhaps surprisingly, XML
> "right";-)).  AFAIR, ConTeXt (which I haven't used for several years, so
> I might be mistaken) does "TRT" here.

LaTeX picked it up from TeX which picked it up from... print (more
specifically from academic print). Which has been optimised for a
couple o'hundred years.

Donald Knuth was mathematician and computer scientist (and pretty
fastidious with the smalles details), so I'd assume his choice of
this "flavour" of document model for TeX was pretty conscious, not
an accident.

> OTOH, I agree that it looks surprising, and we mathematicians (and CS/IT
> people) would like to have a nice, tree-like structure, but I suspect
> that not allowing to continue the parent section after the subsection
> ends is a wise decision.  I highly suspect this would be very confusing
> for 99% people, which might be precisely the benefit the OP is asking
> about.

You might not like it -- but I stay by my assessment that there isn't
a "right" or "wrong" here.

The most important thing, IMHO, is to be aware of those two models
(most of us stumble unexpectedly into it and go "WAT?" -- although
it has made it to the FAQ by now :)

It isn't difficult to model the one with the other. I already proposed
having one canonical heading meaning "back to that level", say dash
or dot, like so:

  * General animals
    Some text about general animals

  ** arthropods
     spiders and things

  * -
    More about animals in general

  ** vertebrates
     so-and-so

(You could even do with the space alone, but playing with significant
trailing spaces is asking for trouble: i'd go for some unobtrusive char
unlikely to be a heading text for itself).

Now for that to be useful, you'd have to gather enough users who
like the idea and use the convention. It's a communication medium,
after all :-)

Cheers
-- 
t

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 195 bytes --]

Re: Is the cascading logic of outlines a feature, or a design bug?

[Max Nikulin]

On 27/12/2022 00:03, abq@bitrot.link wrote:
> When I searched prior to posting, the only info I could find was how to 
> work around the restriction. But my question isn't how to work around 
> it; my question is, what is its purpose?

I have an impression that I saw messages explaining that the real 
problem is to implement the feature consistently and to avoid too much 
code for handling it in various functions. I do not have specific links. 
Reading such discussion I would pay more attention to messages from 
Carsten, Bastien, Nicolas.

> It doesn't affect regexp search efficiency.

Regexps would be more complex, sometimes several iterations would be 
required. You may underestimate amount of code that should be adapted 
for this feature.

In general, I do not mind to have such feature e.g. to have an overview 
headings with comments between deep dive notes. However if I desperately 
need it, I will write a custom unfolding function (for tagged 
subheadings or for drawers). I am unsure that benefits outweigh 
additional complexity and performance penalty.

This topic belongs to a several feature requests that pop up regularly 
and fade with almost no outcome (intra-word emphasis, merged cells in 
tables).

Re: Is the cascading logic of outlines a feature, or a design bug?

[Samuel Wales]

inline tasks are arguably a limited implementation of the other model
and have had issues where they didn't work well with one feature or
another of org, so much so that i got into the habit of not using
them.  thus, modulo parsers, inline tasks might be used as a very
rough lower bound of the havoc a full implementation might wreak,
including on 3rd party tools and user code?  dunno.  just an idea.


On 12/27/22, Max Nikulin <manikulin@gmail.com> wrote:
> On 27/12/2022 00:03, abq@bitrot.link wrote:
>> When I searched prior to posting, the only info I could find was how to
>> work around the restriction. But my question isn't how to work around
>> it; my question is, what is its purpose?
>
> I have an impression that I saw messages explaining that the real
> problem is to implement the feature consistently and to avoid too much
> code for handling it in various functions. I do not have specific links.
> Reading such discussion I would pay more attention to messages from
> Carsten, Bastien, Nicolas.
>
>> It doesn't affect regexp search efficiency.
>
> Regexps would be more complex, sometimes several iterations would be
> required. You may underestimate amount of code that should be adapted
> for this feature.
>
> In general, I do not mind to have such feature e.g. to have an overview
> headings with comments between deep dive notes. However if I desperately
> need it, I will write a custom unfolding function (for tagged
> subheadings or for drawers). I am unsure that benefits outweigh
> additional complexity and performance penalty.
>
> This topic belongs to a several feature requests that pop up regularly
> and fade with almost no outcome (intra-word emphasis, merged cells in
> tables).
>
>


-- 
The Kafka Pandemic

A blog about science, health, human rights, and misopathy:
https://thekafkapandemic.blogspot.com

Re: Is the cascading logic of outlines a feature, or a design bug?

[Marcin Borkowski]

On 2022-12-27, at 10:00, tomas@tuxteam.de wrote:

> On Tue, Dec 27, 2022 at 08:21:28AM +0100, Marcin Borkowski wrote:
>
> [...]
>
>> > At first it seems surprising that there are those two perspectives
>> > and there's no "right" or "wrong", as the OP seems to assume.
>>
>> FWIW, I think LaTeX also got this "wrong" (and perhaps surprisingly, XML
>> "right";-)).  AFAIR, ConTeXt (which I haven't used for several years, so
>> I might be mistaken) does "TRT" here.
>
> LaTeX picked it up from TeX which picked it up from... print (more

Hm.  It's been decades since I used plain TeX on a daily basis, so
I don't remember exactly, but it seems to me that plain TeX doesn't even
have sectioning macros...

> specifically from academic print). Which has been optimised for a
> couple o'hundred years.

Well, yes, though one might argue that it's only a local optimum;-).

> Donald Knuth was mathematician and computer scientist (and pretty
> fastidious with the smalles details), so I'd assume his choice of
> this "flavour" of document model for TeX was pretty conscious, not
> an accident.

Actually, this is much stronger argument than it might seem.

>> OTOH, I agree that it looks surprising, and we mathematicians (and CS/IT
>> people) would like to have a nice, tree-like structure, but I suspect
>> that not allowing to continue the parent section after the subsection
>> ends is a wise decision.  I highly suspect this would be very confusing
>> for 99% people, which might be precisely the benefit the OP is asking
>> about.
>
> You might not like it -- but I stay by my assessment that there isn't
> a "right" or "wrong" here.

Well, I was a bit tongue-in-cheek here - I meant "right" in the
mathematician/computer scientist mind, which is, let's say, a very
peculiar type of mind...

> The most important thing, IMHO, is to be aware of those two models
> (most of us stumble unexpectedly into it and go "WAT?" -- although
> it has made it to the FAQ by now :)
>
> It isn't difficult to model the one with the other. I already proposed
> having one canonical heading meaning "back to that level", say dash
> or dot, like so:
>
>   * General animals
>     Some text about general animals
>
>   ** arthropods
>      spiders and things
>
>   * -
>     More about animals in general
>
>   ** vertebrates
>      so-and-so
>
> (You could even do with the space alone, but playing with significant
> trailing spaces is asking for trouble: i'd go for some unobtrusive char
> unlikely to be a heading text for itself).

+1 for avoiding significant trailing spaces, and agreed.

> Now for that to be useful, you'd have to gather enough users who
> like the idea and use the convention. It's a communication medium,
> after all :-)

Fair point.  And frankly, I find this unlikely to happen.  As I said,
for me the main argument against "continuation sections" is that they
would probably be /extremely/ confusing to most readers.

Best,

-- 
Marcin Borkowski
http://mbork.pl

Re: Is the cascading logic of outlines a feature, or a design bug?

[Stefan Nobis]

abq@bitrot.link writes:

> Likewise, is the inability to close an org-mode outline section
> without starting a new section really a feature?

I think so. :)

First, technically, it makes the sections (and their contents) a tree
instead of a graph (DAG) and trees are easier to understand and
handle. As sections are a quite essential and important data structure
of Org, it usually means that it would be hard to change it (meaning
that it could affect a really big part of the code base).

Another rather technical point is, that most export formats like HTML
and LaTeX/PDF are also tree like structures (regarding sections).
Therefore it is quite a challenge to export a DAG like structure to
these formats.

But also semantically I would say it is a feature. Have you ever seen
a book, longer web page, or even article (with multiple sections) that
tries to close one section and continue any previous sibling or its
parent? I have never seen such kind of textual structuring and my
guess is, that this would be hard for a reader to understand and
follow. If the intermediate text is small, just make it a list (maybe
a description list). If a new (sub-)section seems a good idea, then
structure everything accordingly and tree-like. For example:

--8<---------------cut here---------------start------------->8---

    * Topic
    Some initial words.
    ** Subtopic 1
    More text.
    ** Subtopic 2
    Another paragraph.
    ** Other Aspects
    There may be more to say.

--8<---------------cut here---------------end--------------->8---

IMHO there is always a way to structure sections, such that a tree
like structure suffices. And IMHO this is easier to read an follow.

If you try to use Org for other kinds of data and this data is
naturally structured like a DAG (or even a cyclic graph), then I think
a database or other means are better suited than Org.

-- 
Until the next mail...,
Stefan.

Re: Is the cascading logic of outlines a feature, or a design bug?

[Samuel Wales]

stefan's example reminded me that there is another common request,
with :noexportheading kludges, in which you do not export a headline
itself.  you could try one of those perhaps.

that assumes you want this for export and not for the .org.

On 12/28/22, Stefan Nobis <stefan-ml@snobis.de> wrote:
> abq@bitrot.link writes:
>
>> Likewise, is the inability to close an org-mode outline section
>> without starting a new section really a feature?
>
> I think so. :)
>
> First, technically, it makes the sections (and their contents) a tree
> instead of a graph (DAG) and trees are easier to understand and
> handle. As sections are a quite essential and important data structure
> of Org, it usually means that it would be hard to change it (meaning
> that it could affect a really big part of the code base).
>
> Another rather technical point is, that most export formats like HTML
> and LaTeX/PDF are also tree like structures (regarding sections).
> Therefore it is quite a challenge to export a DAG like structure to
> these formats.
>
> But also semantically I would say it is a feature. Have you ever seen
> a book, longer web page, or even article (with multiple sections) that
> tries to close one section and continue any previous sibling or its
> parent? I have never seen such kind of textual structuring and my
> guess is, that this would be hard for a reader to understand and
> follow. If the intermediate text is small, just make it a list (maybe
> a description list). If a new (sub-)section seems a good idea, then
> structure everything accordingly and tree-like. For example:
>
> --8<---------------cut here---------------start------------->8---
>
>     * Topic
>     Some initial words.
>     ** Subtopic 1
>     More text.
>     ** Subtopic 2
>     Another paragraph.
>     ** Other Aspects
>     There may be more to say.
>
> --8<---------------cut here---------------end--------------->8---
>
> IMHO there is always a way to structure sections, such that a tree
> like structure suffices. And IMHO this is easier to read an follow.
>
> If you try to use Org for other kinds of data and this data is
> naturally structured like a DAG (or even a cyclic graph), then I think
> a database or other means are better suited than Org.
>
> --
> Until the next mail...,
> Stefan.
>
>


-- 
The Kafka Pandemic

A blog about science, health, human rights, and misopathy:
https://thekafkapandemic.blogspot.com

Re: Is the cascading logic of outlines a feature, or a design bug?

[Heinz Tuechler]

>> Donald Knuth was mathematician and computer scientist ...
According to https://en.wikipedia.org/wiki/Donald_Knuth, Donald Knuth is
still alive. So maybe "Donald Knuth *is* mathematician ..."
best regards,
Heinz

Re: Is the cascading logic of outlines a feature, or a design bug?

[Greg Minshall]

Stefan,

i am agnostic about this.  but, ...

> But also semantically I would say it is a feature. Have you ever seen
> a book, longer web page, or even article (with multiple sections) that
> tries to close one section and continue any previous sibling or its
> parent?

one sometimes see "sub-sections" indented from the main flow.  at the
end of the sub-section, the indentation reverts to that of the main
flow.  in the case of one level, this works fairly well (the case where
the end of the sub-section corresponds to the end of a "physical" page
is one place it works less well).

also, one *could* consider "boxes" (e.g., in textbooks) something like
this, though they tend to exist outside the main flow.

cheers, Greg

Re: Is the cascading logic of outlines a feature, or a design bug?

[Ihor Radchenko]

Greg Minshall <minshall@umich.edu> writes:

>> But also semantically I would say it is a feature. Have you ever seen
>> a book, longer web page, or even article (with multiple sections) that
>> tries to close one section and continue any previous sibling or its
>> parent?
>
> one sometimes see "sub-sections" indented from the main flow.  at the
> end of the sub-section, the indentation reverts to that of the main
> flow.  in the case of one level, this works fairly well (the case where
> the end of the sub-section corresponds to the end of a "physical" page
> is one place it works less well).
>
> also, one *could* consider "boxes" (e.g., in textbooks) something like
> this, though they tend to exist outside the main flow.

That's better reflected by inlinetasks. Any kind of long text being
indented or boxed will not be readable. Nesting is also questionable.

-- 
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: Is the cascading logic of outlines a feature, or a design bug?

[tomas]

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

On Wed, Dec 28, 2022 at 08:28:58AM +0100, Heinz Tuechler wrote:
> > > Donald Knuth was mathematician and computer scientist ...
> According to https://en.wikipedia.org/wiki/Donald_Knuth, Donald Knuth is
> still alive. So maybe "Donald Knuth *is* mathematician ..."
> best regards,

Very much true. Chalk that up to *my* old age ;-)

Cheers
-- 
t

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 195 bytes --]

Re: Is the cascading logic of outlines a feature, or a design bug?

[Greg Minshall]

Ihor,

> That's better reflected by inlinetasks. 

inlinetasks?  that's new for me.  i see some mention in the manual.
but, the comments in source code is more helpful.

yes, i see what you mean.  for boxes, that would make sense.

> Any kind of long text being indented or boxed will not be
> readable. 

for a (possibly context-specific) suitable definition of "long", that
seems correct (though, for someone *else's* text, it's a value judgement
that i, personally, wouldn't like to make :).

> Nesting is also questionable.

quite likely.

cheers, Greg

Re: Is the cascading logic of outlines a feature, or a design bug?

[tomas]

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

On Wed, Dec 28, 2022 at 08:14:26AM +0100, Stefan Nobis wrote:
> abq@bitrot.link writes:
> 
> > Likewise, is the inability to close an org-mode outline section
> > without starting a new section really a feature?
> 
> I think so. :)
> 
> First, technically, it makes the sections (and their contents) a tree
> instead of a graph [...]

No. XML is very much a tree yet has "that other" document model. The
difference is whether you allow a node to contain "mixed" (as the
XMLians call it) stuff (nodes and text, basically) or you allow
certain nodes to only have one text element at the very beginning
(Org). Actually, Org is more confusing than that, because inline
markup, blocks and all that /are/ allowed to mix with normal text.

Cheers
-- 
t

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 195 bytes --]