Reasons to do this (was [Doc-SIG] Re: Ho hum - back to work...)

[Tony J Ibbs (Tibs)]

Edward D. Loper wrote:
> > B. Reasons to be doing this
> [Summarized:]
>   - NOT: we don't need to invent a markup language
>   - DOC: we want to be more expressive in our docstrings
>   - REP: we want to be smarter about displaying docstrings
>   - STRUC: we want to be able to do smart things with our
>            docstrings (other than displaying them).
>
> I would say that for me, your REP and DOC would be my most important
> reasons for this work, probably in that order.  The reason that I put
> REP above DOC is because I think that the need for standardization is
> much less for DOC than it is for REP.

Interesting. For me, the order is quite close anyway, so I think this is
agreement.

> > I'm not sure I actually believe that we're going to get a lot from
> > STRUC
>
> One thing we get is the ability to check for certain completeness
> criteria in our documentation.. e.g., did I specify a return
> value/type for everything that returns something?  did I describe
> every parameter?

Which is *not* the classic thing people claim to want from STRUC - they
normally seem to be asking for the ability to extract information for
querying.

*If* we are primarily interested in DOC and REP (survey of 2 people, so
terribly significant) then I think that has repercussions. I need to
develop my ideas on this a bit more.

(It seems worth noting, to me, that if STRUC were the main reason, then
the use of __version__, __author__ (and potential others), and the way
that the Types SIG looks like allowing string annotation of typed
argument values, would seem to make its case a LOT less strong. And if
REP/DOC is our main aim, we need to consider what it is that we object
to about what pydoc does (which is a brutal rendering of the text as
written, with URIs guessed at) - an extreme position would say that
structuring was unnecessary and only the markup/colourising was
needed...

Hmm - I'll think about trying to expand on these things, since they seem
to be useful potential ammo for (a) convincing ourselves, (b) convincing
others...)

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