[Doc-SIG] Docstring markup process
Tony J Ibbs (Tibs)
Mon, 12 Mar 2001 10:03:10 -0000
> Paul Prescod made an excellent meta-proposal for docstrings at the
> recent conference: rather than arguing endlessly about various
> markup formats, anyone who wants to propose a particular markup format
> should write a PEP describing that format in detail. Only formats
> described in a PEP will be under serious consideration. By an agreed
> deadline, we can vote on the PEPs, and then be done with it.
Sounds OK by me - although I haven't *heard* any argument for a long
time (was there argument at the conference? Why aren't they arguing here
where I can hear them!).
I rather fondly thought we were working on STNG with minor extensions,
specifically '>>>' paragraphs and '#...#' markup, with other stuff to be
decided later on when that was working (sounds like what a PEP could
say!), but maybe I was mistaken. Of course, writing that down *formally*
somewhere is not a bad idea...
(it seemed somewhat Pythonic to me to work on the thing as one was
with Edward Loper producing STminus to allow us to understand
relationships and maybe be able to produce interoperability.
> Of course we can discuss the various proposals here, but it's a big
> step forward to get them written up and all in one place for
Do we *have* various proposals? I guess this is one way of finding
> I strongly support this process; let's pick a deadline.
OK, but please make it at least a month away or I'm unlikely to have
time to write anything - are we at least allowed to have a quick stab at
agreeing something here of thinking of what goes on, or are PEPs to be
subimtted any old how?
(reasons for asking is that I was fondly hoping to tidy up docutils a
bit, rewriting docstrings where necessary, redo the STpy documentation
somewhat, and alpha release within the next fortnight, thus making STpy
the 'de-facto' standard for people to organise grumbles at. If peps are
being written, then that has to go on hold, which is a pain - unless
STpy documentation *becomes* a PEP.)
Or is this related to Ka-Ping Yee's mega-documentation scheme, addressed
Suggestion for meat-and-bones of PEP:
1. STNG plus '>>>' plus '#...#', maybe plus "tagged paragraphs" -
what docutils supports now ('cos I *know* it hangs together
- working out what ST variants work is an ad-hoc business)
2. Future enhancements to include: <list of future enhancements> - these
are also discussed in the STpy document, but need deciding which ones
the community wants. The most important is references within a
and the next most important references to a Python object.
3. Whether ST<whatever> gets vastly expanded to meet Ka-Ping Yee's
proposal (discussed in another email).
I'm certainly intending to try to produce (1), I guess...
Tony J Ibbs (Tibs) http://www.tibsnjoan.co.uk/
Give a pedant an inch and they'll take 25.4mm
(once they've established you're talking a post-1959 inch, of course)
My views! Mine! Mine! (Unless Laser-Scan ask nicely to borrow them.)