Re: [Docutils-users] Headlines and Structure

[Dave K. <dku...@cu...>]

On Wed, May 12, 2004 at 08:36:16PM -0400, Dave Edwards wrote:
> I've recently begun to use docutils and rST.  I like these tools a
> lot, but I have a small gripe about the way docutils interprets rST.
> 
> docutils seems to designate the top-level headline as a title, and the
> subsequent one as the first "body headline".  To put that more
> clearly, docutils interprets the following:
> 
> =========
> Top-Level
> =========
> 
> Lorem ipsum dolor sit amet.
> 
> 2nd-Level
> ---------
> 
> as:
> 
> <h1 class="title">Top-Level</h1>
> <p>Lorem ipsum dolor sit amet.</p>
> <h1>2nd-Level</h1>
> 
> To me, this is very counter-intuitive.  I expect the hierarchy to
> begin from the top of the document.  The current model seems to impose
> a certain structure -- title-and-body -- on docutils users, rather
> than trusting them to handle it.  My questions are:

This is from the "reStructuredText Markup Specification":

    "Specifically, there is no way to indicate 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."

Ref:

    http://docutils.sourceforge.net/spec/rst/reStructuredText.html#document-structure

So, I interpret this as saying that if you have a paragraph before
your first section title and then several top-level titles at the
same level, you will get a document with no (top-level) title and
with several top-level sections.  Is that what you want?

Dave


> 
>   1. Am I doing something wrong?  I've put an example at
>   http://dle.ascendant.ca/lorem.html .  I have looked at other
>   docutils-generated pages, and I don't think I'm in error, but I ask
>   just to make sure.
> 
>   2. Is there a way to use rST and/or html.py so that the document
>   hierarchy begins at the top-level headline, rather than use the
>   title-and-body arrangement?

Oops.  Now you have me confused.  What is the difference?

Dave

-- 
Dave Kuhlman
dku...@re...
http://www.rexx.com/~dkuhlman