docutils.transforms.frontmatter.DocInfo

This transform is specific to the reStructuredText markup syntax; see "Bibliographic Fields" in the reStructuredText Markup Specification for a high-level description. This transform should be run after the DocTitle transform.

Given a field list as the first non-comment element after the document title and subtitle (if present), registered bibliographic field names are transformed to the corresponding DTD elements, becoming child elements of the "docinfo" element (except for a dedication and/or an abstract, which become "topic" elements after "docinfo").

For example, given this document fragment after parsing:

<document>
    <title>
        Document Title
    <field_list>
        <field>
            <field_name>
                Author
            <field_body>
                <paragraph>
                    A. Name
        <field>
            <field_name>
                Status
            <field_body>
                <paragraph>
                    $RCSfile$
    ...

After running the bibliographic field list transform, the resulting document tree would look like this:

<document>
    <title>
        Document Title
    <docinfo>
        <author>
            A. Name
        <status>
            frontmatter.py
    ...

The "Status" field contained an expanded RCS keyword, which is normally (but optionally) cleaned up by the transform. The sole contents of the field body must be a paragraph containing an expanded RCS keyword of the form "$keyword: expansion text $". Any RCS keyword can be processed in any bibliographic field. The dollar signs and leading RCS keyword name are removed. Extra processing is done for the following RCS keywords:

• "RCSfile" expands to the name of the file in the RCS or CVS repository, which is the name of the source file with a ",v" suffix appended. The transform will remove the ",v" suffix.

• "Date" expands to the format "YYYY/MM/DD hh:mm:ss" (in the UTC time zone). The RCS Keywords transform will extract just the date itself and transform it to an ISO 8601 format date, as in "2000-12-31".

  (Since the source file for this text is itself stored under CVS, we can't show an example of the "Date" RCS keyword because we can't prevent any RCS keywords used in this explanation from being expanded. Only the "RCSfile" keyword is stable; its expansion text changes only if the file name changes.)