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-18 22:49:04

On 10/19/2011 2:21 AM, Daniel James wrote:

>>> 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.
> 
> It isn't just about what you (or Joel) wants. 

You are the defacto maintainer of Quickbook now. What do you want?
This is an important question too because I'll need your interest
to go down this road.

> Quite a lot of quickbook
> documentation uses doxygen (not mine by the way). If we want to switch
> to generating html, we'll need to provide a means of transition,
> otherwise the uptake will be low.
> 
> And I was talking about linking not extracting. The idea is that if
> you document a function in quickbook, you mark it with a function
> anchor so that it can be easily linked to. I've found that linking to
> functions by their symbolic name is actually a really nice feature. A
> documentation generator could insert the anchors automatically. When
> manually writing reference documentation they could be inserted by
> hand. As I said, I'm not sure about it because I can see a few
> possible warts.

Well, let's see the numbers. Matias, do you have the number of
Quickbook+Doxygen docs available? If there's a high number of
DOx+Qbk, then I have to conclude that Quickbook now is too tied
to DocBook/Doxygen to be practically decoupled from its backend.

What's the implication of this? Well, we'll be forever tied to the
nasty DocBook tool chain.

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