[Doc-SIG] Re: changing comment & directive syntax

[Edward Loper]

Felix wrote:
> Thus, comments could be written as::
> 
>     Normal text.
> 
>     .. invisible:: This is a comment.
>        
>        This still belongs to the comment.
> 
>     Normal text again.

I brought this up before, and I'm still +1 on it.  I don't feel very 
strongly about the name.  "comment::" makes the most sense to me, but 
I'd be ok with "invisible::" or "ignore::" or something like that, as well.

How's this...

   1. Add a new comment:: directive (or whatever you want to call it).

   2. Change the docs to encourage people to use the new directive for
      comments.  (I.e., under the ".." comment syntax, add a note that
      the prefered way to mark comments is with the directive.)

   3. Put of the decision of whether to phase out the old ".." syntax
      for comments until later.  I'm +1 for phasing it out eventually,
      but it's worth waiting to see if people like the new syntax and/or
      if people start editing their old documents to use the new syntax,
      before we make decisions about phasing out the old syntax.

-Edward

p.s., another good property of adding it as a directive instead of just 
"..": it gives people a keyword to search for, when they encounter it 
for the first time.