Re: [Docutils-users] Subtitle issue

[Patrick K. O'B. <po...@or...>]

On Tuesday 21 January 2003 08:53 am, David Goodger wrote:
> I tried the full file just now, and I see the problem.  It's very simple.
> The table of contents gives a clue (note the nesting):
>
>     * Using Python As An Authoring Tool
>
>       * Introduction
>       * reStructuredText
>
>     * Creating a custom writer for dW tutorials
>
> Here's the document subtitle::
>
>     Using Python As An Authoring Tool
>     ---------------------------------
>
> And here's the last section title::
>
>     Creating a custom writer for dW tutorials
>     -----------------------------------------
>
> They both use the same title adornment style -- dash underlines. 
> Therefore the parser places them at the same section level, as evidenced
> by the TOC above.  The solution is to use a different -- and unique --
> adornment style for the document subtitle.  You could add a dash
> overline::
>
>     -----------------------------------
>      Using Python As An Authoring Tool
>     -----------------------------------

Okay, I understand now. Two things might help others in the future. First, 
this entry in FAQ.txt could be a bit more explicit about this requirement:

<quote>
How can I indicate the document title?  Subtitle?
-------------------------------------------------

If there's only one highest-level section title at the beginning of a
document, it is treated specially, as the document title.  Similarly,
a lone second-highest-level section title may become the document
subtitle if it immediately follows the document title.

For example::

    This is the Document Title
    ==========================

    This is the Document Subtitle
    -----------------------------

    Here's an ordinary paragraph.

Counterexample::

    Here's an ordinary paragraph.

    This is *not* a Document Title
    ==============================

    The "ordinary paragraph" above the section title
    prevents it from becoming the document title.
</quote>

Second, even having read all the docs several times (but not all the specs) 
I wasn't aware that adding an overline changed how the section title was 
interpreted. If anything, I had the impression it was a completely optional 
adornment with no semantic significance. Is that not correct? If not, I 
suggest making that clear in this section of quickstart.txt, especially the 
last sentence:

<quote>
To break longer text up into sections, you use **section headers**.
These are a single line of text (one or more words) with an underline
(and optionally an overline) in dashes "``-----``", equals
"``======``", tildes "``~~~~~~``" or any of the non-alphanumeric
characters ``= - ` : ' " ~ ^ _ * + # < >`` that you feel comfortable
with.  The underline/overline must be at least as long as the title
text.  Be consistent though, since all sections marked with the same
underline style are deemed to be at the same level::
</quote>

-- 
Patrick K. O'Brien
Orbtech      http://www.orbtech.com/web/pobrien
-----------------------------------------------
"Your source for Python programming expertise."
-----------------------------------------------