Document implicit section behavior

[chrisjsewell]

When you create a heading, it nests all other content in a section

# Heading

Paragraph

## Heading 2

doc
  section id="Heading"
    heading level=1
      str text="Heading"
    para
      str text="Paragraph"
    section id="Heading-2"
      heading level=2
        str text="Heading 2"

However, for example, if a heading is nested, it turns off this nesting:

> # Heading

Paragraph

## Heading 2

doc
  block_quote
    heading level=1 id="Heading"
      str text="Heading"
  para
    str text="Paragraph"
  section id="Heading-2"
    heading level=2
      str text="Heading 2"

I was thinking that perhaps there should be some way to specify that a heading should not be a section?

Perhaps something like

{section=false}
# Heading

Paragraph

## Heading 2

doc
  heading level=1 id="Heading"
    str text="Heading"
  para
    str text="Paragraph"
  section id="Heading-2"
    heading level=2
      str text="Heading 2"

What do you think?

---

Note, I guess this has some read across to unnumbered in https://pandoc.org/MANUAL.html#extension-header_attributes

[jgm]

You could always nest the section in a div?

https://djot.net/playground/?text=%3A%3A%3A%0A%23+Heading%0A%0AParagraph%0A%3A%3A%3A%0A%0A%23%23+Heading+2%0A&mode=html&sourcepos=false

[chrisjsewell]

Yeh, but ughh, I feel that doesn't seem very readable or user friendly

In the example, its not clear why its in a div, and seems more like a "hack" than a feature 🤔

[chrisjsewell]

I guess its not the end of the world, if this is the "solution" 😬

But I do feel at least this aspect of the heading parsing should be better documented in https://htmlpreview.github.io/?https://github.com/jgm/djot/blob/master/doc/syntax.html#heading

I guess the logic is that headings add sections if they are a child of the doc or another section?

[jgm]

I guess the logic is that headings add sections if they are a child of the doc or another section?

Yes. Agreed that the "section" behavior should be documented.

As for ugliness, I think it's no more ugly that {section=false} (though perhaps less explicit as to its purpose, at least for people who know English).

What's the real-world case that is motivating this?

[chrisjsewell]

Yes. Agreed that the "section" behavior should be documented.

👍

As for ugliness, I think it's no more ugly that {section=false} (though perhaps less explicit as to its purpose, at least for people who know English).

No you are right actually, I should of never doubted you 😅

But yes documenting the section behaviour woulf be great thanks 🙏

[Omikhleia]

It's perhaps not only a documentation issue. To me, it might also lead to inconsistencies in interpretation, as attributes and ids are on the section node when present, not the header:

{ .red }
# Chap1

Lorem

{ .twocolumn }
:::
{ .blue }
# Chap2

Ipsum
:::

doc
  section class="red" id="Chap1"
    heading level=1
      str text="Chap1"
    para
      str text="Lorem"
    div class="twocolumn"
      heading level=1 class="blue" id="Chap2"
        str text="Chap2"
      para
        str text="Ipsum"

Which content is supposed to be "red", and "blue" ? The whole section (including all child nodes) or just the header? Where are links supposed to be applied (e.g. if chapters introduced a page break to start on an odd page in print), where the section starts or where the actual header ends up? Is the expected sectioning really respected in the above?

EDIT:

as attributes and ids are on the section node when present, not the header:

BTW if I am not mistaken, djot.lua (at least at one point) differs from djot.js / the online playground here - having the id on the section node, but not the other attributes.

[jgm]

This would be less confusing if there were just one AST element, Section, with a field for a title. Of course, this would be rendered in HTML as a <hN> element embedded in a <section>. But then, it would be clearer conceptually why all the attributes go on the section, and it is impossible to put them on the heading.

Which content is supposed to be "red", and "blue" ? The whole section (including all child nodes) or just the header?

In HTML output at least, you can choose by using appropriate CSS rules.

[bitfehler]

Sorry in case this is not entirely the right place for this question, but I found this issue trying to figure out the intended behavior of block attributes added to headings. Now, the last comment says (emphasis mine):

But then, it would be clearer conceptually why all the attributes go on the section, and it is impossible to put them on the heading.

This seems to be the answer I was looking for, but I initially played with the playground, and was a little surprised by this example:

doc
  section
    heading level=1 foo="bar"
      str text="heading"
    para
      str text="text"

Somewhat unexpectedly, all attributes are assigned to the section instead if, and only if, one of them is an id.

Is that an implementation issue? Is it possible to describe the intended behavior in a sentence or two? I am not so much interested in the workarounds, but curious about the consistency here, like "if a heading generates a section, all attributes should be assigned to the section"? Thanks for Djot btw, and thanks in advance for any guidance :slightly_smiling_face: