[Doc-SIG] Documentation markup & processing / PEPs

[Tony J Ibbs (Tibs)]

Drat - I knew I should *really* read more before commenting - getting
David to point out what I'd missed is a selfishly lazy way of
proceeding...

Mind you, point 1 *was* the most important one to say.

David Goodger made various replies to my comments:
> > 2. ...emphasise that the *primary* aim of this project
> > is doc strings...
>
> Which document are you referring to? I believe the PEPs do emphasize
> docstrings; I'll make sure to emphasize the emphasis ;-).

It may just be poor scanning of the text on my part.

> reStructuredText is neutral on that point: applicable
> to docs of any length (just use what you need). I'm
> trying hard to keep the issues separate so
> they don't get bogged down. reStructuredText deals with
> markup syntax *only*, not usage.

OK - good point.

> > 3. I believe (as discussed earlier) that we could drop **strong**
> > emphasis...
>
> I don't think nesting of inline markup is useful enough to complicate
> matters. And I do think both *emph* & **strong** are useful.

And given other people have said the same, I'll drop the point.

> > 5. Did it mention whether line breaks were allowed in
> > things? Should be no for literals, yes for other quoted
> > thingies...
>
> Inline literals:
>
> """
> Line breaks are *not* preserved; other whitespace is not
> guaranteed to be preserved.
> """
>
> If you want linebreaks & whitespace preserved, use literal
> blocks instead.
> I'll add that to the spec.

I see. *But* I would argue that whitespace preserving in inline literals
*is* important (personally, I don't care if a linebreak in an inline
literal is mapped to a single space or illegal). It's not a showstopper
(heh, I'm one of the people who argued for losing escape characters and
using literal blocks instead, so I don't think I can grumble too much if
the argument is used back at me), but I think it might be a major
inconvenience (which, he awkwardly maintains, the other would not...).

> > 7. I *hate* the titles with "underlining" above as well as
> below - yuck.
>
> So don't use them? ;->

Grumble, mumble, humph.

> The most obvious underlines are '=' and '-'. I came up with
> 'overlines' to expand their use, before being forced to use
> other underline characters.

Understood. It's not a point to refuse a PEP on, so far as I'm
concerned.

> > 10. Oh - terminology on ".." - don't refer to them as
> > "comments"...
>
> How about 'processing instructions'? (He said, half seriously.)

I don't care much what the term is (that one is OK) so long as it
doesn't imply that "ignored for meaning" terms are being used for
meaning (which "comment" did).

> > and note that an implementation may ignore undefined directives
>
> It does:

Thanks. I *definitely* need to read these things. Maybe this weekend...

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