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-22 01:48:31

On 10/21/2011 6:14 PM, Daniel James wrote:
> 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.

That, I am aware of. That is the primary reason for the redesign.
The tricky part is how to make the revised grammar as close as
possible to what we have now. The original grammar tried to
look as much like the qbk markups at the time but didn't quite
do it well.

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

Right.

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

No. The language should not be newline nor comment sensitive.

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

It's just like S-expressions. You are right that without proper
placement, you never know where a list begins and ends. It really
depends on placement. The quickbook table is an example:

  [table title
      [[Heading 1] [Heading 2] [Heading 3]]
      [[R0-C0]     [R0-C1]     [R0-C2]]
  ]

Here, it is clear that the syntax is:

  [table title list]

So the 'list' is expected only as arguments to the table template.
*That* is its position (but more below).

> I think your third list is incorrect.

This?:

  [[a][[b][c]]]

How so? Maybe I'm blind :-P

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

You are right. It is ambiguous. I guess it will all be clearer if
I present a formal grammar instead of snippets of code. Forward
declarations may be important for recursive templates though.

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

Because in the def of ==, it is a 2-arity function:

  [def == a b]

Perhaps we ought to have the notion of var-arg lists at the
end, like, e.g.:

  [table title rows...]

The table markup is what actually prompted the need for lists.
Right now, with the current qbk template scheme, you can't
do something similar to qbk tables.

> How do you pass a function as a parameter?

Still working on that. TBH, I'm still unsure about the need for
explicit function invocation/eval, but I was guessing that it's
needed to allow functions to be passed in. For example:

  [def dup a][[`a][`a]]

This is a function invocation:

  [`dup [apple pie]]

This is not:

  [dup [apple pie]]

The latter can be passed in to a template like, e.g. transform
if we have some bind/phoenix like placeholders. E.g.:

  [`transform [`list] [dup _1]]

Just an idea. But perhaps we can make function invocations
implicit and use 'lambda' to pass functions:

  [transform [list] [lambda dup _1]]

Again reminiscent of phoenix and also makes the syntax close
to current Qbk. Yeah! Definitely better. I keep forgetting
I've solved this problem over and over again! Duh!

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

I don't care which operators we'll end up using. The ^ also
looks good. What's more important is a well defined, unambiguous
and simple (as simple as possible!) syntax.

I invite you and anyone else interested to hack at the informal
specs I presented. Ultimately, I'd like to have this as a
separate tool as it can be useful in other applications that
need text generation. It's simple but is quite powerful. It
can be used, say for example, as a tool for generating web pages,
xml, even automated generation of C++ source files, etc.

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

Right! That would be a special case.

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