Menu
▾
▴
Re: [Docutils-users] rst2html5 title demotion?
|
From: Guenter M. <mi...@us...> - 2021-05-25 13:25:55
|
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 |
