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

[Greg Ward]

On 21 August 2001, David Goodger said:
> Another option: use a directive::
> 
>     class Animal (Thing):
>         """An animal, ie. a thing with multiple legs and possibly fur.
>   
>         Instance attributes:
> 
>         .. oscar::
>            num_legs : int
>                the number of legs this animal has
>            furry : boolean
>                whether this animal is furry or not
>   
>         Outsiders should use 'get_num_legs()' and 'is_furry()'
>         to access these attributes.
>         """
> 
> The "oscar" directive is free to define the syntax of its contents and
> do anything it likes with the results.

FYI: s/oscar/grouch/; too many projects named "Oscar" already.  Anyways.

Seems to me that a much neater way to do this would be

        .. grouch-instance-attributes::
           num_legs : int
               the number of legs this animal has
           furry : boolean
               whether this animal is furry or not
  
ie. drop the "Instance attributes:" line entirely, and just use a single
reST directive.  It's just spelling; why say the same thing twice?

> The DPS_ is the Python Docstring Processing System, subject of PEPs
> 256 and 258. reST [1] is reStructuredText, a markup syntax and parser
> component of the DPS, possibly one of many.

OK, that was my rough understanding, based mainly on skimming the
doc-sig for the last couple of months.  Glad to hear things are going
right at last -- I would be quite happy to make trivial changes to
Grouch's syntax to play along nicely with reST.  It's not gonna happen
in the first release, though, which is imminent.

 In my biased opinion, it
> reStructuredText seems to have more support than any other
> proposal, and the best chance of success. Juergen Hermann of MoinMoin
> fame has shown definite interest, as have others (in private
> correspondence), and still more are guardedly interested (wait and
> see).
> 
> .. _DPS: http://docstring.sourceforge.net
> 
> .. [1] A complete reference to reStructuredText can be found at
>    http://structuredtext.sourceforge.net/spec/reStructuredText.txt,
>    and Tony's QuickRef is located at
>    http://structuredtext.sourceforge.net/docs/quickref.html.
> 
> 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.

All sounds pretty sensible to me.

<digression irritation="moderate">
Just downloaded "rst.0.3.tar.gz".  Argg.  One of the reasons I wrote the
Distutils was because I was (and still am) tired of downloading tarballs
with non-standard names that unpack to directories whose names are not
immediately obvious from the tarball.  Such as, for instance
"rst.0.3.tar.gz" which unpacks to "restructuredtext".  If you had simply
used the Distutils "sdist" command (and updated the version in your
setup.py), this would be "rst-0.3.tar.gz" which unpacks to "rst-0.3",
which is the time-honoured convention for source distributions on Unix,
used by thousands of programmers for well over a decade.  Grumble.  The
Distutils exist for a reason!
</digression>

> If you get on the bandwagon with Oscar, it will help push
> reStructuredText toward becoming the exalted "One True Syntax", and
> help push the DPS toward completion and eventual inclusion in the
> standard library. So please do! And your input is welcome.

Yeah, that would be a good thing.  I'll look into it for some future
version.

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

Interesting notion.  Whether it's of general interest will have to be
decided by the doc-sig, but I like it!  ;-)

For the record, I'd much rather require spaces around a single colon
than any other contortion -- ie. " : " over "::".

        Greg
-- 
Greg Ward - software developer                gward@mems-exchange.org
MEMS Exchange                            http://www.mems-exchange.org