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

1997年11月11日 13:35:53 -0500 (EST)

[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
_______________