|
|
Boost Docs : |
From: Matias Capeletto (matias.capeletto_at_[hidden])
Date: 2007-08-02 07: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