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

[Tony N. <to...@gi...>]

Hi Günter,

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?

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.

The two solutions given sound like hacks with big trade-offs that don't
justify bothering to pass those options through, 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``?
   2. What is the internal issue that makes it difficult to give an option
   to just render h1, h2, h3, h4, h5, h6?*
   3. Does this happen in HTMLWriter?

   If so, how much work would it be to create a config option / python
   interface to configure html element + class for each level? Here's an
   example of how bootstrap would render a title + subtitle::

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

   4.


   5.

   Considering that title + subtitle is a special case, it would be
nice to offer a

   6.

    way to configure output of it that doesn't result in the
trade-offs of those

   7.

   config options.

   8.


   9.

   source: http://getbootstrap.com/css/#h1.-bootstrap-heading-secondary-text


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

* Even if it would chop stuff off - I think that covers 90% of my cases.  I
do not use lone subtitle.  I typically will make a title header, then
immediately go down to h2-section style headers (I follow this convention
in my reST projects, and I see it in many other projects as well)