Class DocTitle

Transform --+
            |
           DocTitle

In reStructuredText_, there is no way to specify a document title
and subtitle explicitly. Instead, we can supply the document title
(and possibly the subtitle as well) implicitly, and use this
two-step transform to "raise" or "promote" the title(s) (and their
corresponding section contents) to the document level.

1. If the document contains a single top-level section as its
   first non-comment element, the top-level section's title
   becomes the document's title, and the top-level section's
   contents become the document's immediate contents. The lone
   top-level section header must be the first non-comment element
   in the document.

   For example, take this input text::

       =================
        Top-Level Title
       =================

       A paragraph.

   Once parsed, it looks like this::

       <document>
           <section name="top-level title">
               <title>
                   Top-Level Title
               <paragraph>
                   A paragraph.

   After running the DocTitle transform, we have::

       <document name="top-level title">
           <title>
               Top-Level Title
           <paragraph>
               A paragraph.

2. If step 1 successfully determines the document title, we
   continue by checking for a subtitle.

   If the lone top-level section itself contains a single
   second-level section as its first non-comment element, that
   section's title is promoted to the document's subtitle, and
   that section's contents become the document's immediate
   contents. Given this input text::

       =================
        Top-Level Title
       =================

       Second-Level Title
       ~~~~~~~~~~~~~~~~~~

       A paragraph.

   After parsing and running the Section Promotion transform, the
   result is::

       <document name="top-level title">
           <title>
               Top-Level Title
           <subtitle name="second-level title">
               Second-Level Title
           <paragraph>
               A paragraph.

   (Note that the implicit hyperlink target generated by the
   "Second-Level Title" is preserved on the "subtitle" element
   itself.)

Any comment elements occurring before the document title or
subtitle are accumulated and inserted as the first body elements
after the title(s).