[Boost-docs] [quickbook] Comments

Subject: [Boost-docs] [quickbook] Comments
From: Joel de Guzman (joel_at_[hidden])
Date: 2007-07-29 10:35:18

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?

Out of curiosity, how many people here are already using 1.4
docs?

Regards,
-- 
Joel de Guzman
http://www.boost-consulting.com
http://spirit.sf.net