[Doc-SIG] Docstring markup process

[Tony J Ibbs (Tibs)]

> 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
de/refining it)

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
> comparison.

Do we *have* various proposals? I guess this is one way of finding
out...

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

Suggestion for meat-and-bones of PEP:

1. STNG plus '>>>' plus '#...#', maybe plus "tagged paragraphs" -
basically
   what docutils supports now ('cos I *know* it hangs together
coherently
   - 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
document,
   and the next most important references to a Python object.

3. Whether ST<whatever> gets vastly expanded to meet Ka-Ping Yee's
latest
   proposal (discussed in another email).

I'm certainly intending to try to produce (1), I guess...

Tibs

--
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.)