[Doc-SIG] Re: PEP 258: DPS Generic Implementation Details

[Ralph Corderoy]

Hi,

>    Choice of Docstring Format
>    ==========================
>
>    Rather than force everyone to use a single docstring format,
>    multiple input formats are allowed by the processing system.  A
>    special variable, __docformat__, may appear at the top level of a
>    module before any function or class definitions.  Over time or
>    through decree, a standard format or set of formats should emerge.

I read in another Doc PEP of the difficulty extracting structure from
the plain text of a docstring.  Of the various Wikis I found TWiki's
plain text input format allows quite a lot of structure to be expressed
whilst still being readable as plain text.  Perhaps it would present
some ideas.

One thing that it uses to good effect is significant whitespace.
Something familiar to all :-)

Allowing multiple docstring formats, whilst perhaps least contentious,
does seem a little like trying to please everyone.


Ralph.

PS.  Not on mailing list.  Sent there at request of Usenet posting.
Please CC.