[Doc-SIG] Some Premilinary Thoughts on Syntax

[Moshe Zadka]

Since I won't be back at home until next week, and since the DOC-SIG
devday sort of nominated me to suggest a syntax for the documentations,
I'll just outline what I think is needed, how I plan on feeling that need,
and skectch the specs and software needed.

There was a consensus that there should be two syntaxes -- one for the
embedded doc-strings, and one for out-of-line documentation. (Note that
wherever I refere to doc strings from now on, a doc string is the
concatanation of all initialstrings in ..., as opposed to the python
interpreter. This is deliberate, and is meant to hve doc strings which can
be optimized away).

The first thing we would need is to make sure the two markups are
semantically equivalent. More precisely, we'll need to figrue out what
"element" (to use XML terminilogy) an embedded doc string corresponds to
in the OOL (out of line) documentation, and make sure we have a one to one
correspondence betweent the syntaxes. At the risk of being flamed to
death, I will offer that this means throwing StructureText clean out of
the door, as it is impossible to reason about it. The only structured text
idea that would be left would be indentation for blocks, because it
meashes well with the rest of the code.

Then we need a spec to define how an ool document can refer to the
documentation inside a module. I'm thinking of a template mechanism, since
it generalizes the two common cases --

- complete ool documentation would be a paramteter-less template
- complete embedded documentation would be using the default template.

The requirement for both of the syntaxes are that they would be very human
writable, and yet structurally equivalent to XML. 

The ool is relatively easy -- we'll use XML plus some of the minimization
from XML. Paul Prescod seemed to say something about it in the elevator,
and I'm hoping to beat something more concrete out of him.

The embedded is up for grabs -- I'm not yet cnvinced it should be human
(as opposed to doc-writer) readable, since I think

>> import help
>> help.help(foobar)

is infinitely better then

>> print foobar.__doc__

And if it's not, we should be able to use hooks in the interpreter to
convert the doc-sig to readable text before it ends up in foobar.__doc__.

Disclaimer:
These are late-night thoughts more written as notes to myself. I'm not as
convinced about things as I sound, so if you have some diagreement, please
mail me (personally, prefereably, to forestall the inevitable flamewar)

--
Moshe Zadka <mzadka@geocities.com>. 
INTERNET: Learn what you know.
Share what you don't.