[PYTHON DOC-SIG] Structured documentation syntax

[Jim Fulton]

Graham C. Hughes wrote:
> 
> -----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.

As I said in my other message, my concern is that what ever is 
done, the text should still be readable as is.

> >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. 

Yup.  See my other message.

> 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?

If gendoc supports TIM, then it will get LaTex, texinfo, info, and
Postscript nearly for free.  The tool I posted a while ago, module2html
does roff. (But probably not as robustly.)

Jim

> 
> =================
> DOC-SIG  - SIG for the Python Documentation Project
> 
> send messages to: doc-sig@python.org
> administrivia to: doc-sig-request@python.org
> =================

-- 
Jim Fulton         Digital Creations
jim@digicool.com   540.371.6909
## Python is my favorite language ##
##     http://www.python.org/     ##

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

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