[DOC-SIG] [XML] Notes on the Tutorial's markup

[Andrew Kuchling]

[This shouldn't be restricted to psa-members, and belongs on the
doc-sig@python.org; please direct your followups there.]

Recently it was proposed to use a XML markup for the Python
documentation.  This is an excellent idea, so here are some notes on
the LaTeX features used by the tutorial, and by api.tex, ext.tex --
they're relatively straightforward documents which only use a little
simple formatting.  I've dodged the really complicated question, which
is the Library Reference.  

No markup is proposed for these features; that's been left for people
such as Paul Prescod who actually know XML.  Probably HTML could be
followed for these.

Markup for tut.tex et al.:
==========================
Header stuff:
	Document title
	Abstract
	Author / copyright 
	Date

Section organization:
	Chapters, sections, subsections, sub-subsections 
		(H1 through H4, in HTML terms)

Lists: Both enumerated (1,2,3...) & not (bullets).	

Text markup:
	Emphasized text
	Footnotes
	URLs, e-mail addresses
	Filenames: {\tt /usr/local/bin/python}
	Including Python code in running text: {\tt a+b}
	Verbatim inclusions of Python code in separate chunks:
		\bcode\begin{verbatim}
		>>> width = 20
		>>> height = 5*9
		>>> width * height
		900
		\end{verbatim}\ecode
	Ideally, you wouldn't have to escape too many characters
	inside these chunks. 

Indexing: 
	Need a way to indicate relevant indexing keywords for each
paragraph (indexing doesn't seem to be easily automated)


	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
_______________