[Doc-SIG] usage docstrings and bibliographic field lists

[Garth Kidd]

I think we need to support field list option 3 (``reStructuredText.txt``
revision 1.1.1.1 line 478) to support PEP-0257 style usage docstrings in
Python scripts without preventing script authors from specifying
bibliographic field lists.

Background:

The reStructuredText spec supports field lists of RFC-822 style
headers::

 Special case: use unadorned RFC822_ for the very first or very last
 text block of a docstring::

     """
     Author: Me
     Version: 1

     The rest of the docstring...
     """

Note that it says *docstring*, not *document*. :) Later, the spec says::

  One special context is defined for field lists. A field list as the
  very first non-comment block, or the second non-comment block
  immediately after a title, is interpreted as document bibliographic
  data. No special syntax is required, just unadorned RFC822_. The first
  ...

Making the least effort to eliminate ambiguity, I come up with:

* When using reStructuredText in docstrings, you can have as
  many field lists as you like, in any docstring, so long as they're
  either the first or last block in the docstring.

  - In a document, you can have only two: one at the beginning, and
    one at the end.

* A field list as the first non-comment block in a document becomes
  ``document bibliographic data``.

  - In docstrings, this becomes tricky. To me, it ends up saying that
    a field list at the top of the *first docstring* (the second if
    the first is a title) becomes bibliographic data for the file.

PEP-0257 says::

  The docstring of a script (a stand-alone program) should be usable
  as its "usage" message, printed when the script is invoked with
  incorrect or missing arguments (or perhaps with a "-h" option, for
  "help").  Such a docstring should document the script's function
  ...

To cut a long story short, when these two lock horns it looks like we
can't have reStructuredText bibliographic field lists in scripts because
otherwise the script couldn't print its usage with a simple ``print
__doc__``.

If by this point you've already figured out how to resolve the issue by
straightening out wording in the spec, not changing any code, please let
me know. :)

The simplest fix I can see is to accept the previously-rejected "option
3" of a ``fields`` directive::

 .. fields::

If specified, it would signal to the parser that the next text block was
a field list, not a paragraph. Furthermore; if it was the first field
list in the document (ie there wasn't one at the top), the field list
would be treated as bibliographic data.

The ``fields`` directive would not be required for field lists at the
beginning or end of a document or docstring. We might generate a
warning.

Regards,
Garth.

PS: The usage for many scripts looks like this::

  """\
  Usage: cvs [cvs-options] command [command-options-and-arguments]
    where
  ...
  """

Perhaps we should suppress recognition of bibliographic field lists
without generating warnings if the first field name seems to be
``Usage``.