Re: [Boost-docs] The beauty of LATEX

Subject: Re: [Boost-docs] The beauty of LATEX
From: John Maddock (boost.regex_at_[hidden])
Date: 2011-10-19 08:20:24

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

Apologies for staying out of this (very interesting!) discussion till now, 
some observations:

1) What's the issue with XEP produced PDF's - is it something we can easily 
fix?  PDF formatting is quite flexible, it's just a question of getting 
where we want to be.... but of course the complexity of setting up the 
toolchain is a concern.
2) I suspect that folks are using Doxygen+Quickbook because (a) they're 
familiar with Doxygen, and (b) there's nothing better currently available. 
That said I'm no fan of Doxygen (even in conjunction with quickbook), and 
personally prefer the control you get with manually quickbook'ed docs.
3) I confess that when I first investigated the import feature I too thought 
it worked as Rene did - Oh and I believe the "Rene include model" would be a 
useful addition, and yes that includes those pesky wildcards ;-)
4) I'd love it if quickbook had a "standard" include path for useful 
template libraries - the Math lib's collection of HTML4 symbols (Greek 
letters mainly) would be a prime candidate.
5) I believe there is a tool somewhere (I forget which library) that 
converts Doxygen XML to quickbook, so use of Doxygen doesn't necessarily 
preclude quickbook doing direct doc generation... but it will mean a long 
tool chain again.

Cheers, John.