Re: [Docutils-users] rst2html5 title demotion?

[Guenter M. <mi...@us...>]

Dear Alan,

On 2021-05-25, Alan G. Isaac wrote:
> On 5/25/2021 9:25 AM, Guenter Milde via Docutils-users wrote:

> ... 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 can reproduce. In the output of the combined file, section headings
look different from the output of the chapter files. However, this is
consistent for "html4", "html5", "latex", and "odf" and reflects the missing
document title in the combined document.

Setting the "initial-header-level" to 1 is a possible workaround in this
use-case.  However, it leads to bad formatting (with the browser default
styling for headings) when the combined document has a title::

  Collection of recent unpublished work
  *************************************

  .. include:: text1.txt
  .. include:: text2.txt


> 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. 

"Saving" elements for use with lower-level headings may have been
sensible with HTML4.1 but is no longer necessary with HTML5 and
<section> elements: here we have the possibility of infinite nesting and
can also use the ARIA "role" element to set a heading level.


> Nevertheless, I typically turned it off with the `--no-doc-title`
> option.

This results in documents without title also for the stand-alone chapters.
A missing document title may be OK for home-use but is generally not
recommended for published work. How would you cite the combined document?

This is, IMV, also the reason behind the obsolete search engine optimization
(SEO) rule "HTML documents must have exactly one <h1> element":   
One <h1> can be extracted as document title, more than one <h1> is
ambiguous (just as multiple top-level headings in rST source).

HTML5's outline algorithm allows to determine a document title also when
several <h1> elements are used, but this depends on document structure and
is not guaranteed to work for any document (see below).

> 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 share this understanding -- this would not violate the standard. However,
it would not align header rank to section depth: the <h1> elements start
implicit sub-sections (level 2). There is no heading in level 1 (i.e. no
document title).
 

> 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.

IMV, both are instances of a titleless document, valid but not ideal. 
Cf. the statement cited in
https://www.impactplus.com/blog/multiple-h1-headlines-okay: 

    it makes no difference to Google whether you use no H1 tags or 100.
    
See also the usage notes in
https://developer.mozilla.org/en-US/docs/Web/HTML/Element/Heading_Elements 


* Both cases are valid HTML documents (in HTML4 as well as in HTML5).
  
  If sections without heading work best for a special use case, fine.

* It is recommended not to skip levels and to have a heading in each section
  level.
  
  - With explicit sections, you cannot skip section levels but you can have
    sections without heading.

  - With implicit sections, you cannot have a section without heading but
    you can skip levels.
    (In HTML5, the <body> element is considered an explicit section
    and thus can be without heading).
    
  To handle the "hole" at level 1, you can either skip <h1> elements and
  keep heading rank and outline level in sync, or you can use <h1> for
  outline level 2 (top sections) and <h:math:`(n-1)`> for outline level
  math:`n`.  The "initial-header-level" setting allows to configure which
  "coping strategy" is used. The best fix is to provide a document title in
  the source.  

As Docutils is already generating explicit sections when converting the rST
source to a document tree, I prefer to follow the tip
in https://html.spec.whatwg.org/multipage/sections.html#headings-and-sections

  Authors are also encouraged to explicitly wrap sections in elements of
  sectioning content, instead of relying on the implicit sections generated
  by having multiple headings in one element of sectioning content.

and keep the current default behaviour.

Viele Grüße,
Günter