Re: [Boost-docs] [quickbook] Comments

Subject: Re: [Boost-docs] [quickbook] Comments
From: Joel de Guzman (joel_at_[hidden])
Date: 2007-07-29 12:03:59

Paul A Bristow wrote:
> 
> 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 :-(

Yeah :(

Oh, BTW the proposed syntax for that is:

     [endsect:overview Quickbook Overview]

where ":overview Quickbook Overview" is optional and if present
makes Qbk check for balanced section/endsect. How many times have
you been bitten by this? Me, lots!

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

Sure, but that's easy to detect. It's also easy to comment out
big chunks by forgetting the 'closing' ] in the current behavior.

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

Been there done that.

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

Good question. For me it happens when I want to temporarily
disable a chunk of text that I want to reuse later, somehow, but
I don't know what to do with at the moment. I'm sure others
have other uses.

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