[Doc-SIG] Re: Oscar - pre-announcement over on Types-SIG

[Tony J Ibbs (Tibs)]

David Goodger replied to Greg Ward (who was replying to me):
> > I used to watch the doc-sig, but got overwhelmed.  Sorry...
>
> There are only so many hours in the day! :-)

Indeed!

> I'm not sure about Tony's reference to a "specialized plugin" for
> fields. Although we have settled on a syntax for field lists, there
> has yet to be a discussion about what field lists actually *do*, if
> anything, other than describing a data structure. I'm wary of it, but
> one (remote) possibility is for field lists to acquire functionality
> similar to that of directives.

Nah - I think it was a brainio on my part - I was trying to make a
response in between building executables and debugging something else,
and indeed what I *should* have said is what David suggests next:

> Another option: use a directive:

Greg then asks:
> > Question for the doc-sig:
> >   * is DPS/reST the One True Docstring syntax? do we have
> >     it at last? an end to the docstring wars?  or is this
> >     just one more proposed syntax?

Technically, it is indeed "just one more proposed syntax". But David has
done two important things - he has separated the infrastructure that
*uses* the docstrings from the parser that understands their content
(hence the DPS and reST split, respectively - and yes, I know HappyDoc,
for instance, has done it as well, but it didn't do it so, well,
prominently), and he has also managed to amalgamate the threads on the
Doc-SIG to produce something that, whilst not *actually* and *formally*
proposed as the One True Syntax, has a good chance at it.

As a long term Doc-SIG participant (my name is Tibs and I'm involved
with the Doc-SIG) *I* am willing to accept it as the OTS (erm...). More
importantly, Guido has made modest supportive noises (warning: my
success at remembering details of what Guido says is limited!).

Also, it *won't* be a *required* syntax - documenting in plain text (for
instance) will always be "allowed" (not that there's anyone to allow or
disallow such things).

Regardless, for the trivial changes to be made to Oscar that admit it to
reST compliance, it seems worth it to me.

> The reStructuredText parser is almost complete, but the DPS itself is
> still in its infancy. The DPS is a framework, providing a clean
> separation of input markup, processing, and output format.

What he said. Progress *is* being made, though.

> In combination with an "oscar" directive the syntax wouldn't be a
> problem, since the directive can parse its data using a special local
> syntax. It may even be feasible to add an optional classifier to
> definition list items::
>
>     term [ ' : ' classifier ]
>         definition
>
> This would be enough to separate the Oscar 'type' from the classifier.
> The classifier could be formatted distinctively, in italics or
> otherwise.

Hmm - do we care about the distinctness (or not) between::

    term : classifier

and::

    word: some text

I'd probably leave that for the moment.

Tibs

--
Tony J Ibbs (Tibs)      http://www.tibsnjoan.co.uk/
"How fleeting are all human passions compared with the massive
continuity of ducks." - Dorothy L. Sayers, "Gaudy Night"
My views! Mine! Mine! (Unless Laser-Scan ask nicely to borrow them.)