[Doc-SIG] Docstring grammar: a very revised proposal

[David Ascher]

> Did we ever determine what OReilly's position on XML and particular DTDs
is?

I did ask Frank Willison (editor in chief of O'Reilly, and for those of you
who don't know, a big Python fan) in the hall after the doc-sig
extravaganza.  He says that they think they have a working system now which
works on DocBook, but that it was damn hard to setup the system.  The
problem was that the DocBook Book tried to tackle every corner of the spec,
which was just really hard. This is from memory and was encoded when I was
pretty exhausted, so I won't swear to the exactitude of the recall.

I am not expert enough on large-scale text processing to fully understand
the implications of specific DTD choices, but I think that the impact of a
specific DTD choice is a minor one in the absence of XML editors for the
masses (i.e., Fred did the work before, and realistically, Fred's going to
be doing the work in the foreseeable future at least -- Fred should choose
what he wants to use).  He's already done the hard part of regularizing the
markup and I'm sorry I didn't get a chance to buy him a beer at IPC8.

> 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?

I think I need to put up working code before folks really get a feel for it,
along with a cleaned up description of the format (different strokes for
different folks).  Not everyone followed every thread of the last couple of
months, and I apologize for not having put forth a revised proposal sooner.

I'll ping Ken to find out what the status of their internal reworking of
StructuredText-the-code is.  FWIW, I don't care much whether we use their
code or not.  I care more about having a common 'base grammar' and then
specific extensions for docstrings (and they can have specific extensions
for other things as they see fit).

--david

It's interesting how the percentage of time that I can allocate to Python
has grown proportionally less than the number of Python-related items on my
todo list =).