[Doc-SIG] lightweight markup: bullets

[Edward D. Loper]

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

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.

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

Again, I very rarely find myself needing to do this in docstrings.. But
maybe I'm not a representative sample.

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

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

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

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

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

Well, as I said *if there's no colorizing*, we don't need escaping.
The second you introduce *emphasis* colorizing, or any other colorizing,
we do need some type of escaping mechanism.  And then we can talk about
various escaping mechanisms (I've seen 3 workable ones: backslashing of
some sort (e.g., \*); using X{..} notation (e.g., E{*} or E{lb}); and
using a literal coloring (e.g. '*' or `*`).. Of course, the last one's 
not as complete, since you then can't include the literal character 
inline..  but at least that's 1 character instead of all the markup 
characters.

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

-Edward