[Doc-SIG] ``invisible`` reST-directive

[Felix Wiemann]

I propose adding a new directive 'invisible' to the reST-syntax, which
translates to the already existing doctree element 'comment'.

Thus, comments could be written as::

    Normal text.

    .. invisible:: This is a comment.
       
       This still belongs to the comment.

    Normal text again.

IMO it's much more intuitive than the '..' syntax for comments.

When the '.. invisible::' directive is available and when it is being
used, we can start phasing out the present comment syntax.

At first, old-style comments can issue an informational system message,
so that one can start replacing old-style comments (with '..') by the
'invisible::' directive.

After some moths, we can start issuing a warning on old-style comments.

Again after some months, we can maybe change the warnings to errors
(that doesn't have to be decided now) and start allowing directives with
a single colon::

    .. image: foo.png

... which is IMO much easier to write and a little bit better to read.
(Of course, there is no need to drop support for the old syntax with two
colons.)

The new directive-syntax with one colon is only possible after having
phased out the old comment-syntax -- see the second point in
<http://docutils.sourceforge.net/spec/rst/alternatives.html#reworking-explicit-markup-round-2>.


IMO an invisible-directive would be a good way to get rid of the the
unintuitive and difficult-to-explain comment-syntax *and* the
double-colon directive-syntax.

What do you think?

-- 
When replying to my email address, ensure that the mail header contains
'Felix Wiemann'. Please don't send unrequested mails > 64 KB.

<http://www.ososo.de/>