Re: [Boost-docs] Quickbook wish list..

Subject: Re: [Boost-docs] Quickbook wish list..
From: Rene Rivera (grafikrobot_at_[hidden])
Date: 2011-11-24 19:34:45

On Thu, Nov 24, 2011 at 1:05 PM, Daniel James <dnljms_at_[hidden]> wrote:

> On 22 November 2011 16:18, Rene Rivera <grafikrobot_at_[hidden]> wrote:
>
> > * Ability to apply syntax coloring to code blocks one at a time. Right
> now
> > one can globally switch the language system with "[c++]" etc. But what
> I'd
> > rather have is the capability to to a temporary switch (i.e. a push and
> > pop). In my case I want to set the global default to "teletype" and then
> > choose "c++" for certain places.
>
> That's something I've thought about. The main problem is coming up
> with good syntax.

Yes.. I didn't suggest any syntax because I couldn't think of a really good
one at the time.

> I was thinking of something to contain the code, the
> problem is that I think it should be clear from the syntax (rather
> than the name of an element) what is a code block and what is
> quickbook. Maybe:
>
> [c++ ``
>    int main() {}
> ``]
>
> and the phrase version:
>
> [c++ `int main() {}`]
>
> i.e. if a source mode element contains code markup, the source mode
> switch is restricted to that code. Or is that horrible?
>

Doesn't seem horrible. Only slightly awkward. I'd say if nothing better
comes along it's a good choice.

> Another possibility is:
>
> `[c++] int main() {}`
>
> But it's hard to come up with good rules to distinguish a source type
> marker from code. I feel that everything within backticks should be
> exempt from normal quickbook rules.
>

Indeed, that would cause a whole slew of problems. The only other option I
can think of is a temporary marker on the current syntax that marks the
"next" code segment only:

[!c++]
``
int main() {}
``

Expression:

[!c++] `int main() {}`

But that doesn't seem any better than your first suggestion.

> > * Ability to use code callouts in regular code blocks instead of just in
> > code "import". This seems like just a consistency issue. It seems to me
> that
> > the code markup aspect available to the "import" should be available to
> code
> > blocks also. Although right now callouts are the only feature in this
> > context.
>
> It shouldn't be too hard to adapt the code snippet parser to do that.
>

Cool.

>
> > * And of course I've already mentioned the file inclusion/extraction from
> > code files.
>
> I've sort of implemented that on the dev branch, but only if you use
> the 1.6 switch. This should be merged into trunk within the next week.
> I think '1.6' is pretty much feature complete from my point of view
> (well, there's more to do, but there's always more to do), so I'll be
> looking for feedback to try to finalize it.
>

And I've tested that with the docs I'm writing. Seems to work rather well
so far. Should add 1.7 switches for features like this that are even more
experimental that the rest of 1.6?

>
> > * And the related include/import with file globs. (I'm actually working
> on
> > translating the glob implementation from b2/bjam to work in quickbook
> since
> > Daniel prefers globs. And b2 has a really small and standalone
> > implementation of globs.)
>
> Will that make it easier to implement dependency checking in boost build?
>

I don't see how it's related. Since it's a straight port from the C code to
templated C++ code. About the only thing it adds is possible future unicode
support.

> On the dev branch escaping is now implemented (for 1.6).
>

I'll update :-)

-- 
-- 
-- Grafik - Don't Assume Anything
-- Redshift Software, Inc. - http://redshift-software.com
-- rrivera/acm.org - grafik/redshift-software.com
-- 102708583/icq - grafikrobot/aim - grafikrobot/yahoo