[Doc-SIG] lightweight markup: bullets

[Edward D. Loper]

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

Ok, you're right.  But I *still* think that we should defer that issue, 
given that we can.  I'd like to get a markup language that we can all
play with for a little while first, and then talk about how to add
colorizing.. The only way that colorizing should be non-backwards-
compatible is when you need to escape things.

> > How would you like to see *emphasis* rendered in a tty environment?
> [...]
> 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!)

Agreed (not to mention that sometimes such fancy features as inverse
video are not available).

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

Agreed.  Although if the tool wants to be nice, and try to avoid 
breaking in-line code, it's free to.  But the markup language says
that any in-line code *can* get broken at spaces.

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

Ok.  Does anyone have objections to using Javadoc-style @ notation?
Any votes on which of the various notations I wrote out that we should

I was looking at the emacs java-mode, to see how they do colorizing
in docstrings.  It looks like they just colorize things like 
"@param x" and "@author" *wherever* they occur (assuming that these
will appear rarely, if ever, in actual source code; and that when
they do, it will be fairly harmless anyway).  Would we be ok with
doing something like that?  Of course, IDLE could in theory be much
smarter about it..  (And if we did eventually put something like 
this in emacs python mode, it would certainly be something you can
turn on/off).

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

Ok.  I'll err on the side of being strict then.

One advantage of being strict is that it greatly reduces the need
to hand-check the parser's output..  as long as running::

  pytext.check_docstrings(module)

or whatever succeeds, you're most likely fine.

-Edward