[Doc-SIG] Comments on the reST specification - comments
David Goodger
dgoodger@bigfoot.com
Thu, 09 Aug 2001 23:07:13 -0400
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