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

[David Goodger]

on 2001-08-06 6:00 PM, Garth T Kidd (garth@deadlybloodyserious.com) wrote:
>>> Please, no! :) Just think of the mess when someone re-wraps a long
>>> directive and the .. markers get evenly distributed. Yeccch.
>> 
>> You misunderstand. I'm talking about comments only, not directives.
> 
> Directives will chew everything until an outdent, but comments won't?
> 
> I'm obviously still misunderstanding.

I'd like to keep everything orthogonal, if possible. One-liner comments seem
less attractive to me today, so it's probably "comment" directives or the
status quo. Give me a few days to mull it over.

In the meantime, can you come up with a way to assuage Tony's concerns
regarding simple ``.. `` comment starts? Specifically:

1. The inability to start a comment with ``_target text:`` or
   ``directive::``.

2. The concern about future comment-breaking (!), if we ever introduce
   another explicit markup construct. (I don't foresee the need now,
   but that's to be expected.)

>> No, an empty comment *will* add a node to the tree.
> 
> My imagination must be cramped. Why? I mean, apart from that being the
> spec. :)

I want the output to have a one-to-one correspondence to the input, so that
round trips are possible (without cheating by looking at the "rawsource"
attribute). (That's why I rejected that part of the patch. :-) I indend to
have an output formatter which produces reStructuredTest.

>> So we special-case the empty comment (== two dots &
>> [optional] space *only* on the first line?) to *not* consume
>> subsequent indented blocks?
> 
> Yes. Exactly.

OK, interesting idea. What about an empty comment start followed by an
indented non-blank line? ::

    .. 
       Is this part of the comment or not?

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