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-30 00:10:58

On 10/28/2011 4:57 PM, Matias Capeletto wrote:
> 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.

Alright, let me make it clear. I'm presenting this in a high-level
design:

1. Preprocesors:

  a. The wiki can and *should be* a preprocessor.
  b. The syntax-highlighter is another preprocessor. It should
     be made modular and should probably make use of a regex
     based highlighter already existing in the wild. THere are
     lots out there.
  c. Code inclusion can very well be another preprocessor.

2. IR:

  a. There will be an (intermediate) output, call it a DOM or an
     AST as you and Dave have been calling. It shall be patterned
     after DocBook which has a very good structure to begin with.
  b. The IR **IS A TREE**. It should be semantically rich and
     extensible.
  c. We should get rid of docbook-isms in the output.
  d. Preprocessors need not be concerned about the full structure
     of the full IR, just a subset. Preprocessors should only be
     concerned about text to text translation into a subset of
     the IR it needs to deal with.

3. Backends:

  a. The template engine is work in progress. The final design
     should be powerful enough for tree transformations like the
     ones Daniel concocted.
  b. The template engine transforms the IR into the final form
     (e.g. LaTeX, Docbook, HTML etc.). But Matias is right: we
     need to focus on just LaTeX and Docbook.

Here are some further comments:

Let's make Quickbook modular! We do not want a monolithic blob
of code.

The wiki can and *should be* a preprocessor. I haven't seen
any compelling showstopper argument yet. The ones Daniel gave
are tradeoffs that can be worked around with for the greater
good. Matias presented a simple rule on the detection of
paragraphs in the wiki preprocessor. Simple is better!
Simple rules are easier to understand and reason out with
compared to the already convoluted phrase-block scheme that
we have right now. Even I (and Steven?) have difficulty
understanding what's going on and that's not a good sign.

Again, preprocessors should only be text to text translators,
much like the C++ preprocessor. It definitely should not dabble
with tree transformations.

Daniel gave an example about footnotes:

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

Here are my thoughts:

I never said we are not working with a tree. I merely said that the
preprocessors should not be working on a tree. I presented the list
structure before:

  [orderedlist
    [One]
    [Two]
    [Three
      [itemizedlist
        [Three.a]
        [Three.b]
        [Three.c]
      ]
    ]
    [Four]
  ]

Isn't it obviously a tree?

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

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

And the point is that *this is a tree!*. And as I said: although
the template engine is work in progress, the final design should
be powerful enough for tree transformations. That's the reason why
it's patterned after scheme: a real programming language (and the
similarity is not a conincidence).

Now back to footnotes. You do it using CSS. Here's a way:

  http://tinyurl.com/4vwe5u

This entails having this structure:

  <div id="container">
   <div id="header"></div>
   <div id="body"></div>
   <div id="footer"></div>
  </div>

I'd say that is easy-peasy! We just have a collector of footnotes
and churn them out at the proper time.

Then again, I also agree with Matias that we may not need to deal
with this since we already have mature HTML generation engines
in any of our backends. I'm just saying that it can be done.

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