Re: rst2html5 title demotion?
Guenter Milde via Docutils-users <[email protected]> Tue, 25 May 2021 13:25:20 -0000 (UTC)
| Newsgroups | gmane.text.docutils.user |
|---|---|
| Message-ID | <[email protected]> |
Dear Alan,
On 2021-05-24, Alan G. Isaac wrote:
> I am not going to drag out this discussion, but I must make one
> last appeal to revert the default behavior.
I am actually glad you don't give up easily, as this makes me think again
about the document structure and design and hopefully helps to improve
implementation and documentation.
There are, however, still open questions regarding the core of your problem
with the current behaviour and I currently come to different conclusions, so
please bear with me.
> Changing the meaning of a section header because it occurs
> a second time seems to me to be fundamentally broken behavior.
> So I must ask: how much consultation did you do on this?
> E.g., Did David agree that this is good behavior?
Changing the meaning of a section header when it occures just one time is
actually the standard behaviour of rST laid down by David in the
reStructuredText Markup Specification.
https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#document
This means that with the default settings, the input ::
Document Title
--------------
This is the content.
generates a document without sections (here rendered as Docutils XML) ::
<document ids="document-title" names="document\ title"
source="/tmp/titles.rst" title="Document Title">
<title>Document Title</title>
<paragraph>This is the content.</paragraph>
</document>
OTOH, changing the the input to ::
1st Section Title
-----------------
Content of section 1
2nd Section Title
-----------------
Content of section 2
leads to a document with two sections but no document title ::
<document source="/tmp/titles.rst">
<section ids="st-section-title" names="1st\ section\ title">
<title>
1st Section Title
<paragraph>
Content of section 1
<section ids="nd-section-title" names="2nd\ section\ title">
<title>
2nd Section Title
<paragraph>
Content of section 2
Of course, this also holds, if the 2nd section is from a different file
and included after the 1st section.
"html4css1" has a special feature: it uses a <h1> tag for both, document
title and 1st-level section titles.
https://docutils.sourceforge.io/FAQ.html#unexpected-results-from-tools-rst2html-py-h1-h1-instead-of-h1-h2-why
> 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.
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?
> Also, this decision seems out of step with the current
> understanding of HTML document structure.
The changing of the default `initial_header_level`__ setting for HTML5
was triggered by a rendering problem observed in Firefox, Chromium and
Opera after the mapping of Docutils "section" nodes from
<div class="section"> to <section>. I consulted the `MDN Web Docs`__ as
well as the `HTML Specifications`__ before settling on this change.
__ https://docutils.sourceforge.io/docs/user/config.html#initial-header-level
__ https://developer.mozilla.org/en-US/docs/Web/HTML/Element/Heading_Elements
__ https://developer.mozilla.org/en-US/docs/Web/HTML/Element/Heading_Elements#specifications
The most current `"living standard"`__ says:
Sections may contain headings of any rank, but authors are strongly
encouraged to either use only h1 elements, or to use elements of the
appropriate rank for the section's nesting level.
__ https://html.spec.whatwg.org/multipage/sections.html#headings-and-sections
The "html5" writer does the latter, using:
<body> h1
<section> h2
<section> h3
... ...
also, if the document heading is missing because the top-level section is
nevertheless nested inside the <body> of the document.
In my understanding, this provides a good match of Docutils document
structure to HTML5.
However, I agree that HTML document structure (especially the understanding
of a section's "nesting level") is a complex issue, , and I may have missed
something.
> For example, consider:
> https://www.impactplus.com/blog/multiple-h1-headlines-okay
This post starts quoting Webmaster Trends Analyst John Mueller
[...] it makes no difference to Google whether you use no H1 tags or 100.
which endorses both, the "html4css1" way of re-using <h1> for document title
and section title as well as "html5"s way of skipping <h1> if there is no
document title.
The section about screen readers states
Whether you decide it's better to use no H1s or several, consider if it
will have an impact on someone who uses a screen reader for
accessibility.
and the summary says
Although multiple top-level headings won't hurt your Google rankings,
it may be preferable to stick to maintaining only one H1 per page until
more information is available on the topic.
> https://webdesign.tutsplus.com/articles/the-truth-about-multiple-h1-tags-in-the-html5-era--webdesign-16824
This article is interesting to read (although a bit dated). It states
that "it is perfectly fine to use as many <h1> tags as your document
calls for; that is one per sectioning root or content section." but also
admits "It is permissible by the HTML5 spec to use lower level headings
than <h1> to label a section".
The "New <h1> Usage Rules" seem to contradict with the "living
standard"'s recommendation and handling in current browsers. They can be
reconciled using the caveat given at the end: "But if you do decide to
use a tag other than <h1> for a section label, just ensure you follow the
same rules as listed above, replacing <h1> in each rule with your chosen
tag."
The example problem given there is a page containing several independent
"articles". Docutils currently does not offer a way to distinguish
independent "articles" from interrelated "sections" inside one rST
document.
> Thus I again urge reverting this change.
Just reverting to ``initial_header_level == 1`` would require another
solution to the rendering problems in current browsers. Alternatives include
"not using <section> elements" and "styling every heading level in the
mandatory CSS style-sheet" which I am open to discuss.
Thank you for the feedback,
Günter
_______________________________________________
Docutils-users mailing list
[email protected]
https://lists.sourceforge.net/lists/listinfo/docutils-users
Please use "Reply All" to reply to the list.