For now, I have quite a few PDF docs in the PDF directory of the sandbox (the max file size of the vault is too limiting for the larger libs docs).

BTW, if anyone with quickbook/boostbook style docs would like pdf's generated for them, then I can probably generate a few more...

Thanks for the offer, John. Generation of PDF docs on OS X is a disaster in my experience - if you get the chance, I would very much appreciate it if you could generate PDF docs for Boost.Units. Thanks, Matthias

-----Original Message----- From: boost-bounces@lists.boost.org [mailto:boost-bounces@lists.boost.org] On Behalf Of John Maddock Sent: 04 November 2008 10:25 To: boost@lists.boost.org Subject: Re: [boost] location for PDF docs? I've added a first cut to the sandbox at pdf/units/release/units

(https://svn.boost.org/svn/boost/sandbox/pdf/units/release/units.pdf)

Very nice :-) But I can't see where the revision date shown on the first page of the html version, for example: Last revised: November 04, 2008 at 14:22:16 GMT appears on pdf versions. It would be really good if we could make this appear on the pdf? (The pdf file creation is in the Aodbe reader properties, but a last edit date would be better). (I also note that the math toolkit docs most helpfully include a line "This manual is also available in printer friendly PDF format." where there is a link to the docs - in the .qbk source thus This manual is also available in [@http://svn.boost.org/svn/boost/sandbox/pdf/math/release/math.pdf printer friendly PDF format]. If we put the docs in a 'standard' sourceforge location as suggested by Eric, we will need to change this. If we plan to put all the pdf versions somewhere 'standard', it would be helpful for all documentation to include this link (for their stuff). Paul --- Paul A Bristow Prizet Farmhouse, Kendal, Cumbria UK LA8 8AB +44 1539561830 & SMS, Mobile +44 7714 330204 & SMS pbristow@hetp.u-net.com

AMDG John Maddock wrote:

I've added a first cut to the sandbox at pdf/units/release/units (https://svn.boost.org/svn/boost/sandbox/pdf/units/release/units.pdf) using a patched version of your Jamfile (let me know if you want me to commit the attached patch).

+ <format>pdf:<xsl:param>img.src.path=$(images_location)/ This path never gets embedded in the pdf, only the images used do, right?

Things I've noticed:

* Links to source files and headers are broken, I think this may be fixable with some more xsl:param's, but haven't looked into it.

The links in the reference are controlled by <xsl:param>boost.root. The others are in quickbook and are set up for generating html. I've never been able to come with a good way to control them. In Christ, Steven Watanabe

I've added a first cut to the sandbox at pdf/units/release/units (https://svn.boost.org/svn/boost/sandbox/pdf/units/release/units.pdf ) using a patched version of your Jamfile (let me know if you want me to commit the attached patch).

Thanks - the patch looks fine to me, if you don't mind committing it...

