On ordered Lists (was RE: [Doc-SIG] Formalizing ST)

[Tony J Ibbs (Tibs)]

There seem to be a lot of follow-ups in the headers - I've left them
intact just in case. Apologies to anyone who would prefer I hadn't...

Peter Funk wrote:
> I meant the following 2 EMails written by Guido: In
> 	http://mail.python.org/pipermail/doc-sig/2001-March/001584.html
> Guido replied on an email from me:
> > > I think, a description list can be dropped alltogether.
> >
> > Yes!  They are darn ugly in HTML anyway.

Sigh. Judging a construct by how IE and Netscape present it is not a
very good way to do it. Full stop. (analogy: Renoire artistically
judging a subject by how my five-year-old renders it)

    (I *assume* that's what he meant - if he actually
     meant what he *said*, which is that
     `<dl><dt>..<dd>..</dl>`
     is ugly, then I really despair.

     'cos, like, who could care - only people like me
     actually *read* HTML).

Besides, we've no requirement *at all* to accept that presentation - the
descriptive list is the *internal* construct, how that gets turned into
(for instance) HTML is in our control (well, the tool writer's control),
and it's only after that the browser gets its hands on it. Even before
style sheets this was a valid way around the problem (one could, for
instance, use tables, or bullet lists with the description formatted as
the first paragraph - you get the idea). And with style sheets the
document creator gets a *lot* of latitude, even if a standard construct
like `<dl>` *is* used.

As I believe I've said elsewhere, I think Guido must have been having a
bad week - it doesn't sound like the BDFL I've learnt to trust to miss
the abstraction and focus on the (particular) implementation.

Dammit, even in his "style sheet" (why won't he finish that?) he uses a
descriptive list! (if it looks like a fish and walks like a fish, it can
ride a bicycle like a fish, or something like that.)

> > > At least for the time being a bullet list will be enough.
> >
> > Agreed.

No. And I will keep fighting this, as I'm sure will other people (other
people, anyone, please). After all, that's why we have the SIG!

Guido is allowed to be human. He is allowed to be wrong. He is allowed
to be *misinformed*. And he is definitely allowed to be convinced of a
different opinion.

He just gets the final overriding vote (on a PEP - which we haven't
produced yet), and it is an item of faith that he only uses that "in
extremis".

> Later in
> 	http://mail.python.org/pipermail/doc-sig/2001-March/001595.html
> he wrote as a reply to mailto:edloper%40gradient.cis.upenn.edu:
> > > Well.. I'm not sure whether we'd want to do that or not.. We
> > > may be happy with just using '1.' and assuming that no one will
> > > start a line with a number that ends a sentence..
> >
> > That was ST's original sin.

Again, sigh. This is the same (beloved, of course) person who was
proposing we look at MoinMoin for ideas, which (for good reasons in
context) uses a *horrible* hodge podge of markup mechanisms. And he
castigates the ST family for this.

(and it's by far not the *worst* "sin" in ST's books, surely)

Whatever markup scheme we adopt, I can guarantee you it will have
infelicities - especially if it "reads" like more-or-less natural text.
People will have to know about those infelicities.

As I said, a bad week.

> If INDENT and DETENT tokens are part of a
> upcoming EBNF docstring grammar,  I think it might be
> possible to come up with rules for ordered and descriptive
> lists later on, which will not suffer from ST patterns
> which trigger in error.

I'm not convinced, myself, because we probably *can't* mandate exactly
how people lay out paragraphs. For instance, consider the variation in::

    Some text.
    This is more of the same.

      Some text.
    This is more of the same.

    Some text.
      This is more of the same.

and (addressing lists themselves) in:

    Some text.
    1. This is a list
       and I continue here.

    Some text.
    1. This is a list
    and I continue here.

    Some text.
    1. This is a list
      and I continue here.

    Some text.
       <<all of the above list formats,
       but indented a little bit>>

I don't see how we can stop people doing any of those (I bet if our
format *tries* it will be either ignored or not used "properly"). That's
one of the reasons I advocate ignoring indentation within paragraphs.
The *only* way round that would be to require blank lines in front of
list items, and that's a no-no for other reasons (well, we discussed
that last time round the Doc-SIG loop).

Besides, if people *really* find this a problem, we will just need to
make sure that the tool implementing the spec looks out for possible
problem cases, and that it can *warn* the document writer they may have
a problem.

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