[DOC-SIG] Library reference manual debate

[Bill Janssen]

Excerpts from ext.python: 15-Nov-97 [DOC-SIG] Library reference.. Guido
van Rossum@CNRI.Re (7617)

> it should be simple enough to rewrite
> the TIM-to-HTML converter in Python (maybe using HTMLgen?).

Probably make more sense to do a TIM-to-XML script in Python...

Excerpts from ext.python: 15-Nov-97 [DOC-SIG] Library reference.. Guido
van Rossum@CNRI.Re (7617)

> The other one is much hairier: conversion of the existing LaTeX source
> to TIM!

The first thing we'd need is a definition of the various markup terms we
wanted to use.  For example, is it better to say "\code" and assume
Python code, or "\python" so that we can also say "\C"?  Should we say
(as the lib sources currently do) "\code" for everything, or do we want
to distinguish the names of functions, say, from the names of modules by
using "\module" and "\function"?  Next, we could start by converting all
the strings of the form "\foo{" to "@foo{", which accomplishes a
remarkable amount of the work.  Then we'd need to replace various common
phrases like

	@renewcommand{@indexsubitem}{(<data,exception,...> in module <module>)}
	@begin{<data,func,exc}desc}{<name>}
	...
	@end{<name>}

with an appropriate TIM construct:

	@def{tp,fn,exc...} <name>
	@{tt,et,vt...}index <module>.<name> (<data,exception,...> in module <module>)
	...
	@end def{tp,fn,exc...}

Most of this can be accomplished with a few Emacs macros.

> One final note: I looked at Perl's POD (Plain Old Documentation) for a
> few seconds.  It's more limited than TIM and uses physical markup
> (e.g. B<words in bold>), but has one feature that I like: a block of
> indented text offset by blank lines (I believe) is automatically
> interpreted as a code sample block (verbatim in LaTeX terms,
> @codeexample in TIM).  This makes POD source remarkably readable.  I
> presume that it would be trivial to add this to the TIM front-end.  (I
> particularly like this idea because it's the same convention that I
> used in the Python FAQ wizard. :-)

I'll put it on my list.

_______________
DOC-SIG  - SIG for the Python Documentation Project

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