[David writes back on Sat 22-Jan-00]
In preparation of a discussion at IPC8's DevDay,
Well, I think we all agree on how that went ;-)
and anticipating (perhaps mistakenly) some resistance to "yet another structured text format" from Jim Fulton, I
In the short discussion on that topic, it seemed that Jim had no great objections. So, as DevDay didnt achieve much, I think we should run with this grammar. My comments, generally ignoring what Ken already commented on:
StructuredText as XML without a DTD:
Im happy to ignore StructuredText for out-of-line doc for now. The critical issue we have to deal with is docstrings. Did we ever determine what OReilly's position on XML and particular DTDs is?
The requirement that a paragraph end with the word example or examples or :: goes against my natural style, as I often do not
IMO, its not too bad, as it is only used to introduce single paragraph code-block (if I read the rules correctly?)
If the two colons are not displayed by the renderer, then my objection is diminished, although I would have preferred a markup which is local to the paragraph which is affected
Agreed.
Missing features:
The definition of references is well-designed for referencing URLs. The docstring proposal needs to address referencing other code elements (methods of current class, other classes, other methods of other classes, builtin modules, imported modules, etc.) This is also more of a lack of feature than a real flaw, and defining the namespaces for lookup of 'reference targets' would probably go most of the way towards fixing the spec for our needs.
Definately agreed, and IMO quite a critical issue. In the absense of any other complaints or comments about this proposal, I suggest that this proposal is what we run with for doc-strings. The key problem is getting tools and code to work with this revised proposal, and exactly what this means to StructuredText as used today by the Zope guys. The key feature of this proposal is that it can already give us something to work with. As mentioned a few times on DevDay, we need a blessed doc-string format so people can start writing docstrings in the knowledge tools will follow. So, does anyone else have any comments on David's proposal? Can we work towards a new set of "Structured Text for DocStrings" rules that people can start using for their docstrings? This SIG has been going for ages, and has been amazingly short on results (a critisism that obviously includes myself!). It really is time to get something happening, and this is an excellent start! Mark.