[Doc-SIG] Documentation markup & processing / PEPs

[Tony J Ibbs (Tibs)]

I said I'd get round to commenting on David's documents (now formal
PEPs - yeh!), and I still haven't had the time to read them thoroughly,
let alone formulate proper comments. I *still* aim to do that, but here
are some quick comments "to be going on with".

1. From a quick scan, I believe I could live with the results of this -
i.e., I don't think there are any show-stoppers for me (I reserve the
right to quibble later, of course, being a pedant). Given we've now got
PEPs to work against, this is a relief to me, if not to anyone else (!).

2. Somewhere, I didn't notice it in my quick scan, it would be good to
emphasise that the *primary* aim of this project is doc strings, which
are *not* (meant to be) incredibly long. This means that constructs that
only work well in long documents are not as important (they are a *nice
thing*, but not the main reason for existence).

3. I believe (as discussed earlier) that we could drop **strong**
emphasis - I think one form of emphasis is enough for almost all
purposes, especially if there are problems nesting the two forms (which
I know Edward Loper has worried about in the past).

4. There is a good description of how literal quoting works (i.e., what
characters may be adjacent to the quotes). I think this argument should
be extended to apply (suitably amended) to other forms of quoting as
well - I assume in David's mind it does already, but in the document I
browsed it wasn't explicit.

5. Did it mention whether line breaks were allowed in things? Should be
no for literals, yes for other quoted thingies...

6. I prefer not to have indentation used for main structure in the
documents - it isn't necessary in a docstring, and has locality problems
in a LONG document. Luckily Guido agrees with me. Erm, no, that must be
the other way round...

7. I *hate* the titles with "underlining" above as well as below - yuck.

8. What are the rules for how *many* "underlines" must be present for a
title - the same number as the title, end at the same column as the end
of the title, at least one...

9. DOM - my experience is that trying to use a DOM tree to do the work
in leads to madness (I'll elucidate if anyone cares, but basically it's
clearly too constraining). However, I still reckon that producing a DOM
tree as final *output* is very useful. Thus one needs to provide method
on the appropriate class(es) to emit a DOM tree - this is simple to do,
and allows one to either publicisise or not the "working" class APIs.

(useful hint: a method that takes a DOM node to "attach" the resultant
DOM fragment to (as a child) works well - from that DOM node one can get
to the document, and that provides the appropriate factory methods. It's
a little naff, in some ways, to have a side-effect on the DOM tree in
this way, but it works.)

10. Oh - terminology on ".." - don't refer to them as "comments", since
"executable/meaningful comments" is an abomination. Refer to them as
(for instance) directive delimiters, and note that an implementation may
ignore undefined directives (which has an identical effect to what
you've already described - although personally I'd prefer to get a
warning - but is not horrible sounding). It's a good thing to avoid
raising people's hackles if you don't have to...

Sorry for the brevity,
	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.)