[Doc-SIG] docstring grammar

[Tony J Ibbs (Tibs)]

OK - I wrote the following whilst reading through today's batch of messages
(that's what happens when you take your elder son swimming on Tuesday
afternoons, I guess). So apologies if its a bit stream-of-consciousness...

David Ascher wrote:
> The only question I suppose is whether one should require a keyword (Test:
> or other) to keep the top-level syntax trivial, or special-case the
> recognition of >>>-beginning paragraphs.
>
> I'm leaning for the former, as it can evolve to the latter if there is
> sufficient call for it from the user base, and I think it does keep the
> code simpler.  But I'm willing to be swayed.

No - keep the keyword. My reasoning is (a) I like it [emotional reaction,
which is the real reason (parse that as "it feels more elegant")], and (b) I
still have the feeling that on occasion I might want non-test Python script
in there, and (c) it *is* a 'logical' subdivision of the text in exactly the
same way as the other major divisions, and so deserves its own place. I
don't think it leaves us with too many such subdivisions (to reply to Robin
Friedrich later on - although I also don't understand his point about more
tags making it harder to parse things (unless he means "for humans to
parse")).

David Ascher later says:
> I'd like to finalize the top-level structure, get it in front of GvR's
> eyeballs, and then we can tackle each subtopic (so far: list processing,
> reference handling, signature, mandatory keywords, keyword registration
> process, multilingual keyword support, etc.) at a later date.

Yeah, go for it (I don't actually think that we have *much* fiddly
disagreement to resolve about the sub-items, but I agree they ARE less
important than the grand sweep. Get the grand sweep approved and documented
and we can start playing with appearance - and dammit I might give in and
write something - I already know that my translator for the mxTextTools
metalanguage has useful chunks of stuff to be lifted out to get SOMETHING
going quick, and I hope no-one realises how close I am to giving in and
writing something instead of doing work I get paid for...)

Later still:
> A keyword is a case-sensitive string which:
> ...
> As (I think it was) Tibs mentioned, it's syntactic sugar for XML notation

Nah - it was Eddy (he works somewhere not too far away in this building, and
keeps mentioning my name in passing (all very flattering) - partly because I
stop to interrupt his work every time I go past to see if he's writing
something about this...).

In the same message, he dislikes:

> >         [Python Language Web Site] is the main source for Python itself.
> >         [Starship Python] houses a number of Python user resources.
> >
> > [Python Language Web Site] -> http://www.python.org
> > [Starship Python] -> http://starship.python.net

in preference for:

>         [PythonLanguageWebSite] is the main source for Python itself.
>         [StarshipPython] houses a number of Python user resources.
>
>      References:
>         PythonLanguageWebSite:  http://www.python.org
>         StarshipPython: http://starship.python.net

I like the "References:" tag on aesthetic grounds, whether it makes parsing
easier or not (it makes parsing more *regular*, but personally I think we're
working for humans here, to a great extent, and should punt the parsing
issues a *little* bit).

David then worries:

> Which leaves open the question of how we can have 'space-enabled' labels
> for references which can't have spaces in them.
>
> One idea is to tag the [] markup with a ="stringlabel":
>
>         [PythonLanguageWebSite="The Python.org website"] is the main
>          source for Python itself.
>
> Another possibility hinted at previously is to enrich the References
> section:
>
>     References:
>        PythonLanguageWebSite:
>          Label: The Python.org website
>          Link: http://www.python.org
>
> either of which, when rendered, would 'do the right thing.  I only expect
> this to be an issue when referring to URLs.  Python modules, classes and
> functions already have perfectly good names.

Hmm. I don't like the "enriched" form - it's just too verbose for the job
it's doing (which I *think* will translate into "people won't want to use
it").

I don't actually see the problem with allowing spaces in references here, by
the way. Granted they need removing (translating in some manner - do they?)
when generating XML (but perhaps NOT when generating some other output
format). This problem won't go away anyway - if one is translating to J.
Random Format that doesn't allow hyphens in names used as references then we
would still have the same problem. It doesn't, in this instance, matter to
me that the text in [..] need be the same sort of thing as that before a
":", either, if that were the objection.

I would favour:

         [Python Language WebSite] is the main source for Python itself.
         [Starship Python] houses a number of Python user resources.
         See [ascher29] for the source of the algorithm.

      References:
         [Python Language WebSite]:  http://www.python.org
         [Starship Python]: http://starship.python.net
         [ascher29]: My famous Ph.D. Dissertation, Foo University, 2029.

as being (a) easy to read and (b) easy to parse. The colon after the [..] in
the References section is syntactic sugar I would like to keep. The use of
the [..] in the References section makes it plainer (to me) that we are
talking about the same "label" as used earlier (heh, it looks *exactly* the
same!) - the colon reminds me we are "defining" it.

I would then not worry too much about what goes between the [..] - I'd be
happy for it to be alphanumerics plus underscore, hyphen and whitespace (nb:
I'd treat all whitespace as self-identical for this purpose!), or for it to
be "anything except [ and ]".

On a slight divergence, I would favour allowing non-Referenced references
(e.g., the famous "[None]") to dangle happily, with the translation/checking
tool emitting a simple (short) warning about them. It also wouldn't disturb
me to have "[ text ]" regarded as Not-A-Reference (even if we allow
whitespace in references).

>PS: I'm working on updating the proposal, but I have other pressing
>    deadlines (such as getting the JPython tutorial ready for IPC8!), so
>    it may not be ready for a couple of days.

Good - without an updated proposal I can probably hold off the urge to
program...

Am I allowed to disagree with Tim Peters (may he have nice things happen to
him)?:
> You'll end up recognizing that with a regexp, like
>
>    r"^\s*Example:\s*"

No! No! Whilst I realise that any General Purpose, Released With Python tool
will probably have to use re 'cos that's all it has, *I* (for one) would
never end up recognising anything much with a regexp. Follow the One True
Way - convert to mxTextTools (gosh, I feel better now).

Otherwise, I think he's causing me to rethink my opinions on tagging code
examples (damn, I hate it when that happens). OK - granted we don't need to
tag most ">>>" code, because it's 'obvious', is it still valid to tag *test*
code? I had assumed it was, but now I'm not sure it is, because I have a
sneaky feeling Tim's doc-code-tester *wants* to test all code given as
examples to make sure they all work (or "fail in the right way"). Hmm.

Ok, that's enough. Really must do the job they're paying me for.

Tibs
--
Tony J Ibbs (Tibs)      http://www.tibsnjoan.demon.co.uk/
2 wheels good + 2 wheels good = 4 wheels good?
3 wheels good + 2 wheels good = 5 wheels better?
My views! Mine! Mine! (Unless Laser-Scan ask nicely to borrow them.)