Re: [Boost-docs] [quickbook] Comments

Subject: Re: [Boost-docs] [quickbook] Comments
From: Paul A Bristow (pbristow_at_[hidden])
Date: 2007-07-29 11:23:46

>-----Original Message-----
>From: boost-docs-bounces_at_[hidden] 
>[mailto:boost-docs-bounces_at_[hidden]] On Behalf Of Joel de Guzman
>Sent: 29 July 2007 11:35
>To: Discussion of Boost Documentation
>Subject: [Boost-docs] [quickbook] Comments
>
>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.

In particular, it breaks the [endsect][/section:overview Quickbook Overview]

style that I have used to make clearer, especially to me, the nesting of sections.

So it would means LOTS of edits :-(

I am also concerned that one can all too easily comment out big chunks by forgetting the 'closing' /

However that is not such a serious problem as commenting out big chunks of code  with mismatched /* */  Been there done that? ;-)

I'm not quite clear where, in 'real life', one would want to comment out chunks of stuff including ]s?

Paul
---
Paul A Bristow
Prizet Farmhouse, Kendal, Cumbria UK LA8 8AB
[phone] & SMS, Mobile [phone] & SMS
pbristow_at_[hidden]