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

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

This archive was generated by hypermail 2.1.7 : 2017-11-11 08:50:40 UTC