[Doc-SIG] Comments on the reST specification - comments

[David Goodger]

Tony J Ibbs (Tibs) <tony@lsl.co.uk> wrote on 2001-08-08 5:59 AM:
> Just one note - *do* we need ``.. comment::`` if we are going to
> retain ``.. `` as *meaning* comments?

Nope. You forget about ``.. comment::`` and I'll forget all about
``.. hyperlink::`` and ``.. footnote::``. Deal?

> A separate note, though - I *don't* like having a blank comment
> represented as::
> 
>     ..
> 
> (see the problem? that trailing space is damned difficult to see, and
> terribly easy to leave out in consequence).

I've redefined explicit markup starts to be two periods followed by
whitespace, which includes a newline (end of line). Ditto for the
space after bullets & enumerators.

> On the other hand, I don't object at all to *not allowing* a blank
> comment!

I think they're useful, in the rare case that you've got a comment or
directive (anything expecting indented text) followed by a block quote.
The blank comment serves to terminate the comment or directive;
otherwise the block quote would be swallowed up. A tiny but practical
wart.

-- 
David Goodger    dgoodger@bigfoot.com    Open-source projects:
 - Python Docstring Processing System: http://docstring.sourceforge.net
 - reStructuredText: http://structuredtext.sourceforge.net
 - The Go Tools Project: http://gotools.sourceforge.net