Re: [Boost-docs] [quickbook] Comments

Subject: Re: [Boost-docs] [quickbook] Comments
From: Kai Brüning (kai_at_[hidden])
Date: 2007-07-30 07:15:06

>Hi again,
>
>There was a small experiment on comment handling in 1.4 (current)
>where comments are nestable, like pascals, but unlike C. The
>problem was that the original quickbook comment syntax is not
>usable for commenting out chunks of Qbk. The problem was that
>the comment ends with the first ']'. So, we can't simply comment
>out a whole chunk because the chunks, almost always, contains
>lots of ']'. So, what I did was try to find the next balanced
>']' instead of the first. Works fine, most of the time, unless
>you have some extra ']' in there (probably escaped, or in code,
>in strings, etc.). There's no way to reliably do it short of
>re-implementing the entire Qbk parser for comments!
>
>Rene noted that a better solution. Keep the non-nestable comment
>syntax (ala C) but choose a unique terminator. He suggested:
>
>[/ this is a quickbook comment /]
>
>I think this is the best suggestion so far. However, it is,
>again, breaking.
>
>Anyway, now that we are talking about breaking code for 1.4
>(or 1.5 as John suggests), perhaps it's time to implement it
>this way?

One additional aspect: Nestable comments can't be catched by a single regular expression.

I am currently implementing syntax hiliting of quickbook files for the Pygments syntax highlighter. Using regular expressions and states, the nestable comments in 1.4 forces a lot more states because comments can be nearly everywhere.

I wouldn't rate this important, but everything else being equal, the easier handling of non-nestable comments with regular expressions may be of value in a variety of cases.

Regards
Kai