Re: [Docutils-users] rst2html5 title demotion?

[Alan G. I. <ala...@gm...>]

> Alan wrote: 
>> I already pointed out that it means that combining two
>> documents (e.g., with an `include`) that have compatible
>> header notation and individually format perfect produces
>> a broken combined document.


On 5/25/2021 9:25 AM, Guenter Milde via Docutils-users wrote:
> Producing broken documents is bad, so I would like to improve the situation.
> Could you provide a minimal working (rsp. breaking) example and specify what
> you would expect and what is broken, please?


I may have miscommunicated here.
By using the `--initial-header-level` option,
I was able to fix things for my use.

Nevertheless, here is an example of what broke.
I have documents (call them chapters), where the
top level section header is the chapter title.
Each of these has a single top-level header.
These format perfectly, individually.

Sometimes I combine these into a single document.
Under the new defaults, since there are multiple
top-level sections, the combined document does not
maintain the desired formatting.

I understand the point you made about the double use of
the h1 element in previous writers. However, I
always understood (misunderstood?) this as an
effort to provide access to a document-level title
while still providing access to *all* of the header
elements within a document. This seemed useful, since
some documents have many levels. Nevertheless, I
typically turned it off with the `--no-doc-title` option.

Finally, to your core concern: sectioning.
My preferred solution would allow multiple h1 elements
*outside* of section elements, thus conforming to the idea that
header depth should conform to section depth.
Note that the standard has the concept of implicit sections,
but `body` is also considered an explicit section.
(That's my non-expert understanding.)
The explicit body section can contain multiple h1 elements.

I see that there is some debate about whether a document *should*
contain multiple h1 elements, but there does not seem to be any debate
that a document *should not* skip levels. Demotion of the top
level header to h2 therefore seems to me to be clearly forbidden
while multiple h1 elements does not.

Again, I simply share my non-expert opinion and experience.
As I said, I have a solution that is working for me.
And again, thank you for all your work on this!

Alan