[Doc-SIG] Ho hum - back to work...

[Tony J Ibbs (Tibs)]

Well, I recovered from my flu (eventually) and am now back to "normal".

One of the interesting side-effects of the flu, though, was its ability
to purge the mind. I'm afraid I've come out of the illness with much
less interest in the Doc-SIG than I went in with - it's very difficult
to see, from the standpoint of now, why I was insane enough to devote so
much time to something that, perhaps, not so many people really care
about, when I could instead have been reading, ironing, making my Debian
system work, talking to Joan - oh, all sorts of things. This means I am
unlikely to be as active as I was, particularly since I'm expecting to
be quite busy with some interesting things at work as well.

It's also why I've been refraining from comment on the "structure"
discussion - I just don't have the time at the moment to spend an hour
in the morning on Doc-SIG.

Anyway, to the point. I'm taking tomorrow (and maybe a day next week)
off to do *some* work for the effort. It's a bit short notice to ask
this, but given all the work that Edward and David are doing (I don't
necessarily *agree* with them, but that's another matter), I figured I'd
seek an opinion on how my time might best be spent.

There are two main options:

1. My original promise - get a version of docutils/fat.py working as a
testbed. It would come with lost of command line switches to try out
various ideas, and would try to incorporate some of Edward's structuring
options (although note that *I* am not going to code *anything* that
supports C{something} or C<something> markup, as I consider this an
abomination). It would be suitable for running over the standard library
to see how well *that* renders when passed through a markup engine (this
seems like a very important point to me!).

2. Work on the Doc-SIG archives, to try to produce summaries of the
arguments from its lifetime. Note that (technically) we may need this
for any PEPs we produce! (and it would clearly be useful to be able to
*point* to who said what and why, given the history of the group).

Option 1 (a) probably needs doing anyway, and (b) fat.py is probably
likely to be the only tool that supports multiple ways of doing things,
to allow users to *compare* them (which seems valuable to me).

Option 2 is actually more tempting (I've done this sort of thing before,
and it's a lot of work, but can be very worthwhile). I think this
*needs* doing at some point - we don't want to lose useful wisdom from
the past.

Two separate questions, as well (if answering these, please start a
separate thread for each?)

A. Content markup pedagogy.

I still don't understand why Edward (and Guido, although I think he's
less likely to answer!) object to "simple" markup like ST and relatives
use - why they consider it a Bad Thing to (a) use punctuation characters
for markup, and (b) use them in a context dependent manner. The last, in
particular, bugs me, as I *really* don't understand what the problem is
(after all, I *read* text in a context dependent manner). An explanation
of the object, in simple terms, would be a nice thing to have for me,
and might be useful pedadgogy in the eventual PEP discussions.

(As a subpoint, I don't *quite* understand why Edward wants to separate
structuring and colourising so much - this seems to me to be
implementation detail (for this purpose, I consider the EBNF to be
"implementation" as well) - real people don't have trouble with fuzzy
distinctions about such things.)

B. Reasons to be doing this

The Types SIG defines several different (possible) reasons for wanting
to produce type annotation, etc. I think it might be useful to produce
similar distinctions for Doc-SIG. So here is a tentative list of *why*
we might do this work:

NOT --- We might *not* do this work because we think that informal plain
text, with pydoc *guessing* what to link to what, is sufficient. This is
a not entirely unreasonable point, as pydoc does a reasonably decent job
(I've been looking at the HTML it produces, and why it's too small to
read, which is why I didn't say "excellent job"!) of presenting the
plain text from doc strings.

DOC --- I personally want to be able to markup the text to get across
more meaning (e.g., I *do* want emphasis, but I also want to be able to
annotate an argument list as such, and indicate what is literal text,
etc.). This is tool independent. It is an advantage to standardise on
one form of markup, even for DOC, because that makes it easier for other
people to read my marked up text.

REP --- It is nice to be able to present a DOC string with a little more
intelligence than is possible if it is treated as just plain text. The
main thing I want here is actually distinction of literal text (be it
inline or not) from "plain" text. Given I like to have emphasis, it
would be nice if that is recognised as well. Note Eddy's point that we
are *not* after "professional" quality of presentation here - just
something easier on the eye than plain text.

STRUC --- One might imagine that there are uses for marked up text,
since one could extract information from it. This relies on use of
"Arguments:" and other tags, as well as (perhaps) using hints like
`#..#` to indicate what one *does* want links generated for. Of course,
it is only if the markup scheme is widely adopted (and used
consistently) that one gets much benefit from this.

Have I missed any options? To me, DOC is the most important, with REP
following. I'm not sure I actually believe that we're going to get a lot
from STRUC (*except* making it easier to guess that I *didn't* want this
"London" to refer to a class, but instead just meant it as plain text).

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