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

[Garth T Kidd]

> >     Arbitrary text after a ``.. `` is treated as a comment.
> >
> >     I don't think this is right.
>
> I've been thinking about this also, with regards to the
> incompatibility of comments (as they are now) and subsequent block
> quotes: a block quote would be "swallowed up" by the comment. I'd
> thought of making comments one-liners, as ``#`` is in Python.

Please, no! :) Just think of the mess when someone re-wraps a long
directive and the .. markers get evenly distributed. Yeccch. In any
case, people might *want* to hand large amounts of text to a directive:

.. sidebar::

   This text will have its ident trimmed and then will be passed to a
   new Parser() instance, the output to be used as a side-bar to the
   current body text. Thank the various and sundries that we didn't
   have to prefix each and every line with a ``..``.

   And now, so that the next text is treated as a blockquote in the
   main body rather than as a blockquote in the sidebar, we dedent
   (outdent?) explicitly with a comment.

.. This comment will be represented in the output, but could just as
   easily be an empty comment, which would outdent without adding a
   node to the tree.

    Here's the block quote in the main text.

> >     way to introduce a comment is with a "proper" named directive::
> >
> >         .. comment:: this is a comment, and
> >            it continues in the normal manner
> >            for a directive.

Hmmm.

> This seems right to me too. Let's take it a bit further: we'll limit a
> comment to a single text block (i.e., up to the next blank line). A
> "multi-block comment" could use "comment-start" and "comment-end"
> directives. This would remove the indentation-incompatibility.

The Python community hasn't historically been enthusiastic about
requiring explicit start and end delimiters, and I'm very concerned that
we're making reST documents with comments look cluttered and ugly for no
real benefit. One of the reasons I'm so enthusiastic about reST is that
the syntax is wonderfully clean to read as a document. ::

  .. This is a comment

is clean. ::

  .. comment:: This is a comment.

  .. comment-start::

     This is also a comment, but the moment I needed a few more
     characters than a single line would support I was forced to
     use a completely different syntax for comments.

  .. comment-end::

is, IMHO, not. ::

  .. This is a comment that is longer than a single line could contain
     given the text editor used to create the document. Explicit end
     delimiters are not required unless the next node in the output
     is a block quote whose parent is the same as this comment, in
     which case a single empty comment can act as a suitable terminator.

  ..

is clean and explicit, uses identation as syntax, doesn't require
un-Pythonlike start or end delimiters, and reads well in the plaintext,
all in the best tradition of the 0.2.2 reST spec.

> Yes, explicit. Which brings the syntax full-circle, since the
> dot-dot-space syntax is now called "explicit markup".

The consistency hobgoblin is about to walk up and demand that since
you've eliminated the only *other* special case for .., you must make
hyperlink targets and footnotes explicit::

  .. footnote:: tag, this is some footnote text

  .. linktarget:: `link text`, target

Suddenly, directives will have leapt from being a placeholder for
whatever behaviour some *consumer* of the parser might need, to being an
integral part of the reST syntax for everyday users.

> I'm just about convinced. I'll ponder it some more. Any further
> arguments or counterarguments anyone?

Please, let's keep directives as something day to day users of the reST
markup format *never need to use*.

Honestly, since I read the reST text I've thought that we could remove
the directives directory entirely and add an optional argument to the
parser initializer which supplied a dictionary of directives that the
consumer wanted to supply the parser. The parser itself didn't seem to
need any directives for itself because the reST format was so complete
and tidy.

Even the namespaces concept can be done by the consumer, a-la Wiki link
resolution.

This whole comments as directives thing makes camels look elegant by
comparison. As you said of another idea:

	Excuse me, but, ugh.

Ugliness doesn't belong in reST. Explicit comment directives are ugly.
QED.

>> Incidentally, this would also mean that directives can use a single
>> colon as a delimiter - I think this would be easier to remember

Can't we do that already? :)

Regards,
Garth.