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 02:29:52

Eric Niebler wrote:
> Joel de Guzman wrote:
>> 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. 
> 
> 
> Sure, blame me. ;-) This was a long time ago. I don't really remember 
> what I was thinking, but it was probably something like, "eh, this is 
> good enough." IIRC, it made the implementation simple. When you see 
> "[endsect]" spit out "</section>" or some such.

I think that /was/ good enough. The other way would have complicated the
parser significantly too (at the time). We didn't have scopes and
stacks and some such before. It was a simple text to text translation.
It's born out of practicality instead of elegance.

> That's not a good reason anymore. Feel free to change it. And then fix 
> all my .qbk files for me. ;-)

Haha :-) Right.

>> 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.
> 
> Is that a problem?

It's not a big problem, but it gets in the way and breaks the
flow of thought when you are writing docs or reading the raw
docs. That is the main reason why many people write the comment
at the right. Ask them.

>> 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!
> 
> 
> I dunno. I kinda prefer the block syntax. Works nice if your editor can 
> do brace matching, which would make it easy to select a whole section 
> and move it elsewhere.

Can't your editor be configured to match [section][endsect] too?
Many editors can. But the point is, with the syntax above, you
don't have to scroll too much. Many times you do it just to
make sure you have the proper nesting and balancing. The parser
helps you track the unbalance. Example:

     [section

     some very long text with nested sections here...

     ]

Now, which section does that last ] terminate? Ah, use the editor's
brace matching. Sure, but then you have to scroll up, perhaps
hundreds of lines, to know which section that ] is balanced with.
With the syntax suggested, or at least with the comments at the
right, you don't have to go up and down again. You know what it
terminates. With the proposed syntax, the parser even helps you
make sure that you are really terminating the exact section that
you wanted to terminate. Another example:

     [section a]

     long text here....

     [section b]

     long text here....

     [endsect a] // i really wanted to end section a here.

     long text here....

     [endsect b]

Here, the parser will catch the unbalance. It is an error.
Section b was not meant to be nested in section a. But,
with only braces:

     [section a

     long text here....

     [section b

     long text here....

     ] // i really wanted to end section a here.

     long text here....

     ]

The parser will accept this but the unwanted nesting will happen.
Yeah, it happens to me at times. The current [endsect] syntax
also has the same problems.

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