Re: [Boost-docs] The beauty of LATEX

Subject: Re: [Boost-docs] The beauty of LATEX
From: Daniel James (dnljms_at_[hidden])
Date: 2011-10-21 10:14:36

On Thursday, 20 October 2011, Joel de Guzman wrote:
>
> 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.

I think that at the moment quickbook templates have enough quirks to
be problematic. I've improved some things, most notably variable
scoping and the confusion between phrase and blocks. But there's still
the odd parameter passing style, and the way they can be confused by
non-grammatical brackets.

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

There's already a path flag (-I).

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

That might be extended to say 'A programming language in a markup
language is nonsense'. The problem is that in most languages things
are symbols by default, in a markup language things are text by
default, so using one as a programming language requires nearly
everything to be annotated as 'not text' which becomes verbose.

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

Well technically, it's probably be a Forth style language. I don't
want to get into programming language arguments because they're so
subjective (which is exactly why I said I'm not planning on doing
this), but I do have a hard time getting on with any language which
doesn't use standard mathematical notation.

> 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 list syntax is pretty different.

> 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

Yes, I started writing a thing, but after spending a while on it
realised that I'd misunderstood the syntax, and never quite got round
to starting again. Although it looks a little different to how I
remember it. A few points:

The list syntax doesn't make it clear when a list begins and ends. You
show three example lists but your grammar suggests it's one list with
five elements (unless comments or newlines end lists?). This syntax
works in quickbook because it's always nested inside another block
which terminates it, in a more general purpose language this might not
always be the case.

I think your third list is incorrect.

The function forward declaration syntax seems a bit ambiguous since
there's no clear indication that it isn't a function. It could
possibly be followed by a block which isn't meant to be a function
body. And quite easy to get wrong (e.g. [def foo][`bar 1 2] would be a
bit surprising). I don't actually see why there needs to be forward
declarations.

I'm also a little confused by how function parameters are passed. In
the example: '[def != a b][[`![`==[`a][`b]]]]' why aren't the
parameters to '==' considered to be a single argument?

How do you pass a function as a parameter?

For some reason whenever I tried writing code I consistently use '^'
instead of '`'. It seems to be hard wired into me. I'm not sure why,
maybe because the use of a back tick in that manner isn't something
I'm used to.

The ["" x] is used to escape all occurances of [ and ] - so how it
does it tell when x ends? I guess they have to balanced. Maybe ["" x
""] would be better.