Re: [boost] [1.56] Sorry but no PDF doc build (build script has been broken)

Subject: Re: [boost] [1.56] Sorry but no PDF doc build (build script has been broken)
From: Niall Douglas (s_sourceforge_at_[hidden])
Date: 2014-08-11 07:59:16

On 11 Aug 2014 at 12:24, John Maddock wrote:

> >> Sorry folks, but as things stand there will be no PDF build of the docs
> >> for 1.56 as the build script appears to be hopelessly broken :-(
> >>
> >> Each time I fix one Boost.Build error it just leads to another, and
> >> frankly at present I have neither time nor inclination to keep tracking
> >> these down.  If anyone wants to experience some pain then trying to
> >> invoke bjam in /doc/pdf/ will give you an idea of some of the issues.
> [snip]
> Which so freaking inscrutable that I'm pretty sure it's a Japanese 
> translation of Klingon.
> 
> I suspect the only proper solution is to have each library's Jamfile 
> include an install rule to build the PDF and put it under dist/pdf.  But 
> with >60 libraries to patch and apparently the only way to submit a pull 
> request for each (fork, clone, patch, test and submit), then do the same 
> for master *and* develop branches, wait and hope that the maintainer is 
> active and feeling favourable.... well you see my problem!
> 
> Apologies for the rant, John.

No, you're spot on. I suspect the modularisation script didn't 
modularise PDF docs. I found a ton of path breakage.

I did however eventually get PDF docs working for proposed Boost.AFIO 
and which you can witness at 
https://ci.nedprod.com/view/All/job/Boost.AFIO%20Build%20Documentation
%20PDF/lastSuccessfulBuild/artifact/boost-local/bin.v2/libs/afio/doc/g
cc-4.6/debug/afio.pdf. Getting docs working correctly was the hardest 
part of the modularisation effort :(

Anyway, here is the PDF docs build script used by the CI, this might 
be helpful to you:

cd boost-local/doc
../b2 -a ../libs/afio/doc pdf

This produces an output into:

boost-local/bin.v2/libs/afio/doc/gcc-4.6/debug/afio.pdf

It won't generate without error into boost-local/docs/pdf for some 
reason.

My user-config.jam contains nothing special. I did install all the 
docbook tools into PATH though.

Finally, my doc/Jamfile.v2 for AFIO, this took quite a lot of trial 
and error before it worked right:

# Boost.AFIO
#
# This documentation machinery is derived from Boost.Geometry

# Use, modification and distribution is subject to the Boost Software 
License,
# Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at
# http://www.boost.org/LICENSE_1_0.txt)

project afio/doc ;

# Auto-index, experimental. Commented otherwise does not build 
without.
#using auto-index ; 

using quickbook ;

path-constant here : . ;

boostbook afio 
    : afio.qbk
    : <dependency>Jamfile.v2
        <dependency>generated/class_async_file_io_dispatcher_base.qbk
        <xsl:param>chunk.section.depth=4
#    <auto-index>off
#    <auto-index-internal>on
#    <auto-index-verbose>off
#    <xsl:param>index.on.type=1
#       <format>html
       <xsl:param>chunk.first.sections=1
       <xsl:param>toc.section.depth=4
       <xsl:param>toc.max.depth=4
       <xsl:param>generate.section.toc.level=4
       <xsl:param>boost.root=../..
       
<format>onehtml:<xsl:param>img.src.path=../../../../libs/afio/doc/src/
images/a/b/
       
<format>html:<xsl:param>img.src.path=../../../../libs/afio/doc/src/ima
ges/a/b/
       
<format>xhtml:<xsl:param>img.src.path=../../../../libs/afio/doc/src/im
ages/a/b/
       
<format>pdf:<xsl:param>img.src.path=../../../../../../libs/afio/doc/sr
c/images/
       <xsl:param>root.filename=afio
       
<xsl:param>html.stylesheet=../../libs/afio/doc/html/myboostbook.css
       <quickbook-define>enable_index
       <include>$(here)
       
<format>pdf:<xsl:param>boost.url.prefix=https://ci.nedprod.com/
       <xsl:param>fop1.extensions=0
       #<format>pdf:<xsl:param>xep.extensions=1
       # TOC generation: this is needed for FOP 0.2, but must not be 
set to zero for FOP-0.9!
       <format>pdf:<xsl:param>fop.extensions=0
       # No indent on body text:
       <format>pdf:<xsl:param>body.start.indent=0pt
       # Margin size:
       <format>pdf:<xsl:param>page.margin.inner=0.5in
       # Margin size:
       <format>pdf:<xsl:param>page.margin.outer=0.5in
;

install pdfinstall : afio/<format>pdf : <location>. <name>afio.pdf 
<install-type>PDF ;
explicit pdfinstall ;

Hopefully some of the above will be useful to you.

Niall

-- 
ned Productions Limited Consulting
http://www.nedproductions.biz/ 
http://ie.linkedin.com/in/nialldouglas/