Re: [Boost-docs] The beauty of LATEX

Subject: Re: [Boost-docs] The beauty of LATEX
From: Rene Rivera (grafikrobot_at_[hidden])
Date: 2011-10-18 03:12:23

On 10/17/2011 3:31 PM, Daniel James wrote:
> On 17 October 2011 06:35, Joel de Guzman<joel_at_[hidden]>  wrote:
>>
>> Anyway, I guess if it still goes through the complex XSLT tool
>> chain, I'll still have my doubts. Another way is to decouple
>> the back-end of quickbook to allow it to directly generate
>> HTML, or LaTeX in addition to Docbook. Quickbook started out
>> generating HTML anyway and it should be reasonably doable to
>> refactor the code, decoupling the output generation. The only
>> problem I see is that some folks (e.g. John M), have written
>> Quickbook templates that leverage more advanced features of
>> DocBook. Those DocBook targetted templates obviously won't work
>> with a different back-end. Me, I avoided writing such templates
>> and going directly to DocBook because I didn't want to lose the
>> possibility to have Quickbook retarget another back-end.
>
> It's certainly doable, the spirit 2 fork of quickbook had a half
> written html generator (it didn't do chunking and missed a few
> features).

Not only is it doable.. But I did it for the Spirit1 version "long" ago. 
And the code is still around.. here.. 
<https://svn.boost.org/svn/boost/branches/quickbook/backend/boost/tools/quickbook>. 
What stopped me those 4 years ago was waiting for a design/choices on 
some other basic features to really make it usable. Like dealing with 
include paths, where to install the templates, how to select the 
backend, etc. I was particularly looking forward to the Spirit2 
"rewrite" to hopefully revive that code to make it easier to implement.

> The feedback wasn't particularly positive which is part of
> the reason that it's the only feature I haven't ported back yet.

Feedback from whom? I'd obviously use it ;-)

> The
> implementation of the current quickbook is quite different though, the
> spirit 2 version was very static, while the current version uses a

Hm you meant spirt1 version was very static?

> more dynamic data structure (along similar lines to utree), so it
> isn't just a case of copying the implementation over. Generating latex
> would be a bit trickier.
>
> There is another problem, much of the current documentation based on
> doxygen + quickbook make use of tags like 'funcref' and 'classref' to
> link into the doxygen documentation, a replacement would need
> something to support that. I haven't really thought about doing that
> in quickbook, could possibly add some sort of anchor for language
> reference types, would need to build in some sort of namespace
> resolution, and maybe a way to identify the language type (could just
> use the source mode?). I'm not sure if it'd be a good idea.

I just don't think it's needed. To be frank, the Doxygen like features, 
of "extracting" synthetic documentation from the code declarations is 
the last thing I want. I find the Doxygen results usually much less 
useful than just opening the header files and reading them. As it's more 
likely that authors will structure their source code to be more readable 
than the usual reference documentation Doxygen puts out. As I mentioned 
in my other post, what I want is to close the distance between where the 
code is and where its documentation is. Not just for the usual literate 
programming ideals. But because the library that I'm working on needs to 
be highly file modular. And by that I mean that it would be 
prohibitively difficult to maintain documentation separate from the source.

NOTE: Yes I'm aware that it's possible to produce high quality 
documentation with Doxygen. But I'm also that it takes an amount of work 
that plurality of authors are not going to be inclined to do.

-- 
-- Grafik - Don't Assume Anything
-- Redshift Software, Inc. - http://redshift-software.com
-- rrivera/acm.org (msn) - grafik/redshift-software.com
-- 102708583/icq - grafikrobot/aim,yahoo,skype,efnet,gmail