* The PNG images don't look that good in PDF's, we have the ability to embed SVG's or PDF's (haven't tried the latter though) if you want to improve these: but it would require some editing of the quickbook source.

I'll take a look at this and see how easily I can generate SVG images from LaTeX source; PDFs should be easy to generate, so perhaps I should try that first...

Also if you want the page setup options changed/tweaked let me know as now I've got it working I can regenerate it pretty quickly...

Thanks again. I'll take a look at the generated PDF and get back to you. Matthias

Paul A Bristow wrote:

...

...

I'll take a look at this and see how easily I can generate SVG images from LaTeX source; PDFs should be easy to generate, so perhaps I should try that first...

The unfinished code to generate SVG graphs as used for the Math Toolkit exists, but is largely documentation-deficient :-(

But if you just want simple XY plots and have data values that could be read into (or generated by) a C++ array, I could try to produce some plots for you.

I believe they're mostly equations in Latex form, not plots. In which case generating PDF's for each equation should be viable: both XEP and FOP support extracting/embedding them in PDF output, but I'm not sure how the toolchain as a whole responds to PDF's since it's not something I've tried yet. John.

-----Original Message----- From: boost-bounces@lists.boost.org [mailto:boost-bounces@lists.boost.org] On Behalf Of Eric Niebler Sent: 03 November 2008 19:19 To: boost@lists.boost.org Subject: Re: [boost] location for PDF docs?

I can think of two logical places to put the PDFs: - A dedicated location under www.boost.org/doc - Alongside the release tarballs on sourceforge.

The problem with both of these locations is that average boost developers do not have upload access. We can make it part of the release procedure that developers can optionally provide the release manager with PDFs, but this is one more thing for developers to forget to do, and more work for the release manager.

Maybe both locations should have a link to documentation in alternate formats,

Since we don't have an automatic indexing system for Quickbook (or other) documentation (A GSoC project?), the PDF version has a distinct advantage in that one can use the PDF reader 'find' button. As an author, I've found this lifesaving ;-) and the docs can actually be hosted someplace else. A logical

place would be http://boost.sf.net/doc -- any boost developer can upload a file there.

The latter sounds a good place to me. It is certainly a big hurdle for those new to Boost to download all of Boost just to access the docs. Might this also help by being better indexed by Google? (Thus helping potential users to see what's on offer). (FWIW I note that googling "student t distribution Boost" gets us top of the page, student t distribution C++ doesn't do quite as well). We also want to reduce the hassle and time delay in getting documentation changes visible. While we want to maintain tight control on source code, making it easier to make documentation corrections and elucidations is good. Paul --- Paul A Bristow Prizet Farmhouse, Kendal, Cumbria UK LA8 8AB +44 1539561830 & SMS, Mobile +44 7714 330204 & SMS pbristow@hetp.u-net.com

-----Original Message----- From: boost-bounces@lists.boost.org [mailto:boost-bounces@lists.boost.org] On Behalf Of Vladimir Prus Sent: 04 November 2008 10:10 To: boost@lists.boost.org Subject: Re: [boost] location for PDF docs?

Paul A Bristow wrote:

...

...

-----Original Message----- From: boost-bounces@lists.boost.org [mailto:boost-bounces@lists.boost.org] On Behalf Of Eric Niebler Sent: 03 November 2008 19:19 To: boost@lists.boost.org Subject: Re: [boost] location for PDF docs? Since we don't have an automatic indexing system for Quickbook (or other) documentation (A GSoC project?),

Boostbook docs have automatic indexing system, for some definition of 'automatic'. Please see

http://www.boost.org/boost-build2/doc/html/ix01.html

Each index entry must be explicitly provided in the source (where the index term is defined). However, collection of all index entries at a single page is done by some magic.

This *looks* nice - but 1 I don't see where to define the index entries. Can you point me to the instructions for this. 2 It will be hard work for a 500 page document :-( (We already have a several libraries that are this big - and it is for big documents that indexing is most useful). 3 Would it be more practical if the author had a list of all possible index terms from the document and could then generate a subset by *excluding* ones that are not considered worth an entry. Could Quickbook or some other tool output this list? Once generated, this 'exclusion list' could be re-used? Paul --- Paul A Bristow Prizet Farmhouse, Kendal, Cumbria UK LA8 8AB +44 1539561830 & SMS, Mobile +44 7714 330204 & SMS pbristow@hetp.u-net.com

-----Original Message----- From: boost-bounces@lists.boost.org [mailto:boost-bounces@lists.boost.org] On Behalf Of Vladimir Prus Sent: 05 November 2008 10:07 To: boost@lists.boost.org Subject: Re: [boost] location for PDF docs?

...

...

Boostbook docs have automatic indexing system, for some definition of 'automatic'. Please see

http://www.boost.org/boost-build2/doc/html/ix01.html

Each index entry must be explicitly provided in the source (where the index term is defined). However, collection of all index entries at a single page is done by some magic.

This *looks* nice - but

1 I don't see where to define the index entries. Can you point me to the instructions for this.

In docbook, you put something like:

<indexterm> <primary>main target</primary> <secondary>declaration syntax</secondary> </indexterm>

Docbook documentation has the details.

OK thanks - I aw looking at BoostBook :-( http://www.sagehill.net/docbookxsl/GenerateIndex.html#Indexterms gives the details.

...

2 It will be hard work for a 500 page document :-(

(We already have a several libraries that are this big - and it is for big documents that indexing is most useful).

Of course. I'm not claiming searchability of PDF is useless -- in fact, I think PDFs have a number of advantages, including searchablility, printability, and presence of annotation tools -- and it's deplorable that we don't officially provide PDF for everything. It may be a problem with fop, or some other issue, I don't know.

It's mainly getting the long toolchain working. John Maddock, for one, has got it cracked - and with his help I'm also re-generating the Math Toolkit library into html and pdf with no hassle.

...

3 Would it be more practical if the author had a list of all possible index terms from the document and could then generate a subset by *excluding* ones that are not considered worth an entry. Could Quickbook or some other tool output this list? Once generated, this 'exclusion list' could be re-used?

Will that work. Say, in Boost.Build case, "main target" is used everywhere, so adding all locations to the index won't work very well. Often, the phrase to appear in the index is not exactly the phrase present in the text. And while usually, a term should be defined on the first use, it could be that the first definition is brief, and the accurate definition is present later.

Boost.Build index is bit lean presently, and I'd love to have some automated tool, but I'm not sure how they could work.

Yup - it's never going to produce a really good index without some human intervention. Even a way of marking a word as an index entry in the Quickbook source would be a major help. Paul --- Paul A Bristow Prizet Farmhouse, Kendal, Cumbria UK LA8 8AB +44 1539561830 & SMS, Mobile +44 7714 330204 & SMS pbristow@hetp.u-net.com

John Maddock wrote:

...

Will that work. Say, in Boost.Build case, "main target" is used everywhere, so adding all locations to the index won't work very well. Often, the phrase to appear in the index is not exactly the phrase present in the text. And while usually, a term should be defined on the first use, it could be that the first definition is brief, and the accurate definition is present later. Boost.Build index is bit lean presently, and I'd love to have some automated tool, but I'm not sure how they could work.

Well.... off the top of my head... and this probably wouldn't work for the Boost.Build docs, but for a library one could:

* For each class, function or macro name: - if the name appears in a section title add a primary entry. - if the name appears in the body text add a secondary entry. * Optionally include any other terms that are manually specified. * Optionally exclude any other terms that are manually specified.

I guess we could even scan headers for a list of possible terms to include?

But this would require an extra processing step in the toolchain (to insert the terms into the Docbook XML), how hard would that be to add?

Adding a new step is easy. The hard thing is writing it, preferably does not using tools that nobody in the world has installed by default ;-) - Volodya

John Maddock wrote:

Vladimir Prus wrote:

...

...

Adding a new step is easy. The hard thing is writing it, preferably does not using tools that nobody in the world has installed by default ;-)

Wel... how about a C++ program?

Fine from my POV.

I'm tied up right now (really must proofread some of the C0x draft std up for ballot), but I think I will try and look into this some more.

Great. - Volodya

-----Original Message----- From: boost-bounces@lists.boost.org [mailto:boost-bounces@lists.boost.org] On Behalf Of Eric Niebler Sent: 05 November 2008 18:39 To: boost@lists.boost.org Subject: Re: [boost] location for PDF docs?

It would probably require "nothing more than" some XSLT hacking. Although I've recently become a little disillusioned with automatic documentation generation. There's just no substitute for doing it by hand.

As for Quickbook, adding support for Docbook's <indexterm> is a trivial matter. I can do it in a day or two. Perhaps:

[indexterm [primary][secondary]]

where [secondary] is optional.

That sounds pretty useful to me - if much hard work for the document writer. It would be very useful (while you are at it ;-) if the PDF Subject and keywords fields could be filled. And a ISBN and Dewey decimal library classification field could be added (like title authors, purpose ...) to aid getting these documents into the normal library catalogs. Thanks in advance ;-) Paul --- Paul A Bristow Prizet Farmhouse, Kendal, Cumbria UK LA8 8AB +44 1539561830 & SMS, Mobile +44 7714 330204 & SMS pbristow@hetp.u-net.com

