Hello, I am looking for the BOOST library in either PDF/PS formats so that I can print the ones I need and read them offline (which I generally prefer). Reading though the boost documenting link, it appears quite a daunting task to setup boost doc build to generate PDF files (it has a bunch of dependencies). Is there any location from where I can download the PDF files for the current release version of BOOST or any plans for providing the same in the near future? with best regards, dhruva -- Contents reflect my personal views only!
dhruva wrote:
Hello, I am looking for the BOOST library in either PDF/PS formats so that I can print the ones I need and read them offline (which I generally prefer). Reading though the boost documenting link, it appears quite a daunting task to setup boost doc build to generate PDF files (it has a bunch of dependencies). Is there any location from where I can download the PDF files for the current release version of BOOST or any plans for providing the same in the near future?
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. Now the bad news: since not all documentation is written in a format suitable for conversion to PDF, not all authors do this. In any case printing all of Boost's docs out in one go would require several large trees and wouldn't be recomended! So the advice is... use the HTML docs to work out which Boost libraries you're interested in, and then print out those libraries docs alone if they're available as a PDF. HTH, John.
Mathias Gaunard wrote:
John Maddock wrote:
Now the bad news: since not all documentation is written in a format suitable for conversion to PDF, not all authors do this.
Aren't people working on converting all documentation to boostbook, which can generate PDFs?
Um, yes, but it's voluntary, and note that not everyone who's using quickbook/boostbook/docbook has their docs in a state that can generate nice looking PDF's: there's often a whole load of pagination / content overflow issues to debug before that's sorted out :-( 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. HTH, John.
On 27/05/2008, John Maddock <john@johnmaddock.co.uk> 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. On 27/05/2008, John Maddock <john@johnmaddock.co.uk> 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. Daniel
On 27/05/2008, Daniel James <daniel_james@fmail.co.uk> wrote:
On 27/05/2008, John Maddock <john@johnmaddock.co.uk> 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.
On 27/05/2008, John Maddock <john@johnmaddock.co.uk> 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. Daniel
Daniel James wrote:
On 27/05/2008, Daniel James <daniel_james@fmail.co.uk> wrote:
On 27/05/2008, John Maddock <john@johnmaddock.co.uk> 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@johnmaddock.co.uk> 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 ; + +
2008/5/28 John Maddock <john@johnmaddock.co.uk>:
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 :-)
Thanks for the help. I've applied your changes, adjusted the PNG's pixels per inch so it isn't so huge, added an SVG and a few other tweaks. There's a new pdf at the same location: http://unordered.nfshost.com/pdfs/unordered.pdf I've also tried generating a single html page and creating a pdf from that using prince (http://www.princexml.com/). This approach should give us a little more control over page breaks using CSS. Although the html output isn't ideal for this kind of thing. The result so far is at: http://unordered.nfshost.com/pdfs/unordered-prince.pdf Daniel
Daniel James wrote:
Thanks for the help. I've applied your changes, adjusted the PNG's pixels per inch so it isn't so huge, added an SVG and a few other tweaks. There's a new pdf at the same location:
http://unordered.nfshost.com/pdfs/unordered.pdf
I've also tried generating a single html page and creating a pdf from that using prince (http://www.princexml.com/). This approach should give us a little more control over page breaks using CSS. Although the html output isn't ideal for this kind of thing. The result so far is at:
These both look pretty good to me: the first has the "no page break in long code block" issue, the second doesn't have the TOC at the side. Actually there *may* be a solution to the wrongly-keeping-long-blocks-together issue: insert a "<?dbfo keep-together="auto" ?>" inside the Docbook XML for the long block, that should then allow it to page break and stop it from starting a new page. The problem is while I think I can see how to insert this into quickbook, I can't see how to insert this into your ref.xml at present :-( There's more info on page break issues here: http://www.sagehill.net/docbookxsl/PageBreaking.html HTH, John.
On 02/06/2008, John Maddock <jz.maddock@googlemail.com> wrote:
These both look pretty good to me: the first has the "no page break in long code block" issue, the second doesn't have the TOC at the side.
It does but it isn't shown as default. Although it's not very good. It's based on the header elements which don't always represent the structure of the boostbook document. This could possibly be improved, although that might not play well with chunking.
Actually there *may* be a solution to the wrongly-keeping-long-blocks-together issue: insert a "<?dbfo keep-together="auto" ?>" inside the Docbook XML for the long block, that should then allow it to page break and stop it from starting a new page. The problem is while I think I can see how to insert this into quickbook, I can't see how to insert this into your ref.xml at present :-(
I tried adding it to the synopses in the boostbook xsl, but it didn't seem to make much difference. The change to the xsl is at: http://svn.boost.org/trac/boost/changeset/46060 If we could get this to work I could try to develop something a bit more sophisticated. If you're interested, you can see the CSS I used for the other version. That was also largely concerned with where page breaks can appear. http://svn.boost.org/trac/boost/changeset/46021 Daniel
Daniel James wrote:
Actually there *may* be a solution to the wrongly-keeping-long-blocks-together issue: insert a "<?dbfo keep-together="auto" ?>" inside the Docbook XML for the long block, that should then allow it to page break and stop it from starting a new page. The problem is while I think I can see how to insert this into quickbook, I can't see how to insert this into your ref.xml at present :-(
I tried adding it to the synopses in the boostbook xsl, but it didn't seem to make much difference. The change to the xsl is at:
http://svn.boost.org/trac/boost/changeset/46060
If we could get this to work I could try to develop something a bit more sophisticated.
Unfortunately having now looked a bit deeper it appears that dbfo keep-together instructions aren't processed by verbatim blocks :-( Indeed, because the keep-together instruction is placed in an attribute set and just injected "as is" into the fo:block by the verbatim processing xsl there appears to be not much we can do :-( I'll see if I can a docbook XSL mailing list to ask about this as it would be nice to have this solved. John.
Daniel James wrote:
On 27/05/2008, John Maddock <john@johnmaddock.co.uk> 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.
Oh :-( Looks like a missing // in the URL. Yes please do go ahead and fix if you're willing that would be great.
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.
Right, the only decent FO processor IMO is XEP, it's a Java app so I assume it'll work on Linux but I've never tried it. There's a free edition available that places a discrete banner add at the bottom of each page - see the math docs for example. Actually I seem to recall they offered Boost a free copy of the full product, but we never got our act together with somewhere to host it :-( In any case XEP and Apache FOP are command line compatible so you easily switch between them in your user-config.jam, for simple use cases Apache FOP is fine, but it's pagination routines aren't nearly as good as XEP's for more complex situations. HTH, John.
participants (5)
-
Daniel James -
dhruva -
John Maddock -
John Maddock -
Mathias Gaunard