Document implicit section behavior
chrisjsewell opened this issue · 7 comments
When you create a heading, it nests all other content in a section
# Heading
Paragraph
## Heading 2doc
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 2doc
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 2doc
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
You could always nest the section in a div?
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 🤔
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?
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?
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 🙏
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.
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.