-----Original Message----- From: boost-bounces@lists.boost.org [mailto:boost-bounces@lists.boost.org] On Behalf Of Eric Niebler Sent: 05 November 2008 19:09 To: boost@lists.boost.org Subject: Re: [boost] location for PDF docs?

Paul A Bristow wrote:

...

It would be very useful (while you are at it ;-)

if the PDF Subject and keywords fields could be filled.

And a ISBN and Dewey decimal library classification field

could be added (like title authors, purpose ...) to aid getting these

...

documents into the normal library catalogs.

Thanks in advance ;-)

Sorry to disappoint, but I don't believe that's something I can do in quickbook. It would probably require someone to dig into the fo.xsl transform. I encourage you to look into it. Thanks in advance. ;-)

Well actually I have :-) But not wishing to rush in where angels fear to tread (again), I didn't actually start hacking. What I'd like to do is to copy the existing stuff for Author and Title and do the same for Subject and keywords. Similarly I'd like to copy the purpose field and use that for ISBN and for Dewey. (Could also usefully emit an <isbn> ... </isbn> block?) But maybe there are difficulties that a brief glance at the code has not revealed to me. Should I look further? Paul --- Paul A Bristow Prizet Farmhouse, Kendal, Cumbria UK LA8 8AB +44 1539561830 & SMS, Mobile +44 7714 330204 & SMS pbristow@hetp.u-net.com

