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-31 01:57:39

On 10/30/2011 9:05 PM, Matias Capeletto wrote:
> Can you explain a little bit more how the template engine works to
> finally transform the IR?
> Using your example...
> 
>> We should be working on a full schema and I propose a minimal DocBook
>> style scheme using simple Qbk/Gaea syntax. Example:
>>
>> [book title
>>  [chapter ch1
>>    [section sect1
>>      [para ... ]
>>      [para ... ]
>>      [para ... ]
>>    ]
>>  ]
>> ]
> 
> I thought that the [para ...] template will get evaluated before the
> [section ...] one. This will generate something like
> "<para>...</para>" in the case of the Docbook back-end and that is
> what the [section ...] template will get as an input. Is that right?

Yes, if you do immediate evaluation of the parameters. However, we
can also make it fully lazily evaluated like in Haskell where the
arguments are evaluated only when they are actually needed (e.g.
when they are referenced in the template body).

So, I can imagine a simple definition of section (ignoring the
additional parameters) like this:

  [decl [section name . blocks]]

'blocks' is a list (note the dot). You can expand the list using
the usual list functions such as head, tail, etc. In this case
it's a simple linear expansion using fold:

(warning this is work in progress and the specs might be way off.
Just consider this as a conceptual exercise.)

  [def [section name . blocks]
    <section>
      <title>[name]</title>
      [fold [blocks][][rcat]]
    </section>
  ]

where rcat is:

  [def [rcat a b] [b][a]]

so, essentially, fold builds/compiles the blocks starting with
an empty state [], calling rcat for each block and the previous
state. (I'm sure you all know how fold works). rcat reverses its
arguments (unlike cat), because that's how fold passes its args:

  [decl [fold x s f]]

  For a list x, initial state s, and binary function f,
  fold returns the result of the repeated application of
  [f e s] for each element e of list x, to the result
  of the previous f invocation (s if it is the first call).

Now see how conceptually beautiful that definition of section is!

>>From your comments about footnotes processing for HTML it seems that
> the [footnote ...] template generates the reference inplace and also
> returns the actual text for the footnote wrapped in a certain way so
> it survive the [para ...] evaluation and is then available in the
> [section ...] template or even in the [chapter ...] one for them to
> arrange where they will finally end up. Could you elaborate on how the
> evaluation steps will actually take place?

When I wrote quickbook, internally, there are what's called
"collectors". We can use the same scheme to "collect" stuff that
you don't need now, but will be needing later. I can see that
we can "push" the actual text for the footnotes in a collector
as we get them. Then later, we can expand them at the proper place.

Granted, the specs does not have this feature yet, but my intent
is to have the spec seen for the purpose of refining it through
brain storming sessions like this.

>> (aside I'm not sure if we should do it the old way using section/
>> endsect, or a real block structure like this. There are tradeoffs,
>> but I do not want to digress. I'm sure you know what the tradeoffs
>> are).
> 
> If you want to follow the design you sketched, I think this is a good
> change and we should move away from [section] and [endsect].

Well, I was hoping for an easy upgrade path to the new scheme.
At first, I thought it should be as easy as regex find replace.
On second thought, perhaps we'll need a real conversion tool
to do the migration. You'll need a smarter parser to detect
and convert nested markups (regex won't cut it). I'm not sure.

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