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

[David Goodger]

[I wrote]
>> I'd thought of making comments one-liners, as ``#`` is in Python.

on 2001-08-05 6:26 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.

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

No, an empty comment *will* add a node to the tree.

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

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

> 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

Actually, I *was* thinking about this, adding explicit directives for
footnotes and hyperlink targets. But I would leave the ``.. _whatever:`` and
``.. _[whatever]`` syntax as shortcuts. Don't panic; read on.

>>> 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? :)

No, because of comments like ``.. Danger: panic imminent!``.

Anyhow, don't worry (yet). I'm just thinking out loud about interesting
alternatives that *might* solve a tiny little wart, but possibly at the
expense of introducing a much larger mole. Any proposed change will get a
full hearing first.

Thanks for your input.

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