[Doc-SIG] ``invisible`` reST-directive
Felix.Wiemann at gmx.net
Mon May 31 12:58:13 EDT 2004
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::
.. 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
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
The new directive-syntax with one colon is only possible after having
phased out the old comment-syntax -- see the second point in
IMO an invisible-directive would be a good way to get rid of the the
unintuitive and difficult-to-explain comment-syntax *and* the
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.
More information about the Doc-SIG