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

[Beni Cherniavsky]

David Goodger wrote on 2004-06-01:

> Felix Wiemann wrote:
>  > For a reader unfamiliar with reST, 'comment' would be almost as
>  > confusing as the existing '..' syntax.
>  >
>  > 'comment' is only appropriate when thinking of reST as a 'real'
>  > language.However, it's rather a simple markup syntax, and at least
>  > it shouldn't look like a language (as opposed to LaTeX, for
>  > example).Thus, 'invisible' describes more obviously what it does.
>
> I'm not convinced.reST is as real a markup language as any other,
> and for better or worse,the accepted term in every markup language I
> know of is "comment"."Invisible" makes me think of the old HTML
> <blink> tag, or of text rendered with the foreground color set the
> same as the background color ("spoiler" text that you have to select
> to read)."Comment" is a precise and accurate term.  Let's not
> innovate needlessly.
>
I'm also -1 on ``invisible``, because it's not WYSIWYG - it *is*
visible in the source, which looks pretty confusing IMHO ;-).

I'm about +0.5 on adding a comment directive at all (as ``comment``).

BTW, if I remember the ``..`` vs. directives rules about empty lines,
writing ``.. comment::`` now is not entirely equivallent to a real
directive.  That's a point in favour of adding a real directive (and
not saying "you can write ``.. comment::`` (or anything else) and it
will work even today).

I'm -1 on phasing-out ``..`` due to backward-compatibility.

-- 
Beni Cherniavsky <cben at users.sf.net>