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

[Guido van Rossum]

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

Given that IE and Netscape are what 99% of our users use to view
documentation, I don't see why this argument is rule out.  Remember,
practicality beats purity.  You seem to argue for the purity side of
things.  And I don't believe the Renoir (sp!) reference is relevant at
all.  IE and NS are not your five-year-old.  They are the front page
of your city's newspaper.

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

Except that the problem is that typically there's *no* decent-looking
way to present such lists.

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

I can do without this particular abstraction.

> Dammit, even in his "style sheet" (why won't he finish that?)

Lack of time, like so many other things.

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

Note that I don't need semantic mark-up for my descriptive lists --
the English language, punctuation and bulleted lists do all that I
want.

An argument against too much abstraction in the current discussion:
the core idea of ST is that the source looks sufficiently like the
output to be readable without any processing.  I'd rather not have a
tool that tries to extract an abstraction and lays it out completely
different in another medium, because that means what I think looks
right in plain text will suddenly look wrong on the user's screen.
Giving the renderer too much freedom IMO makes it harder for the
author to do the right thing.

Really, I wish we could use WYSWIG for docstrings -- that would be so
much better!  But program text editors don't allow that yet... :-(

> 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!

So please write down exactly which forms of lists you want.

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

I am so glad you aren't telling me what to think or do.

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

Well, actually, if I vote your PEP down, that doesn't have to stop you
from using it anyway in your own code.  And if you can convince enough
other users to follow your conventions, I may be convinced.  This is
different than a language change, where I really *do* have the last
word!

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

Except if it *is* plain text.

> As I said, a bad week.

For you, or for me? :-)

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

Or my preference:

    Some text.

    1. This is a list item
       continued here.

    2. This is the second item.

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

Hm, I must've missed that.  It seems reasonably enough to me (I wrote
the above before reading on).

--Guido van Rossum (home page: http://www.python.org/~guido/)