Re: [Boost-docs] The beauty of LATEX

Subject: Re: [Boost-docs] The beauty of LATEX
From: Matias Capeletto (matias.capeletto_at_[hidden])
Date: 2011-10-28 08:57:45

Hi,

On Thu, Oct 27, 2011 at 9:47 AM, Daniel James <dnljms_at_[hidden]> wrote:
> OK. Here's a contrived example (using current quickbook, assume that
> either __list__ or __text__ is defined):
>
>    [template numbers[]
>        [?__list__ [block'''<ol><li>1</li><li>2</li></ol>''']]
>        [?__text__ 1, 2, 3]
>    ]

Do we really need to support this? If we do, then I agree that we can
not do it with out something like the [block ...] element. But it
seems a little contrived to make a template that can be both a phrase
element or a block element. Is this a real need?

> On its own this may not seem that important, but all the other issues
> I mentioned are related because they're a lot easier to solve if you
> are processing the document as a tree with some knowledge of what it
> represents.
>
> For example, when generating the start of a section, any anchors for
> that section need to be placed at a specific point in the output. Take
> this:
>
>    [#markups][section Markups]

Maybe we can demand the user to put the anchor id directly into the
section template, similar to what we have now:

[section:markups Markups]

For this, we should device a notation for optional arguments in Gaea.
Maybe something like

[template section:[title][id=0]
...
<anchor id="[if [== [id][0]] [normalize title] [id] ]"/>
...
]

And when invoked:

[section The reference]                        // id == 0
[section [The reference]]                      // id == 0
[section [The reference][reference_id]]  // id == reference_id

> Another example is footnotes, for docbook they're easy - you just
> write them inline. But when generating html for the web you have to
> place the footnotes in the correct location. To find the correct
> location you need to know about the structure.

Indeed, but supporting this kind of things in HTML requires a bigger
beast. Indexing, paging, footnotes... all these goodies requires a
full knowledge of the document and a heavy processing of it. To make a
good job we will need to replicate something like LaTeX. While this
maybe a really good project, I think it is a lot better to rely on it
or on Docbook and leave them handle these tasks.

> You could do a lot of this with a html post processor, but that'd mean
> writing a post processor for every target supported, it's easier to
> compose reusable tree transformation for each target (e.g. 'html for
> pdf' would be similar to 'html for web' but wouldn't use a chunker,
> and would use a different technique for footnotes).

I am starting to think that except for very basic Quickbook to HTML
snippets (no footnotes, no chunking), we should drop for now the idea
of making a direct Quickbook to HTML or PDF generation. I agree with
Daniel that if this is what we are looking for, then Joel's proposal
will not be enough. But Joel's idea could work very well in a
Quickbook to Docbook or LaTeX processor and, specially for generating
LaTeX, it seems very attractive. I would love to have the power and
maturity of LaTeX with the simple and clean Quickbook syntax.

Best regards
Matias