Re: [Docutils-users] Will new HTMLWriter change the H1, H1 issue?

SourceForge Headquarters 225 Broadway Suite 1600 San Diego, CA 92101 +1 (858) 422-6466

On 2015-05-16, Tony Narlock wrote:

> Regarding
> http://docutils.sourceforge.net/FAQ.html#unexpected-results-from-tools-rst2html-py-h1-h1-instead-of-h1-h2-why
> .

> I am using docutils trunk on a personal website that uses an ordinary css
> framework.  I am using the ``html-base`` writer.

> I have taken a look at the two workarounds:

>    1. If you don't want the top section heading to be interpreted as a
>    title at all, disable the doctitle_xform
>    <http://docutils.sourceforge.net/docs/user/config.html#doctitle-xform>
> setting
>    (--no-doc-title option). *This will interpret your document differently
>    from the standard settings, which might not be a good idea. *

>    2. If you don't like the reuse of the H1 in the HTML output, you can
>    tweak the initial_header_level
>    <http://docutils.sourceforge.net/docs/user/config.html#initial-header-level>
> setting
>    (--initial-header-level option) -- *but unless you match its value to
>    your specific document, you might end up with bad HTML (e.g. H3 without
>    H2).*

> Does the new HTMLWriter do anything to change this?

No. I assume this to be a design decision which was taken with careful
consideration by David and should not be changed without need.

> This is a pretty big deal, I guess it looks like I'm going to need to add
> custom CSS for h1.title, h1, h2, h3, h4, h5... because of this.

If you changed from a system/work-flow that uses h1 for title and h2+ for
section headings and don't want to use the "doctitle-xform" setting, yes.

OTOH, adding a pair of CSS rules does not seem a "big deal" to me.
Especially as Docutils HTML output requires some CSS rules in any case.

"doctitle-xform: False" might be another option -- if you happen to use
source documents with one as well as two top-level headings, this would
make the rendering more consistent. E.g.

  my-site/doc1.txt::

     Thema
     -----

     irgendwas

     Sub-Thema
     ~~~~~~~~~

  my-site/doc2.txt::

     Thema 1
     -------

     irgendwas

     Thema 2
     -------

     noch was.

  my-site/doc3.txt::

     Thema
     -----
     Untertitel
     ~~~~~~~~~~

     irgendwas

With the default settings, doc1 would be a document with title and one
top-level section, doc2 would be a document without title but with two
top-level sections, and doc2 would be a document with title, subtitle and no
sections at all.

¹ Beware: you will need to "manually" set the <title> in this case
  (either via the .. title:: directive, in a template, or in your custom
  Python wrapper).

> The two solutions given sound like hacks with big trade-offs

I'd interpret the caveats in the FAQ rather as minders to consider accepting
the default choice as sensible than as a pointer to a hackish nature of the
options.

> that don't justify bothering to pass those options through,

The easiest way to have consistent local configuration is a
project-specific configuration file, located in the current directory.
See docutils/docs/user/config.html#configuration-files

> but for the sake of asking:

>    1. If I am using docutils via the python API (not the front-end), how
>    could I pass ``inital_header_level`` and ``no-doc-title`` into
>    ``docutils.core.publish_parts``?

See the documentation and code of the publish* functions.
Also, see the examples in the test suite (test/test_functional/tests/*.py).

>    2. What is the internal issue that makes it difficult to give an option
>    to just render h1, h2, h3, h4, h5, h6?*

I suppose you mean: to convert top-level section titles to h1 if there is no
document title but to h2 if there is a document title and let the other
section titles follow suit?

I don't know whether it would be more difficult to implement than the
current behaviour.

This is a design decision taken long before I started working on
Docutils. I may have decided otherwise, but it does not itch me in a
manner that I am going to challenge it.

If I were to implement (or accept) this, then not as a new option but
rather as a special value (e.g. 0 or -1) for the "initial_header_level"
setting.

>    3. Does this happen in HTMLWriter?

Partially.

The doctitle transformation creates a document title out of "lonely" section
headings. This is before the writer kicks in. E.g., the doctree of the above
example looks like::

  <document ids="thema" names="thema" source="/tmp/doc1.txt" title="Thema">
      <title>
          Thema
      <paragraph>
          irgendwas
      <section ids="sub-thema" names="sub-thema">
          <title>
              Sub-Thema

This transform can be deactivated by the doctitle-xform setting,
resulting in::

  <document source="/tmp/doc1.txt">
      <section ids="thema" names="thema">
          <title>
              Thema
          <section ids="untertitel" names="untertitel">
              <title>
                  Untertitel
              <paragraph>
                  irgendwas
              <section ids="sub-thema" names="sub-thema">
                  <title>
                      Sub-Thema

The html writer converts the doctree into HTML. "title" nodes are processed
depending on the parent node. (see the visit_title() method of the html
writer(s)).

>    If so, how much work would it be to create a config option / python
>    interface to configure html element + class for each level?

This depends. In any case, it would be considerably more work
than adding a pair of CSS rules or using the existing options. And it
would interpret your document even more "differently from the standard
settings", so you gain nothing compared to "doctitle-xform: False".

> Here's an
>    example of how bootstrap would render a title + subtitle::

>    <h1>h1. Bootstrap heading <small>Secondary text</small></h1>

Aside: "html-base" and its descendants place sub-title and sub-headings
in paragraph objects with the "subtitle"/"section-subtitle" class
argument because the standard says:

    # h1–h6 elements must not be used to markup subheadings, subtitles,
    # alternative titles and taglines unless intended to be the heading for a
    # new section or subsection.
    # -- http://www.w3.org/TR/html/sections.html#headings-and-sections

For CSS styling, see "html_base/minimal.css" and the rendering examples under
http://www.w3.org/TR/html/common-idioms.html#common-idioms

> I do recognize the issue is complicated, there's no universal default that
> can make everyone happy. What is your thoughts making the html element
> *and* class / id of title, subtitle, header level 1, 2, 3...  configurable
> via options?

Is there a problem with the existing options that would be better solved
via a more specific/intrusive option?

> Is there a an example you have of how the html element and class of title,
> subtitle, h1, h2, h3...  output could be set via Python / subclassing
> HTMLWriter?

Not that I know of. Seems to be a seldom asked question nowadays.

hope that helps,

Günter