[Doc-SIG] lightweight markup: bullets

[Guido van Rossum]

> For structuring, I think I have a set of such rules.  I'll send out
> mail about that when I've done more testing etc., but basically:
>   1. all paragraphs *must* be left-justified
>   2. all lists must be either indented or separated by a blank
>      line.
>   3. The second and subsequent line of a list item must be indented
>      further than the bullet.  All lines but the first must be
>      left-justified.
> 
>      Subsequent paragraphs in the same list item must line up with
>      that indentation level.

I like this.

> There are some more, but those are the basics required to avoid
> mis-interpreting bullets..  The only true ambiguities you get with
> rules like these are things like:
>   1. This is a list item whose second line begins with the number
>      1.  Was that "1." a bullet or part of a sentence?

Let's err on the side of caution and declare this is not a list item
unless it's separated by a blank line.

> > Really, it seems to me that such docstrings would make python code
> > *less* readable, not more.
> 
> Do you think that we should have any colorizing at all?  If so, what
> colors?  People usually talk about *emphasis*, although I really very
> rarely find it useful in docstrings (despite its usefulness in
> *email*).  The color I most often want is something to mark a token as
> a python identifier (or, more generally, to mark a string as Python
> code).

Personally, I like having the *emphasis coloring*; I care less about
coloring identifiers.  My reasoning: sometimes it's *really* useful to
be able to stress the importance of something without SHOUTING; but
pieces of source code are easy enough to recognize without coloring:
they just *look* different, e.g. foo(bar) is clearly a function call.
When it's ambiguous, I'll put single or double quotes around it
(e.g. when referencing the 'a' variable by itself) but I'm OK with
seeing those quotes in the printed documentation as well; I'm *not* OK
with seeing *emphasis* printed as "*emphasis*".

One more thing: I'd like to argue against the use of a fixed-width
font for in-line code examples.  Typically this uses Courier, whose
characters are *way* to wide for readability.  I can understand why a
fixed-width font is necessary in sample *blocks*, because *sometimes*
(though not very often) there's code that is arranged in a tabular
manner; but this argument doesn't apply to in-line code samples.

> If we didn't do any colorizing, we would probably have:
>   - paragraphs (in which word-wrapping is legal, etc.)
>   - literal blocks (which are displayed as-is)
>   - doctest blocks (which are displayed as-is, or possibly colorized)
>   - lists (ordered and unordered)
>   - sections (and subsections)
> 
> If there was no colorizing, I'm pretty sure we could get away with no
> escaping mechanism (with carefully chosen structuring rules, it would
> never be necessary).

But I want an escaping mechanism.  I want to be able to say e.g. "When
I write "*foo*", all its characters are rendered, including the quotes
and the stars, but when I write \*foo*, it is rendered in italics."
(In other words, I want to be able to give an in-line example of the
"*foo*" notation.)

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