Re: [Docutils-users] h1, etc

[David G. <go...@us...>]

Mark McEahern wrote:
> When I run it through tools/html.py, I get unexpected results (below).  I
> was expecting H1, H2, then H3; instead, I get H1, H1, H2.

Check the "class" attribute on the "h1" tags, and you will see a difference.

The first title becomes the document title.  From the markup specification:

    Specifically, there is no way to specify a document title and
    subtitle explicitly in reStructuredText.  Instead, a lone
    top-level section title (see Sections_ below) can be treated as
    the document title.  Similarly, a lone second-level section title
    immediately after the "document title" can become the document
    subtitle.  See the `DocTitle transform`_ for details.

    (http://docutils.sf.net/spec/rst/reStructuredText.html#document)

HTML is being used for dumb formatting; it isn't meant for anything but
final display.  A stylesheet *is* required, and you're welcome to roll your
own.  HTML is limited with only H1..H6, so we need to use them sparingly.
The HTML Writer uses H1 for document title and H2 for document subtitle, and
starts over at H1 for section titles.

This will definitely go into the FAQ, being the most frequently asked
question so far.

-- 
David Goodger  <go...@us...>  Open-source projects:
  - Python Docutils: http://docutils.sourceforge.net/
    (includes reStructuredText: http://docutils.sf.net/rst.html)
  - The Go Tools Project: http://gotools.sourceforge.net/