Re: [Docutils-users] safe comment

[David G. <go...@py...>]

On Tue, Jan 22, 2013 at 6:24 AM, Peter L. Soendergaard
<pe...@so...> wrote:
> is there are way to create a completely safe comment in reStructuredText?
>
> My problem with something like
>
> .. this is a comment
>
> is that the text following ".." might sometimes trigger reStructuredText
> into not treating it as a comment, for instance
>
> .. the norm of x is given by ||x||=1.
>
> So I would like a comment where everything following the opening is
> always ignored.

That example doesn't make sense to me. It is a comment. The reST
parser will not process it at all. Why would you think otherwise?

>From the markup spec:

           Comments begin with two dots and a space.  Anything may
           follow, except for the syntax of footnotes/citations,
           hyperlink targets, directives, or substitution definitions.

So a comment is ".. " followed *immediately* by anything other than
"[", "_", "|", or a single word followed by "::".

If you want to guarantee a comment, put something at the beginning
that isn't one of the cases above:

    .. - This can never be anything other than a comment.
    .. .. Nor can this.
    .. # Nor this.
    .. . etc.
    .. ! But I think you're being a bit paranoid.

-- 
David Goodger <http://python.net/~goodger>