[Doc-SIG] Comments on the reST specification - comments
David Goodger
dgoodger@bigfoot.com
Mon, 06 Aug 2001 22:53:03 -0400
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