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.