[Doc-SIG] lightweight markup: bullets

[Guido van Rossum]

> > Let's err on the side of caution and declare this is not a list item
> > unless it's separated by a blank line.
> 
> Ok, I'll change it.  But in any case, it will generate a warning, since
> it's potentially confusing (it will recommend that they move the "1."
> to the previous line or the "number" to the next line, or that they
> add a blank line if they intended to start a new list item).  It also
> generates warnings for things like::
> 
>   The following was probably a mistake:
>   - This is not a list item.
>   - Neither is this
> 
> and::
> 
>   The following was probably a mistake:
> 
>   - This is a list item;
>   but this is a new paragraph, not
>   a continuation of the list item.

Good.

> > 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; 
> 
> Again, I very rarely find myself needing to do this in docstrings.. But
> maybe I'm not a representative sample.

Grep through Lib/*.py for ' \*[a-z][a-z]*\* '.  Lots of examples (some
in comments, but those are also documentation :-).

> > 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; 
> 
> It can be nice to have code colored for other reasons, but I don't 
> think it's really a necessity..

Agreed.

> > I'm *not* OK with seeing *emphasis* printed as "*emphasis*".
> 
> How would you like to see *emphasis* rendered in a tty environment?
> Like "*this*"?  Or just like "this", since emphasis should never
> really be *necessary* to make your point?  This would apply to any
> tool that tries to print marked-up documentation from within
> Python, for example (similar to "help").

Since I went to the trouble of typing it, I'd like to see it rendered
one way or another.  Rendering as *foo* is fine.  (Much better than
inverse video!)

> > 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.
> 
> Yeah, I had been thinking about that, and I agree.  But of course that's
> mainly a tool issue, not a markup language issue.  (though not entirely).

I know, I just wanted to throw it out while I was thinking of it.

> On a related note, I've been thinking that all spaces in in-line
> code should be soft.  If you really need "x  y" to come out with 2 
> spaces in it instead of one, you should use a literal block.  I'm undecided
> about whether spaces in in-line code should be breakable.. Maybe leave
> that a tool issue.

Agreed, and I do think spaces in in-line code should be breakable.  I
write a lot of email with in-line code samples, and I often have no
choice in letting it break -- and if I don't want it to be broken,
I'll make it a block.

> > > 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)
> 
> I forgot to mention "fields," which allow you to do things like describe
> individual parameters, or the return value, or a class's instance
> variables, etc.

The Javadoc-style @ notation makes sense to me here -- as you showed,
trying to do this without markup can be plain confusing.

> But I think that, for now, it makes sense to postpone discussion of
> *both* colorizing and escaping (since they're clearly related) and to
> try to come up with a good definition for how we want structuring to
> work.  Currently, the only open questions in my mind are where to draw
> the lines between errors and warnings,

I say be strict.  The tool should always be available and we should
tweak all our docstrings until the tool is happy.

> and how to write fields in such a
> way that they won't conflict with normal English usage.  Any feedback
> would be much appreciated.  I'll try to put up a link to my parser
> sometime soon, but it's getting towards the end of the semester, and I'm
> a bit swamped with projects. :)

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