Re: [Boost-docs] [Quickbook] Templates and Namespaces

Subject: Re: [Boost-docs] [Quickbook] Templates and Namespaces
From: Joel de Guzman (joel_at_[hidden])
Date: 2007-08-02 00:12:56

Matias Capeletto wrote:
> On 8/1/07, David Abrahams <dave_at_[hidden]> wrote:
>> on Wed Aug 01 2007, "Matias Capeletto" <matias.capeletto-AT-gmail.com> wrote:
>>
>>> [namespace math]
>>>
>>>    [template formula ....]
>>>
>>> [endnamespace]
>> I hate this kind of XML-ish syntax formulation.  We have brackets that
>> can be matched; let's use them.
> 
> I agree with you. Why it was decide to use [endsect]?
> I was only proposing something that looks similar to the actual
> syntax, but I dislike the name endnamespace a lot.

This was Eric's design decision. I'm CC'ing him. I too don't quite
like XML-ish syntax formulation, but for long stretches of text,
it certainly helps. If we strictly abide with the end-bracket,
we'll end up with something like:

     [section stuff

     lotsa text here....

     [section sub-stuff

     and lotsa more text here....

     ] [/ sub-stuff]
     ] [/ stuff]

which kinda reflects what we do in C++. For verrryy long stretches of
text, we'd hope the author writes the trailing comment. Otherwise,
we'll have to scroll back and forth figuring out the nesting.

Right now, we have:

     [section stuff]

     lotsa text here....

     [section sub-stuff]

     and lotsa more text here....

     [endsect] [/ sub-stuff]
     [endsect] [/ stuff]

which also does not require the comment. Again, if the author skips on
the comment, we have difficulty figuring out the nesting.

Now, my proposed syntax is:

     [section stuff]

     lotsa text here....

     [section sub-stuff]

     and lotsa more text here....

     [endsect sub-stuff]
     [endsect stuff]

which makes it explicit and clear which starts and which ends. This
also allows the parser to catch improper nesting. This also makes
it more xml-ish!

In the end, I'd say my opinion on this is that the xml-ish syntax has
its uses, especially on very large marked-up blobs.

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