[Doc-SIG] suggestions for a PEP

[Tony J Ibbs (Tibs)]

Edward D. Loper wrote:
> > in new code as well!
>
> Um.  So did I.  I'm not sure where you got the impression that I
> didn't.  Hopefully having special places to describe arguments is
> useful in new code?  I wasn't even thinking about the std library..

Erm - sorry, probably "too early in the morning"-itis

> > Aagh! Quick, do a "from __future__ import docutils" 'cos that's all
> > being addressed in the alpha release and *it's already coded*.
>
> So, my main objection to this format (given that I'm the one that
> has to formalize it) is that it means we're giving meaning to
> yet another character: ':'.  I read through the list archives, but
> didn't seem to find eventual consensus.  But if we're going to have
> it, here's how I would *like* it to be defined:
>
>   1. *Any* paragraph starting with '\w+:' is a "label paragraph."
>   2. Any ':' in any other location is treated as a normal ':'
>   3. It is illegal for a label paragraph to contain a newline.
>   4. If a label paragraph has (non-space) content after the ':',
>      then that is parsed as the only subparagraph of the label
>      paragraph.
>   5. If a label paragraph does not have content after the ':',
>      then following indented paragraphs are subparagraphs.
>   6. If a label paragraph has content after ':' *and* is followed
>      by indented paragraphs, then... I'm not sure.  Could be illegal.
>      Could all that the following paras are children of the para
>      that's on the same line..  Ideas?

Off the top of my head, I *think* the rules it works by are remarkably
similar. I *don't* think it enforces the "any paragraph with label-chars
then a colon must be a label paragraph to be valid" (although in
validation mode it maybe should). I'm fairly sure that if it is a
one-line paragraph with text after the colon, then it *will* grumble
(again, in validation mode) if there are subparagraphs.

[beware that in non-validation (passthrough) mode docutils will try to
"do something sensible", since it is very frustrating for an end-user to
be unable to get documentation out because the documentation writer made
mistakes, and because there are applications (like, maybe, Wiki pages)
where there is nowhere for the validation messages to go.]

STpy, on the other hand, should define non-valid occurrences *as*
non-valid (whilst not forbidding the existence of "passthrough" tools).

> > OK. The rules for "paragraph labels" (I changed the term) are fairly
> > simple. Basically, there are two dictionaries::
> >
> > 	label_dict = { "Label" : "xml-label" }
>
> If we're going to be xml-like in specifying contents, then we
> might want to consider using actual xml DTD-like strings to
> specify this (so "Label" : "ANY").  :)

I had thought about something like that, and dithered...

Basically, allowing absence to mean "anything" means that someone
defining a new profile who honestly doesn't care about validation (in
this manner) need do nothing, which swayed it for me.

> > I decided *not* to complicate matters
> > by allowing::
> >
> > 	Label:
> > 	    Only indentation makes this look like a paragraph.
> >
> > because there are already enough rules about when paragraphs start.
>
> Agreed.  Although this is bound to confuse people.. :)  But
> according to my rules, it will produce an error if they have
> error checking turned on..

I can't see a way out of confusing people in some circumstances,
unfortunately. It *is* possible that future releases (of STpy and
docutils) might relax this, but I'm not convinced it's worth the
think-space.

> > This fits in reasonably well with David Ascher's original ideas
> > (thrashed out at the end of 1999), and to my eye the use of
> a colon is
> > more natural than overloading descriptive lists.
>
> Again, I don't like giving even more meaning to ':' when we could
> just give '--' the same meaning, and say it's a "tool issue" to
> decide whether a key has special meaning..  But as long as we
> give ':' special meaning *only* and *always* when it appears directly
> after the first word in a paragraph, I can accept it.

Whereas I don't like reusing '--' for something that *isn't* a
descriptive list (these things fit in a different place in my head, but
maybe not in yours). On the other hand, the use of the colon *was*
always specified as being so restricted.

> > More explanation can (please) wait until the alpha release, which I
> > *hope* will be end of next week, with the PEP.
>
> Looking forward to it.  If my emails take too much time to answer,
> just punt them for now. :)  I've been trying to get some answers
> out of your source code, but I don't have the time to figure out
> everything that's going on in there..

So far, all the emails I've been answering (no matter how fast and
carelessly) have been useful for clarifying stuff in my head. And I've
printed out this last one, because I want to check my implementation of
the labeled paragraphs against your list.

> > > I think it will be helpful to people if we can get this
> streight now.
> >
> > Yes, but can now be next week, 'cos then I won't have to
> explain things
> > *quite* so many times, please?
>
> Yes, I was thinking of "now" as "before the PEP is accpeted." :)

Oops - sorry. Another artefact of being in a hurry.

> I didn't think this was possible, because the following fails::
>
>   B.f.__doc__ = A.f.__doc__
>
> But really you have to do this:
>
>   B.f.im_func.__doc__ = A.f.__doc__

Well, I didn't realise that, but (a) that counts as "works" (for an odd
value of "works", admittedly) and (b) it may change with function
attributes - don't know.

> It might be worth mentioning this in documentation, because I
> think that the whole idea is not quite intuitive, and it's something
that the
> code writers would have to do..  So we should suggest that they do it
> when applicable! :)

Oh definitely - can I leave you to remember it, though?

> Time travel's fun! :)  But I'm sure you've been through all
> this too many times to count.  I'm a bit new to all these issues,
> so if I seem dense sometimes, please forgive.. :)

Well, it's only twice at most, and new ideas *do* keep coming up all the
time, and besides, all the newcomers this time round are *very
valuable*.

Hmm. The next two emails actually require some coherent thought to
answer (stuff about quoting and '#...#' and so on), so I'll defer them
for now.

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