Re: [boost] BOOST documentation in PDF/PS format

From: John Maddock (john_at_[hidden])
Date: 2008-05-28 05:56:16

Daniel James wrote:
>> On 27/05/2008, Daniel James <daniel_james_at_[hidden]> wrote:
>>> On 27/05/2008, John Maddock <john_at_[hidden]> wrote:
>>>  >
>>>  > First the good news: some libraries already provide PDF's of
>>>  their docs, for >  example the regex, math, type_traits and tr1
>>>  libraries all have links to the >  PDF versions of their docs from
>>> their title pages.
>>>
>>>
>>> The pdf links in the math libraries are broken. If it's okay, I'll
>>>  fix them in trunk and release.
>>
>> Patch attached. I've also changed inspect (in trunk) to notice this
>> type of link error.

Thanks, can you go ahead and apply the patch?

>>>  On 27/05/2008, John Maddock <john_at_[hidden]> wrote:
>>>  >
>>>  >  However, if anyone would like help getting their quickbook docs
>>>  converted to >  PDF, I'm certainly willing to help with that as I
>>>  have all the necessary >  tools etc set up here.
>>>
>>>
>>> I'd be interested in trying. Are there linux tools available? I
>>>  think I remember you saying that the only decent ones were
>>> commercial.
>>
>> I saw the renderx advert in the pdfs and had a go:
>>
>> http://unordered.nfshost.com/pdfs/unordered.pdf
>>
>> But it needs some work; there's a missing png, code escapes its boxes
>> and there are page breaks in all the wrong places and none of the
>> right places.

Looks a bit better if you modify the Jamfile using the patch below, the main 
outstanding issues are the very long code blocks - code blocks are formatted 
as "keep together" which causes them to start on a new page if they're too 
big for a page, this is part of the "monospace.verbatim.properties" 
attribute set, so we can't override on the command line (ie in the Jamfile), 
only in an xsl customisation layer.  Normally "keep-together" is what we 
want escpecially for smallish code blocks, but it causes issues for very 
long blocks, is there any way these can be split up?  Hmm, maybe not on 
looking again :-(

Oh and the png image is too large for the page, can you generate an SVG for 
this, it would look much nicer :-)

HTH, John.

Index: Jamfile.v2
===================================================================
--- Jamfile.v2  (revision 45859)
+++ Jamfile.v2  (working copy)
@@ -3,6 +3,9 @@
 # Distributed under 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)

+path-constant images_location : ../ ;
+path-constant admonishment_location : ../../../../doc/src/images ;
+
 xml unordered : unordered.qbk ;
 boostbook standalone : unordered :
     <xsl:param>admon.graphics.path=images/
@@ -18,6 +21,32 @@

     <dependency>css
     <dependency>images
+
+        # PDF Options:
+        # TOC Generation: this is needed for FOP-0.9 and later:
+        <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
+        # Paper type = A4
+        <format>pdf:<xsl:param>paper.type=A4
+        # Yes, we want graphics for admonishments:
+        <xsl:param>admon.graphics=1
+        # Set this one for PDF generation *only*:
+        # default pnd graphics are awful in PDF form,
+        # better use SVG's instead:
+        <format>pdf:<xsl:param>admon.graphics.extension=".svg"
+        <format>pdf:<xsl:param>use.role.for.mediaobject=1
+        <format>pdf:<xsl:param>preferred.mediaobject.role=print
+        <format>pdf:<xsl:param>img.src.path=$(images_location)/
+ 
#<format>pdf:<xsl:param>admon.graphics.path=$(admonishment_location)
+        <format>pdf:<xsl:param>draft.mode="no"
     ;

 install css : [ glob $(BOOST_ROOT)/doc/src/*.css ]
@@ -26,3 +55,5 @@
     : <location>html/images ;
 explicit css ;
 explicit images ;
+
+