Re: [Boost-docs] The beauty of LATEX

Subject: Re: [Boost-docs] The beauty of LATEX
From: Joel de Guzman (djowel_at_[hidden])
Date: 2011-10-18 23:10:49

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