Re: [boost] building docs (Was: [test] trunk breakage)

Subject: Re: [boost] building docs (Was: [test] trunk breakage)
From: John Maddock (john_at_[hidden])
Date: 2010-01-08 04:03:41

>>> c) I could choose which kind of documentation I wanted
>>> html or pdf or (maybe someday) windows help file
>>
>> Building PDF docs is complicated by needing to have a specific PDF
>> generator software which is commercial, IIRC. I heven't tried building
>> PDF so someone else will have to answer as to how to do it.
>
> Technically, you can use Apache FOP. In practice, you might need to use
> specific version, as all other versions are badly broken. What version
> exactly is sacred knowledge. I believe John is using XEP Personal for
> generating release docs on PDF.

Nod.  XEP Personal edition is highly recommended - modulo the fact that it 
basically doesn't have any useful error handling :-(

Apache FOP will build some of the docs OK, but often completely mangles the 
pagination in more complex cases, so I've stayed away from it.  If you're 
building docs for a specific library that isn't too large, and you're 
prepared to manually check the docs to make sure they're OK, then FOP may 
work for you.  Otherwise XEP personal edition is free and a drop in 
replacement for FOP.

Just my 2c.... John.