[1.38] Beta release of PDF documentation (and some help needed).
Folks, SVN commit 51104 to trunk provides the basic support for building all the Boost libraries that can be as PDF's: * improved fo.xsl stylesheet, * tweaked individual Jamfiles so they find their images etc when being built as a PDF, * adds doc/pdf/Jamfile.v2 to build all boost libraries that can be as individual PDF's. Beta builds of the PDF's are available for download from http://boost.cowic.de/rc/pdf/ includes the libraries and tools: Accumulators Algorithm/String Asio Bimap Bind ConceptCheck Config DateTime ForEach Function Functional/Hash Interprocess Intrusive Iterator Lambda Logic Math/Complex Math/Octonion Math/Quaternion Math/GCD Math/Special functions and Distributions Numeric/Conversion (currently has a build problem, not on ftp site) Optional (currently has a build problem, not on ftp site) Proto PtrContainer Pythod/Tutorial Range Regex ScopeExit Signals Spirit/Phoenix StaticAssert Thread (currently has a build problem, not on ftp site) TR1 TypeTraits Typeof Units Unordered Variant Xpressive BoostBook (currently has a build problem, not on ftp site) Boost.Jam Boost.Build Quickbook. I'd be grateful if all the Boost library authors that are using QuickBook/BoostBook/DocBook could take a look at their PDF's and check that they're OK, users too if you're willing! Also if anyone would rather that their library wasn't included in this build please speak up now - eventually the plan is make these available as a sourceforge download. The following default build options have now been added to the fo.xsl stylesheet customization layer, let me know if anyone is violently opposed to these: * No indent on body text (we need all the horizontal space we can get for code blocks). * Left and right page margins 0.5in - a little small, but as above we need all the space we can get. * Paper type is A4 - it's an ISO standard, and just a little smaller than US letter, so should print OK on both. * Draft mode is turned off so we don't try and download draft.png just in case. * SVG graphics are used for admonishments. * Default path to search for images (if not overridden in a library's Jamfile) is the SVN repository: allows most (but not all) libraries to be built as PDF's without having to change their Jamfiles. Known TODO's ~~~~~~~~~~~ * Some of the PDF's are badly named: for example the python tutorial is simply "tutorial.pdf", Phoenix is "users_manual.pdf" and Boost.Build is "standalone.pdf". Anyone know how to get Boost.Build to rename a file or else change the name of Boostbook target? * The libraries Conversion, Optional and Thread do not currently build as PDF's - their XML is invalid, looks like an easy fix though - just tweak their usage of hyperlinks at global (i.e. not in a section) scope. I think I can make the changes for this one if their authors agree. * The BoostBook documentation doesn't build as a PDF - Lots of invalid XML - this one looks much harder to fix. I need some help with this one. * Currently only RenderX's XEP FO processor will build all the docs correctly, Apache FOP is *still* not mature enough :-( * There is currently no way to detect overflow of content on the right margin (usually caused by over-long code blocks), ideally this would be made a build error. I've no idea how to achieve this - the things I've tried so far don't seem to work :-( Anyway thanks for your attention, and I'll look forward to your feedback, as well as this list, there is a Wiki site here https://svn.boost.org/trac/boost/wiki/BoostDocs/PDF to track progress, Regards, John Maddock.
John Maddock wrote:
Folks,
SVN commit 51104 to trunk provides the basic support for building all the Boost libraries that can be as PDF's:
Thanks for doing this. Printable documentation for all libraries would be extremely nice.
Known TODO's ~~~~~~~~~~~
* Some of the PDF's are badly named: for example the python tutorial is simply "tutorial.pdf", Phoenix is "users_manual.pdf" and Boost.Build is "standalone.pdf". Anyone know how to get Boost.Build to rename a file or else change the name of Boostbook target?
Something like: install my_pdf_file : some_target_that_produces_badly_named_file : <name>nice_name <location>whatever ; should work. - Volodya
on Sun Feb 08 2009, Vladimir Prus <vladimir-AT-codesourcery.com> wrote:
John Maddock wrote:
Folks,
SVN commit 51104 to trunk provides the basic support for building all the Boost libraries that can be as PDF's:
Thanks for doing this. Printable documentation for all libraries would be extremely nice.
Known TODO's ~~~~~~~~~~~
* Some of the PDF's are badly named: for example the python tutorial is simply "tutorial.pdf", Phoenix is "users_manual.pdf" and Boost.Build is "standalone.pdf". Anyone know how to get Boost.Build to rename a file or else change the name of Boostbook target?
Something like:
install my_pdf_file : some_target_that_produces_badly_named_file : <name>nice_name <location>whatever ;
should work.
Yeah, but might it mess up cross-references? -- Dave Abrahams BoostPro Computing http://www.boostpro.com
David Abrahams wrote:
on Sun Feb 08 2009, Vladimir Prus <vladimir-AT-codesourcery.com> wrote:
John Maddock wrote:
Folks,
SVN commit 51104 to trunk provides the basic support for building all the Boost libraries that can be as PDF's:
Thanks for doing this. Printable documentation for all libraries would be extremely nice.
Known TODO's ~~~~~~~~~~~
* Some of the PDF's are badly named: for example the python tutorial is simply "tutorial.pdf", Phoenix is "users_manual.pdf" and Boost.Build is "standalone.pdf". Anyone know how to get Boost.Build to rename a file or else change the name of Boostbook target?
Something like:
install my_pdf_file : some_target_that_produces_badly_named_file : <name>nice_name <location>whatever ;
should work.
Yeah, but might it mess up cross-references?
I get the impression that each PDF is produced independently, in which case -- do cross-references already work? Or I could have misunderstood what is desired here :-) - Volodya
Something like:
install my_pdf_file : some_target_that_produces_badly_named_file : <name>nice_name <location>whatever ;
should work.
Yeah, but might it mess up cross-references?
Cross references between libraries are effectively broken anyway.... but that said, there may not be any as I don't recall seeing any "Can't find LINKEND" messages from the build. John. PS That reminds me of one more TODO: Links to library headers and source code are all broken as these are relative links that depend upon the location of the html docs, anyone know how we can rewrite those URL's during the build?
2009/2/9 John Maddock <john@johnmaddock.co.uk>:
Links to library headers and source code are all broken as these are relative links that depend upon the location of the html docs, anyone know how we can rewrite those URL's during the build?
It could be done in the pdf xslt, although it's probably better if it was done in an extra build step. It'd be a bit of a hack. It might be relevant that I'm going to post a patch for this feature request soon: https://svn.boost.org/trac/boost/ticket/1166 If we have a special url for links to other parts of boost, then we could just strip those links out. Daniel
Links to library headers and source code are all broken as these are relative links that depend upon the location of the html docs, anyone know how we can rewrite those URL's during the build?
It could be done in the pdf xslt, although it's probably better if it was done in an extra build step. It'd be a bit of a hack.
It might be relevant that I'm going to post a patch for this feature request soon:
https://svn.boost.org/trac/boost/ticket/1166
If we have a special url for links to other parts of boost, then we could just strip those links out.
Thanks Daniel, that patch would be really useful - especially if it'll work for PDF's as well as the HTML output :-) Ping me if I can help, John.
Something like:
install my_pdf_file : some_target_that_produces_badly_named_file : <name>nice_name <location>whatever ;
should work.
I tried adding: install pdf-python-install : ../../libs/python/doc/tutorial/doc//tutorial : <location>. <name>python_tutorial.pdf <install-type>PDF <format>pdf ; But get a load of Boost.Build errors: d:/data/boost/Trunk/tools/build/v2/tools\stage.jam:143: in construct from module object(install-target-class)@439 error: When <name> property is used in 'install', only one source is allowed d:/data/boost/Trunk/tools/build/v2/build\targets.jam:1244: in object(install-target-class)@439.generate from module object(install-target-class)@439 d:/data/boost/Trunk/tools/build/v2/build\targets.jam:767: in generate-really from module object(main-target)@444 d:/data/boost/Trunk/tools/build/v2/build\targets.jam:739: in object(main-target)@444.generate from module object(main-target)@444 d:/data/boost/Trunk/tools/build/v2/build\targets.jam:257: in object(project-target)@433.generate from module object(project-target)@433 d:/data/boost/Trunk/tools/build/v2\build-system.jam:682: in load from module build-system d:\data\boost\Trunk\tools\build\v2/kernel\modules.jam:283: in import from module modules d:\data\boost\Trunk\tools\build\v2\kernel\bootstrap.jam:138: in boost-build from module d:\data\boost\Trunk\boost-build.jam:17: in module scope from module Any ideas or workarounds? Thanks, John.
John Maddock wrote:
Beta builds of the PDF's are available for download from http://boost.cowic.de/rc/pdf/ includes the libraries and tools:
Accumulators
<snip>
ForEach <snip> Proto <snip> Xpressive <snip>
I'd be grateful if all the Boost library authors that are using QuickBook/BoostBook/DocBook could take a look at their PDF's and check that they're OK, users too if you're willing!
These 4 look good to me. A million thanks for taking the lead on this, John. -- Eric Niebler BoostPro Computing http://www.boostpro.com
John Maddock <john <at> johnmaddock.co.uk> writes:
Folks,
SVN commit 51104 to trunk provides the basic support for building all the Boost libraries that can be as PDF's:
Bimap
Some of the figures are too big for the page. See page 4 of bimap for example. Looks great so far otherwise... Thanks, Joel
Folks,
SVN commit 51104 to trunk provides the basic support for building all the Boost libraries that can be as PDF's:
Bimap
Some of the figures are too big for the page. See page 4 of bimap for example.
Looks great so far otherwise...
Thanks,
Joel
It's really a great achievement to make pdf doc of these libs available. Especially for such a beatifully documented lib as bimap. :-) Tons of thanks from one of the boost user to you John! B/Rgds Max
It's really a great achievement to make pdf doc of these libs available. Especially for such a beatifully documented lib as bimap.
And, we are all awaiting similar docs for rest of the libs too, specially: graph, mpl. I am a bit surprised not to see the same for flyweight, scopexit, swap, treap, treap_set and treap_multiset which are the new additions. -Chandra ********************************************************************** This communication contains information which is confidential and may also be legally privileged. It is for the exclusive use of the intended recipient(s). If you are not the intended recipient(s), disclosure, copying, distribution, or other use of, or action taken or omitted to be taken in reliance upon, this communication or the information in it is prohibited and maybe unlawful. If you have received this communication in error please notify the sender by return email, delete it from your system and destroy any copies. **********************************************************************
It's really a great achievement to make pdf doc of these libs available. Especially for such a beatifully documented lib as bimap.
And, we are all awaiting similar docs for rest of the libs too, specially: graph, mpl.
Since these aren't built via DocBook, we have no means of generating PDF's for these for now.
I am a bit surprised not to see the same for flyweight, scopexit, swap, treap, treap_set and treap_multiset which are the new additions.
Scope_exit is in the list already, the others aren't using quickbook/boostbook/docbook. John.
2009/2/9 John Maddock <john@johnmaddock.co.uk>:
I am a bit surprised not to see the same for flyweight, scopexit, swap, treap, treap_set and treap_multiset which are the new additions.
Scope_exit is in the list already, the others aren't using quickbook/boostbook/docbook.
The treap containers are part of intrusive, so they're documented in that pdf. Daniel
It's really a great achievement to make pdf doc of these libs available. Especially for such a beautifully documented lib as bimap.
And, we are all awaiting similar docs for rest of the libs too, specially: graph, mpl.
It seems that I'm not alone. :-)
I am a bit surprised not to see the same for flyweight, scopexit, swap, treap, treap_set and treap_multiset which are the new additions.
-Chandra
B/Rgds Max
2009/2/10 Max <loadcom@sina.com>:
It's really a great achievement to make pdf doc of these libs available. Especially for such a beautifully documented lib as bimap.
And, we are all awaiting similar docs for rest of the libs too, specially: graph, mpl.
It seems that I'm not alone. :-)
MPL actually has a pdf of it's reference manual at 'libs/mpl/doc/refmanual.pdf' in your local copy of boost. But it was last updated for four years ago. If anyone fancies looking into generating an up to date pdf, or pdfs for other documentation written with python docutils we could probably add that to the boostbook pdfs. Daniel
Some of the figures are too big for the page. See page 4 of bimap for example.
Looks great so far otherwise...
I'll look into that, might have to fixed within bimap though (with a smaller graphic), I'll check to see if there are any magic xsl-param options that can help first though... John.
2009/2/9 John Maddock <john@johnmaddock.co.uk>:
I'll look into that, might have to fixed within bimap though (with a smaller graphic), I'll check to see if there are any magic xsl-param options that can help first though...
If it's a png, I think you can fix this by changing the file's meta data. I did this for the diagram in unordered, although I can't remember how of the top of my head. Daniel
I'll look into that, might have to fixed within bimap though (with a smaller graphic), I'll check to see if there are any magic xsl-param options that can help first though...
If it's a png, I think you can fix this by changing the file's meta data. I did this for the diagram in unordered, although I can't remember how of the top of my head.
Ah yes, good point: I used IrfanView to batch convert all the Bimap images to 120dpi and the PDF looks much better now (HTML display is unchanged). Thanks, John.
-----Original Message----- From: boost-bounces@lists.boost.org [mailto:boost-bounces@lists.boost.org] On Behalf Of John Maddock Sent: 08 February 2009 18:10 To: boost@lists.boost.org Subject: [boost] [1.38] Beta release of PDF documentation (and some help needed).
SVN commit 51104 to trunk provides the basic support for building all the Boost libraries that can be as PDF's:
A Major Step Forward for Boost! Thanks John. Paul PS And although automatic indexing isn't is a good as a manual one might be, I still think it will be very useful. (I am still learning how to tweak it to produce better indexes, with invaluable assistance of course).
On Sun, Feb 8, 2009 at 6:09 PM, John Maddock <john@johnmaddock.co.uk> wrote:
Folks,
SVN commit 51104 to trunk provides the basic support for building all the Boost libraries that can be as PDF's:
<snip>
Regards, John Maddock.
Nice - I've always liked PDF docs. One question, John - is there any intent to (at some point) somehow collate the individual PDFs into a single, 'Boost documentation' PDF document - or is that something that's trivially easy for the end-user to do once they have the individual files? Stuart Dootson
is there any intent to (at some point) somehow collate the individual PDFs into a single, 'Boost documentation' PDF document - or is that something that's trivially easy for the end-user to do once they have the individual files?
Getting all the boost docs in a single pdf will be nice. Though I use pdftk to do it for me now. HTH, Chandra ********************************************************************** This communication contains information which is confidential and may also be legally privileged. It is for the exclusive use of the intended recipient(s). If you are not the intended recipient(s), disclosure, copying, distribution, or other use of, or action taken or omitted to be taken in reliance upon, this communication or the information in it is prohibited and maybe unlawful. If you have received this communication in error please notify the sender by return email, delete it from your system and destroy any copies. **********************************************************************
SVN commit 51104 to trunk provides the basic support for building all the Boost libraries that can be as PDF's:
Nice - I've always liked PDF docs. One question, John - is there any intent to (at some point) somehow collate the individual PDFs into a single, 'Boost documentation' PDF document - or is that something that's trivially easy for the end-user to do once they have the individual files?
That would be one very big PDF ;-) Seriously though the DocBook XSL stylesheets don't scale well to very large documents - and if one library's XML has a SNAFU then nothing builds :-( That's why these will all be separate PDF's for the time being. John.
On Mon, Feb 9, 2009 at 10:49 AM, John Maddock <john@johnmaddock.co.uk> wrote:
SVN commit 51104 to trunk provides the basic support for building all the Boost libraries that can be as PDF's:
Nice - I've always liked PDF docs. One question, John - is there any intent to (at some point) somehow collate the individual PDFs into a single, 'Boost documentation' PDF document - or is that something that's trivially easy for the end-user to do once they have the individual files?
That would be one very big PDF ;-)
Seriously though the DocBook XSL stylesheets don't scale well to very large documents - and if one library's XML has a SNAFU then nothing builds :-(
Out of interest - how is it that the stylesheets don't scale well? I would have thought they would stay the same no matter how large the document was?
That's why these will all be separate PDF's for the time being.
John.
I'll give pdftk a go at some point, see what that produces through merging the documents. Stuart
Stuart Dootson wrote:
On Mon, Feb 9, 2009 at 10:49 AM, John Maddock <john@johnmaddock.co.uk> wrote:
SVN commit 51104 to trunk provides the basic support for building all the Boost libraries that can be as PDF's:
Nice - I've always liked PDF docs. One question, John - is there any intent to (at some point) somehow collate the individual PDFs into a single, 'Boost documentation' PDF document - or is that something that's trivially easy for the end-user to do once they have the individual files?
That would be one very big PDF ;-)
Seriously though the DocBook XSL stylesheets don't scale well to very large documents - and if one library's XML has a SNAFU then nothing builds :-(
Out of interest - how is it that the stylesheets don't scale well? I would have thought they would stay the same no matter how large the document was?
But the time it takes to process input files depends on input document, and tends to be large. - Volodya
Seriously though the DocBook XSL stylesheets don't scale well to very large documents - and if one library's XML has a SNAFU then nothing builds :-(
Out of interest - how is it that the stylesheets don't scale well? I would have thought they would stay the same no matter how large the document was?
Time taken for a 1000 page doc is not 10x the time for a 100 page doc: some things, certainly index generation (which we're not using at present, but I'm experimenting with now) and also seemingly hyperlinking and document outlining require more than O(N) time, probably more like O(N^2) for indexing. It's the XSLT transforms that take the time BTW, not the FO->PDF transform. Basically building all of Boost takes more or less all day, where as all the separate PDF's are built in 30-40 minutes total. John.
On Mon, Feb 9, 2009 at 11:15 AM, John Maddock <john@johnmaddock.co.uk> wrote:
Seriously though the DocBook XSL stylesheets don't scale well to very large documents - and if one library's XML has a SNAFU then nothing builds :-(
Out of interest - how is it that the stylesheets don't scale well? I would have thought they would stay the same no matter how large the document was?
Time taken for a 1000 page doc is not 10x the time for a 100 page doc: some things, certainly index generation (which we're not using at present, but I'm experimenting with now) and also seemingly hyperlinking and document outlining require more than O(N) time, probably more like O(N^2) for indexing.
It's the XSLT transforms that take the time BTW, not the FO->PDF transform.
Basically building all of Boost takes more or less all day, where as all the separate PDF's are built in 30-40 minutes total.
John.
Gotcha - thanks Stuart
John Maddock wrote:
Time taken for a 1000 page doc is not 10x the time for a 100 page doc: some things, certainly index generation (which we're not using at present, but I'm experimenting with now) and also seemingly hyperlinking and document outlining require more than O(N) time, probably more like O(N^2) for indexing.
XSLT has a feature called "keys" that lets you re-write O(n^2) code to be O(N log N). xsltproc has a --profile option that can help identify where the time is spent. Beware, however, that libxslt [and I guess that you're using libxslt, right?] has in the past had bugs in its implementation of this relatively rarely used feature. Phil.
XSLT has a feature called "keys" that lets you re-write O(n^2) code to be O(N log N). xsltproc has a --profile option that can help identify where the time is spent. Beware, however, that libxslt [and I guess that you're using libxslt, right?] has in the past had bugs in its implementation of this relatively rarely used feature.
Yes we're using xsltproc, and to be honest, this looks to be more complex that I want to get into at present :-( John.
Just a note that a rebuild of the docs is now at Changes: * Bimap images are now set at 120dpi and display correctly. * numeric/conversion, optional and thread libraries are now included as well. John.
* Bimap images are now set at 120dpi and display correctly. * numeric/conversion, optional and thread libraries are now included as well.
As is BoostBook now, all at http://boost.cowic.de/rc/pdf/. John.
participants (11)
-
Chandra Kumar -
Daniel James -
David Abrahams -
Eric Niebler -
Joel -
John Maddock -
Max -
Paul A. Bristow -
Phil Endecott -
Stuart Dootson -
Vladimir Prus