[Doc-SIG] ST and DOM

[Tony J Ibbs (Tibs)]

Edward D. Loper wrote:
> > Agreed. Some additional elements are needed for callable object
> > docstrings, though - informally, one also needs the "funcdesc"
> > (apologies for the poor name) which is made up of a
> "signature" and an
> > optional "summary-descripton" - for instance::
> >
> > 	function(fred[,boolean]) -> integer -- This is silly.
> >
> > or
> >
> > 	function(fred[,boolean]) -> boolean
> >
> > 	This is silly.
>
> I disagree.  Isn't this the whole point of inspect?  To get that
> information?  Why include it in the doc string?  That just seems
> to make things very prone to errors.  What happens if the
> signature doesn't match the real signature?  etc.

I believe it is by fiat of the BDFL, in fact - this is a factlet he
wishes to have inserted into callable object docstrings. Things like
IDLE will use it to produce a pop-up when you type the name of a
callable.

Technically, it is *not* necessarily the same information you get from
the Python code.

The first part (signature) declares information you don't get therefrom
(the return value) and also uses human readable text for the values,
which might arguably be different than their names. The second part is
meant to be the "traditional one line summary" of what the callable
does.

But as I understand it, we are considered unlikely to get a PEP accepted
if we don't cater for it. Damn - I can't offhand see a reference to it
in my saved Doc-SIG emails, but I'm sure *someone* said words to that
effect (someone, are you listening?).

> > >   * labelsection can only appear at top-level
> >
> > Needs debating - I don't necessarily disagree, though.
>
> I have trouble thinking of what it would mean for labelsections
> to appear deap within a docstring.

I'm not convinced it *does* mean anything, but it still feels like it's
not proven yet...

> > >   * anchorsection can only appear at top-level, and after all
> > >     other elements of structuredtext.
> >
> > I probably disagree. Probably.
>
> I think that if we want anchors to be available anywhere
> in a docstring, then we need to change them to be local
> markup, allow them *anywhere* that normal local markup is
> allowed, and have them be invisible.  We would probably
> also have to change the notation for them.  Then, if you
> want to do an endnote, you just include an anchor at
> the beginning of the footnote..  Something like::
>
>     <anchor>'[foo]' Foo is a dummy word.
>
> Where '<anchor>' is whatever syntax we decide to use for anchors.
>
> I'm not saying this is a *good* thing to do, but I like
> it better than allowing anchors, as they are currently defined,
> to appear anywhere.  That just seems like a hack.  And I don't
> think the meaning will be obvious to someone reading the
> plaintext who's not familiar with ST (which it *should* be).

Hmm. Maybe that's a vote for saying we'll deal with anchors as they are
now (and make them into anchorsections, as you wish) and defer the other
issue - yes, I could go for that, especially as anchors-as-they-are-now
is what was discussed and requested (once upon a time) whereas generic
anchor points wasn't.

> > >   * list items may not contain sections; but they can contain
> > >     just about anything else (except top-level-only things).
> >
> > I *do* agree (I too dislike sections in list items!)
>
> The only potential problem I can see is people wanting to
> use sections in DL items under label sections..  (e.g.,
> when describing a parameter).  But I don't think we should
> let them! :)

I agree - that's normally a "presentation" issue, anyway (as in fighting
the default presentation of browsers). And if people jump up and down
about it too much, we can always change our minds later on.

The rest of your email I am resolutely putting aside (i.e., printing) to
look at in more detail later on.

But this is Good Stuff - I think we're getting somewhere very useful.

Tibs

--
Tony J Ibbs (Tibs)      http://www.tibsnjoan.co.uk/
"Bounce with the bunny. Strut with the duck.
 Spin with the chickens now - CLUCK CLUCK CLUCK!"
BARNYARD DANCE! by Sandra Boynton
My views! Mine! Mine! (Unless Laser-Scan ask nicely to borrow them.)