[Docutils-users] Section titles, with or without multiple sections in document

[Ben F. <ben...@be...>]

Howdy all,

How can I disable the special-case treatment of a lone section title as
the document title?

The default reST parser treats a lone section title as a special case,
promoting it as the document title. What I want is to disable that
behaviour, and have the first section treated as a section regardless of
whether any sections follow it.

A document with two top-level sections is parsed as I want:

=====
$ cat foo.txt
First Section
=============

Lorem ipsum, dolor sit amet.

Second Section
==============

Praesent eleifend ligula eget luctus consectetur.

$ rst2pseudoxml < foo.txt
<document source="<stdin>">
    <section ids="first-section" names="first\ section">
        <title>
            First Section
        <paragraph>
            Lorem ipsum, dolor sit amet.
    <section ids="second-section" names="second\ section">
        <title>
            Second Section
        <paragraph>
            Praesent eleifend ligula eget luctus consectetur.
=====

But if the document has only one top-level section, the special case
applies and I don't get the sections as I want:

=====
$ cat foo.txt
First Section
=============

Lorem ipsum, dolor sit amet.

Second Section
==============

Praesent eleifend ligula eget luctus consectetur.

$ rst2pseudoxml < foo.txt
<document ids="first-section" names="first\ section" source="<stdin>" title="First Section">
    <title>
        First Section
    <paragraph>
        Lorem ipsum, dolor sit amet.
=====

What I want is:

=====
$ rst2pseudoxml < foo.txt
<document source="<stdin>">
    <section ids="first-section" names="first\ section">
        <title>
            First Section
        <paragraph>
            Lorem ipsum, dolor sit amet.
=====

In fact, I'm accessing this document programmatically using a custom
Writer. How can I get the parsing result I want?

-- 
 \         “A politician is an animal which can sit on a fence and yet |
  `\                  keep both ears to the ground.” —Henry L. Mencken |
_o__)                                                                  |
Ben Finney