-----Original Message----- From: boost-bounces@lists.boost.org [mailto:boost-bounces@lists.boost.org] On Behalf Of John Maddock Sent: 06 November 2008 16:55 To: boost@lists.boost.org Subject: Re: [boost] location for PDF docs?

Paul A Bristow wrote:

...

...

But not wishing to rush in where angels fear to tread (again), I didn't actually start hacking.

What I'd like to do is to copy the existing stuff for Author and Title and do the same for Subject and keywords.

Do you mean copy the code that currently handles Author and Title, to handle Subject and Keywords?

Yes. Though I have to confess I haven't checked if or how the tools downstream will deal with it :-( Time to FTFM perhaps?

...

...

Similarly I'd like to copy the purpose field and use that for ISBN and for Dewey.

(Could also usefully emit an <isbn> ... </isbn> block?)

<isbn> is deprecated in favour of <biblioid>.

Ok fine - I'm way out of date :-) I would like to see the full document id in small font at the bottom of every page of the document, but I haven't researched how to do that either yet. I also note that the Document properties (File, Properties) shows the pdf creation date - this is some help in checking version date, though not our ideal of the date of last .qbk file edit. This should probably be close to the date of the html file generation. Paul PS Disappointingly :-(( I also note that trying to digital sign the math toolkit pdf it reports "This document is PDF/SigQ compliant. 4002 PDF contect contains errors Malformed drawing instructions: Syntax error. Page content violates the grammar for page content definition. For example, the instruction might specify drawing a square but the syntax for doing it is incorrect. 1000 The document contains hidden actions that may not be intended or known by the end user. Actions include JavaScript actions (document open, save, etc.), playing multimedia, executing a menu item, etc. 1002 The document contains comments. Comments' visual appearances may change based on external variables. 1008 Disallowed action type: URI. The document contains hidden actions that may not be intended or known by the end user. Actions include JavaScript actions (document open, save, etc.), playing multimedia, executing a menu item, etc. " but I doubt if we should worry? --- Paul A Bristow Prizet Farmhouse, Kendal, Cumbria UK LA8 8AB +44 1539561830 & SMS, Mobile +44 7714 330204 & SMS pbristow@hetp.u-net.com

Eric Niebler wrote:

...

John Maddock wrote:

...

Well.... off the top of my head... and this probably wouldn't work for the Boost.Build docs, but for a library one could:

* For each class, function or macro name: - if the name appears in a section title add a primary entry. - if the name appears in the body text add a secondary entry. * Optionally include any other terms that are manually specified. * Optionally exclude any other terms that are manually specified.

It would probably require "nothing more than" some XSLT hacking. Although I've recently become a little disillusioned with automatic documentation generation. There's just no substitute for doing it by hand.

Nod, understood. Not so sure about the XSLT hacking though... I think I'd stand better chances going bungie jumping with no rope!

...

As for Quickbook, adding support for Docbook's <indexterm> is a trivial matter. I can do it in a day or two. Perhaps:

[indexterm [primary][secondary]]

where [secondary] is optional.

Isn't this trivial with templates (untested): [template indexterm [primary][secondary] '''<indexterm><primary>'''[primary]'''</primary><secondary>'''[secondary]'''</secondary></indexterm>'''] ? Cheers, John.