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

[Mike Clarkson]

At 04:06 PM 4/6/01 -0500, Guido van Rossum wrote:
>> I've been a bit busy lately, but I'm still working on coming up with
>> a good markup language for docstrings...

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

Because the delimiters are the standard \backslash and curlys, it means
you can convieniently take advantage of r"""strings"" to protect the
backslash markup in docstrings:

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

Seems that this is legal Python, and allows HappyDoc to use Python
to get the class structure with the docstrings. Also, the TeX convention
of a blank line to mark a paragraph is really useful.

Would this work for what you are wanting to do with docstring markup?

The advantages I see is that:
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.
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.
5)	It would reinforce the use of HappyDoc (semi-literate programmming).
6)	It would avoid yet another documentation markup language.
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.
8)	No need for syntax discussions, as it's already done :-)

Mike.