Re: [Boost-docs] The beauty of LATEX

Subject: Re: [Boost-docs] The beauty of LATEX
From: Daniel James (dnljms_at_[hidden])
Date: 2011-10-27 07:47:13

On 27 October 2011 00:35, Joel de Guzman <joel_at_[hidden]> wrote:
> On 10/27/2011 5:54 AM, Daniel James wrote:
>> On 26 October 2011 15:07, Joel de Guzman <joel_at_[hidden]> wrote:
>>>
>>> Then again, I am not sure how that is related to the wiki
>>> blocks and phrases question at all.
>>
>> I was trying to move away from blocks and phrases because that was
>> going nowhere. If that's all you wish to discuss then I don't think
>> I've got anything more to add.
>
> I don't think it is going nowhere. Let me rewind:
>
> Matias said:
>
>> Because this kind of interaction between the template system and the
>> wiki processor is not very clean, maybe we could solve this problem by
>> saying that the wiki processor will consider that any lines that are
>> wrapped by a template are not considered a paragraph.
>>
>>   This is a [*paragraph].
>>
>>   [custom_section This is not]
>>
>> The only thing that it will change for the user is that he will have
>> to wrap this kind of lines:
>>
>>   [custom_bold This is not a paragraph]
>>
>> with a [para ...] template:
>>
>>   [para [custom_bold Now it is]]
>>
>> We can even avoid this for the common standard templates like [* ...].
>>
>> This could simplify a lot the logic of the wiki processor (and its
>> interaction with the template system) at the cost of changing the
>> behavior of what I think are corner cases.
>
> Which makes sense, really. It is simple and easy to explain.
> Then you replied:
>
>> If anyone doesn't realise, I proposed a 'block' element in another
>> thread to deal with this issue.
>
> So I asked for an explanation how it would help. But then you bundled
> it up with other unrelated issues and in the end I didn't really
> get an answer.

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

    Some numbers: [numbers]

If __text__ is defined that generaters:

    [para Some numbers: 1,2,3]

All is fine.

If __list__ is defined it generates:

    [para Some numbers:
        [block'''<ol><li>1</li><li>2</li></ol>''']]

Now there's a block inside a paragraph - not good. But if this is
represented as a tree you can walk that tree, detect situations like
this and transform it to the correct representation:

    [para Some numbers:]
    [block'''<ol><li>1</li><li>2</li></ol>''']

But this has to be done after the template stage - since the template
generates different content based on which macro is defined. So the
later stages have to be aware of the documentation structure. I'm not
sure that in this context 'block' is the correct solution, something
more sophisticated might be better.

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]

A straight translation generates:

    <anchor id="markups"/><section><title>Markups</title>

That has a tendency to place the anchor in the previous section (there
were problems with this in the past), what it should generate is
something like:

    <section><title><anchor id="markups"/>Markups</title>

Or maybe:

    <section id="markups"><title>Markups</title>

AFAICT that's difficult with your proposal. But as a tree
transformation it's pretty simple.

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.

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

The reason I moved onto lists is because they're quite simple to
process (once they're parsed). And I thought that if I could see a
clear illustration of how they are processed, I might find out that I
was missing something and there was a way to do these things. Or I
could suggest some changes that would allow these things to be done.