[Doc-SIG] Re: ``invisible`` reST-directive
Beni Cherniavsky
cben at users.sf.net
Thu Jun 3 16:07:46 EDT 2004
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>
More information about the Doc-SIG
mailing list