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

Subject: Re: [Boost-docs] [Quickbook] Templates and Namespaces
From: Matias Capeletto (matias.capeletto_at_[hidden])
Date: 2007-08-02 11:31:07

On 8/1/07, Joel de Guzman <joel_at_[hidden]> wrote:
> 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.

Great, I love this willing to do things right :)

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

I state it again here, we are a small community now, and a very active
one. I am willing to fix others docs (and I know a lot of folks from
IBD will work on this too) in order to make quickbook syntax more
comfortable and consistent. The time for changes is now, I do not
think it will be possible to be this flexible in a near future.

> Can't your editor be configured to match [section][endsect] too?

boost::hs can match it, but I really think we should change this.
"endsect" is just another reserved word the user has to learn.

> <snip> ( problems with unbalanced sections, named endsect )

> 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.

What about something like:

   [section:sid Section Title
   ...
   ]

And optionally you allow the user to include the id of the section:

   [section:sid Section Title
   ...
   :sid]

I think it solves both issues. We have to check other blocks construct
if we follow this path. For example, the doc type block. I think it
will be better like:

   [article:aid Article Title
   [quickbook 1.4]
   [copyright ...]
   ....
   [category ...]

    ....
    Article body...
    ....

    :aid] [/ End of the article /]

Or if you want to have an information block:

   [document:id Article Title
   [info
       [doctype article]
       [quickbook 1.4]
       [copyright ...]
       ....
       [category ...]
   ]
   ....
   Article body...
   ....
   :id] [/ End of the document /]

This style works better now that we want to include several articles
or libraries in the same .qbk document.

What do you think?

Best regards
Matias