[DOC-SIG] Re: [PSA MEMBERS] [XML] Notes on the Tutorial's markup

[Andrew Kuchling]

Paul Prescod <papresco@technologist.com> wrote:
>... Despite my
>attachment to XML, it isn't clear that XML is better than Full SGML in
>this context. Here are the major issues in my mind:
	...
	Hmm.  DocBook looks interesting
(http://www.oreilly.com/davenport/), but it is, as you say, pretty
darned big, and one would like to simplify things by switching from
LaTeX.  I'm also not sure if the tools to manipulate DocBook are
freeware, or if you're expected to use the DocBook DTD in commercial
SGML editing tools.

>A related issue is whether we intend to have both a library reference
>and structured docstrings? Or is the library reference just what you get
>by concatenating the docstrings from the various modules? Are people
>willing to make the source the documentation source too?

	In general I think docstrings and a reference manual are two
different things.  The LibRef is supposed to be fairly complete, and
may include sample code, stylistic comments ("You can override this
method, but it's a bad idea; do this instead...").  Docstrings are
intended to be displayed by class browsers and used as comments, and
every byte in a docstring is dragged around at runtime, so you don't
want them to get too bloated.  Making a LibRef out of docstrings will
result in either huge docstrings, or a too-terse LibRef.  

	This means we don't need to use XML/SGML markup in docstrings,
and it isn't necessary that everything can be done in pure Python
(though it would be nice, and probably better, IMHO, since you'd have
to install less software).


	Andrew Kuchling
	amk@magnet.com
	http://starship.skyport.net/crew/amk/


_______________
DOC-SIG  - SIG for the Python Documentation Project

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