Re: [boost] [fusion] html docs woes

Subject: Re: [boost] [fusion] html docs woes
From: Joel de Guzman (joel_at_[hidden])
Date: 2011-07-20 19:49:24

On 7/21/2011 4:30 AM, Eric Niebler wrote:
> On 7/19/2011 10:58 PM, Daniel James wrote:
>> On 20 July 2011 06:20, Joel de Guzman <joel_at_[hidden]> wrote:
>>> On 7/20/2011 11:30 AM, Eric Niebler wrote:
>>>>
>>>> So I just generated the new Fusion HTML docs and did an svn diff. The
>>>> resulting diff file is 1,617 lines, and is too large for me to post
>>>> here, weighing in at 112K.
>> [snip]
>>>
>>> If that's the case, then that is clearly unacceptable. I was under the
>>> impression that this has been fixed? Daniel? Hartmut? John?
>>
>> Not fixed, but improved. In a previous check-in (r72930) the svn diff
>> of the generated html was 872K.
>>
>> The improvement was acheived by adding ids to headings in quickbook,
>> because if they don't have them docbook generates random ids for them.
>> There are still ids generated for some things. I had a look at recent
>> changes to the spirit documentation and fixed a couple of them the
>> other day (on legalnotice and footnotes). Looking at the fusion
>> documentation there also seem to be a few for tables, which I can
>> probably fix. But I don't think I can completely fix this, certainly
>> not for anyone using a boostbook generated reference.
>>
>> The last revised dates are generated by quickbook. It'd be quite easy
>> to add a flag to suppress them. I don't like them much anyway, since
>> they tend to be misleading.
> 
> Joel, would you accept a patch to remove the generated HTML docs and
> integrate Fusion docs into the regular Boost doc build?

If we have to do it, let's do it for Spirit and Phoenix as well.
There are some minor issues still not discussed though.
Hand-picking from John:

* One size fit's all chunking scheme - it works for small libraries - but IMO larger
libraries with complex documentation hierarchies would be rendered almost unreadable (I'm
thinking of Boost.Math here).
* No way to insert any library specific XSL options - for example the Math library uses
.png's for html and SVG's for PDF output which requires some fancy XSL footwork that other
libraries wouldn't want I'm sure.

If we could move to a unified, but still distributed scheme; (oxymoron (*)? )
or at least have that as a goal, then by all means.

(* we have to move away from a monolithic one-big-doc for all libraries.
I'm not sure how to best do it, but regardless of the docs being generated
or not, it's still best to have the docs in each library's doc directory
and have the top level doc link to each library's doc).

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