[PYTHON DOC-SIG] Structured documentation syntax

[Graham C. Hughes]

-----BEGIN PGP SIGNED MESSAGE-----

In message <3234BF96.6181F217@sse.tottori-u.ac.jp>, 
    Ka-Ping Yee writes:
>I know that it may not be my place to speak so soon, as i have
>not spent any time researching what has been done, but a look
>at the description on the doc-sig page produced these thoughts
>(in order of decreasing strength):

I'm in the same boat here, but I've seen more than a few auto-docs in
my time.  Mostly, I agree with Ping, except for one or two points...

>  - Couldn't you just choose one bullet marker for list elements,
>    instead of three?

This is probably to accomodate existing text, which uses a bewildering
variety of markers.  FYI, nroff uses an asterisk overstruck with a
dash as a list marker...

>  - It might be nicer (simpler) to use _underscores_ for italics
>    and use *single asterisks* for bold.  (Special Python names
>    that start and end with underscores should be marked as code
>    examples anyway...)

Underscores are traditionally used for citations in (e.g.) Usenet.
You would refer to _Running_Linux_ by Matt Welsh, or _The_TeXBook_ by
Knuth.  Asterisks have traditionally been used for emphasis, but there
isn't the difference between (in HTML) <STRONG> and <EMPH>.  There is
some prior art for using /slashes/ for italics, but I don't know how
well that goes over.  Emacs-w3 mode uses ~tildes~ for general
emphasis, as did earlier versions of gendoc.

>Has there been any thought towards a well-defined standard
>for documenting functions?  I'm thinking of things about
>the interface, like parameter lists and descriptions of
>parameters, and maybe a defined place for a one-sentence
>(or even one-predicate) summary of what the function does,
>and/or what circumstances it expects to be run under.

This is needed.  Now, I've just jumped in here, so there may be some
as-yet-unpublished standards doc on this very subject.  But it's not
on the Python web page...

All that exists at the moment is expressed in the Python manuals: the
first line should be a concise summary of the function, the second
line should be blank, and anything else should be wonderfully
illustrative.

I suppose I should be more specific about this; I'll have to look
through all my documentation stuff before I make up my mind.  Javadoc
has different conventions for Perl's POD, which is in turn different
from (say) cxref and cxx2html.

Finally, is anyone else working on formatters for [nt]roff and LaTeX?
- --
Graham Hughes (graham@resnet.ucsb.edu)  finger for PGP key
``Unix is many things to many people, but it's never been 
		everything to anybody.''
Home page at: http://www.cs.ucsb.edu/~ghughes/
-----BEGIN PGP SIGNATURE-----
Version: 2.6.2
Comment: Processed by Mailcrypt 3.4, an Emacs/PGP interface

iQCVAwUBMjT0BSqNPSINiVE5AQFTqQQApLp0fHja4kU2/8vn7SqjP1f9V+8lGgeJ
poVWGOnJrXLRHOLcdC7QvcAIBKp5D31lUk/x7mlGS7NglEioaPHEb3LSxX/rl8Dh
D4zpH7UJcozyFaxSXHKNqKwH3OzwA7fyA9wRTmeBrZRkMkk2TdNgmeZJ6kT5x7XN
fK5FbHQEXyM=
=N88r
-----END PGP SIGNATURE-----

=================
DOC-SIG  - SIG for the Python Documentation Project

send messages to: doc-sig@python.org
administrivia to: doc-sig-request@python.org
=================