Re: [Boost-docs] The beauty of LATEX

Subject: Re: [Boost-docs] The beauty of LATEX
From: Joel de Guzman (joel_at_[hidden])
Date: 2011-10-20 01:16:58

On 10/20/2011 4:34 AM, Daniel James wrote:
> On Tuesday, 18 October 2011, Joel de Guzman wrote:
> 
>     On 10/19/2011 2:21 AM, Daniel James wrote:
> 
>     >
>     > It isn't just about what you (or Joel) wants.
> 
>     You are the defacto maintainer of Quickbook now. What do you want?
> 
> 
> I don't feel a strong ownership of quickbook, I'm currently driving development but don't
> feel like I will automatically get new features through or have a veto on anything (part
> of the reason for putting a version switch on everything is so that language changes can
> be easily backed out if rejected).

And I am very happy and I really appreciate what you have done!

> My main aim with quickbook has been to get what currently exists to work as well as
> possible. I've been very conservative about adding new features but a little radical with
> the implementation (I do worry that one day someone is going to look at it and have a
> heart attack). My recent efforts have been to improve the way quickbook structures the
> documentation - e.g. better id generation, smarter placement of anchors, supporting
> docinfo in included files. Once that's done (soon I hope, subject to approval), I want to
> improve the grammar, for example change it so that square brackets are always grammatical,
> unless they are escaped or in a code block (which should fix a few of quickbook's quirks)
> and try to improve nesting of blocks (e.g. paragraphs in lists and lists in tables).

Those are nice pragmatic moves. I do hope that we still share the same
objectives and plans as we did when I was developing Qbk. Here was the
original plan of crucial significance:

1) Better library support + inclusion of a standard qbk library
2) Move as much code from C++ into the standard qbk
3) As a corollary of 1 and 2, we need to make sure that the
   template mechanism serves its purpose well for replacing
   hand-coded markups in C++ into Qbk.

As I suggested earlier, 1 can be done by adding a --path and --include
command line arguments (maybe even --import). 2 Will vastly simplify
the code and will make it easier for others to hack into.

> I'm pretty wary about embedding a programming language in a documentation format. My
> experience with such things has not been great. If you look at XSL, it's great for some
> XML transformations, but when you try to do something more complicated (you don't have to
> look far) it becomes a real pain, I could see quickbook templates being similar. 

XSL is a sorry mess. A programming language in XML is nonesense!

> I would
> be more interested in embedding an existing language by some means, but that isn't
> something I'm planning on doing (I think it would really need to have a full AST
> representation first, although maybe just section by section).

If you want the simplest usable embedded programming language, that would
be scheme, or a dialect. We already have embedded implementations of it in
Spirit examples. Yet, by design, it just so happens that quickbook templates
are basically influenced by scheme (just replace [] with ()).

The Qbk template mechanism *is not* a documentation format. It is a
minimal text oriented DSL by design. More power can be obtained from
it by giving it some more juice. I think I showed you an idea sometime
ago on how to make the Qbk template mechanism a complete text generation
engine. Here is the current incarnation of it. I call it Gaea --heavily
influenced by Qbk templates *and* scheme:

  http://pastebin.com/1EKHukY4

Regards,
-- 
Joel de Guzman
http://www.boostpro.com
http://boost-spirit.com