Re: [Boost-docs] [quickbook] Comments

Subject: Re: [Boost-docs] [quickbook] Comments
From: Joel de Guzman (joel_at_[hidden])
Date: 2007-07-29 15:00:09

John Maddock wrote:
> Joel de Guzman wrote:
>>> 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.
> 
> I've had a need for that in the past, but can't we avoid breaking old code 
> with a new "block-comment" template, maybe:
> 
> [template ##[args]]
> 
> Would that let us use [## ... ] to comment out blocks?  or can't we have ']' 
> as an argument to a template?  Hmm, no maybe not...

Well, the current behavior of 1.4 that finds the next balanced ]
does it quite well with minimum disruption to old code. If we
want that (minimum disruption), then the current 1.4 strategy is
the best. It's similar to pascal's nested comments. Thus:

     [/ this [*is] a comment ]

parses ok as one whole comment. With the 1.3 behavior, the
comment ends at the first ] (after "is"). IT is ok, because
1.3 files do not write comments that way anyway. So the
nested pascal-style comments is, fortunately, both upward
and backward compatible.

This one only breaks on rather obscure text like:

     [/ this is a comment with a ']' in it ]

the (spirit) rule that extracts the balanced [] is not that
smart. Giving it a sure-fire smartness will mean no less than
making it parse QB blocks and phrases and throw away the
output. (Hmmm that's a possibility, will get back on that).

> Just an idea, John. 

Another idea might be to use another syntax. Example:

     [// this is a comment //]

it really does not hurt to type in the double slash. It's just
a simple tap-tap on the keyboard, and marginally slower than
the single tap. There are no shifts, like say, & (shift-7 on
my keyboard).

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