[Doc-SIG] which characters to use for docstring markup

[Edward D. Loper]

> FYI, I have the HappyDoc formatter/docstring extractor
> (happydoc.sourceforge.net),
> generating standard Python documentation LaTeX from docstrings. It's kind
> of nice, because it means that I immediately have all of the python.sty
> features available
> to me for crosseferencing etc., plus it immediately gives me my docstring
> derived documents in PDF, PS, HTML, and info (if I can get info working
> again).

The only formatters I could find for HappyDoc use StructuredTextClassic,
or some variant.  And many people (incl. Guido) are not terribly happy
with ST.  Does the formatter you're talking about use something else?
What does it do about lists, etc?

> def foo():
> 	r"""
> 	My \code{foo} function \emph{breaks} the
> 	\module{bar} module.\index{Foos and Bars}
> 	"""
> 	pass

Most people have objected to "heavyweight" markup for docstrings.. 
i.e., they don't want to have to write docstrings in LaTeX or XML
or whatever..  It *looks* like you're basically just writing 
docstrings using some subset of LaTeX?  If so, we'd have to carefully
define *which* subset, and what everything means, etc., before I
would accept it.  We don't want people assuming that, just because
they can use \emph{...}, they can use all their other favorite LaTeX
commands (we do, after all, want it to be possible to convert this
to HTML, info pages, etc.)

> 1)	It's quite complete for all of the entended uses (\emph(...})
> 	Because it's more or less TexInfo compatible, most people know it
> 	or can learn it easily, even if you don't know LaTeX.

But you can't make it *too* "complete," or it won't be a standard that
people can write tools to process anymore..  We don't want to just
reimplement LaTeX here...

> 2)	It means you can cut and paste between docstrings and the formal
> 	module documentation for Doc/.
> 3)	The macros/commands are already completely documented, and the 
> 	documentation for them ships with the core distribution.
> 4)	It would reinforce the use of the Doc/ tools.

I actually am not too familiar with the Doc/ tools..  Can you give
me a pointer to them?  But copy/paste does seem useful.  (Although it 
should at least be possible to write conversion tools, in any case, 
given a good standard).

> 5)	It would reinforce the use of HappyDoc (semi-literate programmming).

Happydoc seems like a nice tool.  Whatever markup language we settle
on (if we ever do), a HappyDoc formatter will probably be implemented..

> 7)	It's likely to be mainly backward compatible - I doubt many
> 	docstrings use \ a lot. On the other hand, I bet a lot of
> 	them use blank line as a paragraph seperator.

I believe that trying to be "backward compatible" with a markup language
is an extremely dangerous thing to do, esp. if your markup language is
relatively "forgiving," because you probably won't *notice* the places
where it gets confused.  I would rather be explicitly non-backward-
compatible.

-Edward