[1.35] Where to place PDF versions of docs?
Folks I think we need to get organised with PDF's now that we have many more libraries with quickbook/boostbook docs. I don't particularly want these in SVN trunk: apart from anything else it needlessly bloats the download size if folks are happy with HTML versions. Previously I've placed these in the vault, but there's a file size limit there and the new Boost.Math PDF's are too large :-( Another alternative would be the sourceforge file release system, but I don't believe all developers have access to that? So.... how about we either have a directory in the "website" area of SVN for these, or else in the sandbox maybe? Thoughts? John.
John Maddock wrote:
Folks I think we need to get organised with PDF's now that we have many more libraries with quickbook/boostbook docs.
I don't particularly want these in SVN trunk: apart from anything else it needlessly bloats the download size if folks are happy with HTML versions. Previously I've placed these in the vault, but there's a file size limit there and the new Boost.Math PDF's are too large :-(
Another alternative would be the sourceforge file release system, but I don't believe all developers have access to that?
So.... how about we either have a directory in the "website" area of SVN for these, or else in the sandbox maybe?
Thoughts? John.
How are the HTML docs handled? Are the generated HTML files checked into the website's SVN? Seems odd to check generated files into version control. Maybe the Documentation link on the Boost's home page could take you to a page that had links to automatically generated PDFs in addition to the HTML. -- Eric Niebler Boost Consulting www.boost-consulting.com
Eric Niebler wrote:
How are the HTML docs handled? Are the generated HTML files checked into the website's SVN?
The boost.python tutorial's html is in fact checked into the boost.python repository itself. I don't know about other libraries.
Seems odd to check generated files into version control. Maybe the Documentation link on the Boost's home page could
Not only odd, but error-prone. (I was just asked to check conflicts in an attempted merge from the last release branch to trunk, because the html in trunk was generated by a different tool than the one on the branch, resulting in many benign conflicts.
take you to a page that had links to automatically generated PDFs in addition to the HTML.
I see multiple issues here: 1) The packages are even bigger than necessary as they bundle documentation. IMO it would be good to split packages on that axis, too, i.e. provide documentation separately, as an add-on. 2) Since developers are not expected to have all the required tools installed, the produced docs are in the repository, too. The way I have seen this handled in other cases is that docs are only to be built (by default) on previleged hosts that have all the right tools set up. The results of such builds are then made available through the common website. (Of course authors *can* build html and pdf themselves, if they make sure they have the proper build environment set up first.) Regards, Stefan -- ...ich hab' noch einen Koffer in Berlin...
Stefan Seefeld wrote:
Eric Niebler wrote:
How are the HTML docs handled? Are the generated HTML files checked into the website's SVN?
The boost.python tutorial's html is in fact checked into the boost.python repository itself. I don't know about other libraries.
Seems odd to check generated files into version control. Maybe the Documentation link on the Boost's home page could
Not only odd, but error-prone. (I was just asked to check conflicts in an attempted merge from the last release branch to trunk, because the html in trunk was generated by a different tool than the one on the branch, resulting in many benign conflicts.
Checking in generated documentation that is also generated as part of the BoostBook chain is a waste. It will not be used from the POV of the release since the docs will end up in the boost-root/doc location, not in the libs/<library>/doc location. Other types of generated docs do need to be checked into SVN as otherwise they will not show up in the release. Hence until everyone switches to BoostBook we will have HTML docs in SVN.
take you to a page that had links to automatically generated PDFs in addition to the HTML.
I see multiple issues here:
1) The packages are even bigger than necessary as they bundle documentation. IMO it would be good to split packages on that axis, too, i.e. provide documentation separately, as an add-on.
Perhaps, not a concern for this release though. Since we clearly can't change this now ;-)
2) Since developers are not expected to have all the required tools installed, the produced docs are in the repository, too. The way I have seen this handled in other cases is that docs are only to be built (by default) on previleged hosts that have all the right tools set up. The results of such builds are then made available through the common website.
Historically the release manager has built the BoostBook docs that go into the release, and are checked into SVN. We also want to have up to date docs available, hence it's always been a goal to have a documentation build server. Such trunk & release built docs would be available in the same way the docs are available now in the beta site. -- -- Grafik - Don't Assume Anything -- Redshift Software, Inc. - http://redshift-software.com -- rrivera/acm.org - grafik/redshift-software.com -- 102708583/icq - grafikrobot/aim - grafikrobot/yahoo
Stefan Seefeld wrote:
Eric Niebler wrote:
How are the HTML docs handled? Are the generated HTML files checked into the website's SVN?
The boost.python tutorial's html is in fact checked into the boost.python repository itself. I don't know about other libraries.
Seems odd to check generated files into version control. Maybe the Documentation link on the Boost's home page could
Not only odd, but error-prone. (I was just asked to check conflicts in an attempted merge from the last release branch to trunk, because the html in trunk was generated by a different tool than the one on the branch, resulting in many benign conflicts.
take you to a page that had links to automatically generated PDFs in addition to the HTML.
I see multiple issues here:
1) The packages are even bigger than necessary as they bundle documentation. IMO it would be good to split packages on that axis, too, i.e. provide documentation separately, as an add-on.
2) Since developers are not expected to have all the required tools installed, the produced docs are in the repository, too. The way I have seen this handled in other cases is that docs are only to be built (by default) on previleged hosts that have all the right tools set up. The results of such builds are then made available through the common website.
(Of course authors *can* build html and pdf themselves, if they make sure they have the proper build environment set up first.)
I agree with all of Stefan's points. I think the only concern for having the docs in there is that if a developer wants a snapshot of (tarball, zip) the package downloaded, he should be able to get the docs too. If it is possible to do 2 (above), a developer can get a snapshot of the repository and have the docs auto-generated in the process, then all is well. Regards, -- Joel de Guzman http://www.boost-consulting.com http://spirit.sf.net
on Thu Nov 01 2007, Eric Niebler <eric-AT-boost-consulting.com> wrote:
John Maddock wrote:
Folks I think we need to get organised with PDF's now that we have many more libraries with quickbook/boostbook docs.
I don't particularly want these in SVN trunk: apart from anything else it needlessly bloats the download size if folks are happy with HTML versions. Previously I've placed these in the vault, but there's a file size limit there and the new Boost.Math PDF's are too large :-(
Another alternative would be the sourceforge file release system, but I don't believe all developers have access to that?
So.... how about we either have a directory in the "website" area of SVN for these, or else in the sandbox maybe?
Thoughts? John.
How are the HTML docs handled? Are the generated HTML files checked into the website's SVN?
In some cases.
Seems odd to check generated files into version control.
Yeah, but can I count on whoever is generating docs to install docutils for my ReST documents? What about the GPL'd Makefile I used to generate PDFs of the iterator docs, which I can't include in the boost distro, but link to from the README?
Maybe the Documentation link on the Boost's home page could take you to a page that had links to automatically generated PDFs in addition to the HTML.
Would be nice, for sure. -- Dave Abrahams Boost Consulting http://www.boost-consulting.com
David Abrahams wrote:
How are the HTML docs handled? Are the generated HTML files checked into the website's SVN?
In some cases.
Seems odd to check generated files into version control.
Yeah, but can I count on whoever is generating docs to install docutils for my ReST documents?
What about the GPL'd Makefile I used to generate PDFs of the iterator docs, which I can't include in the boost distro, but link to from the README?
Right, and the Math PDF can only be built with XEP not FOP (which mangles it up terribly even with the 0.9 release), and then the equations only display correctly if you have the right fonts configured for XEP.... it's not pretty and it's far from ideal, but there you go, that's PDF's for you. Also building the HTML documentation as a single "book" from doc/ simply isn't viable anymore IMO: it doesn't scale well (takes an age to build, breaks at the drop of a hat etc). It worked when we only had a few Boostbook libraries, but we have too many for this now. So we IMO we need a more distributed system similar to the one Robert suggested: we can still have a central "build everything" script as well if desired, but that change is probably for 1.36. For now I just want a location we can all point to for the PDF's, and that the user can browse to see what's available.
Maybe the Documentation link on the Boost's home page could take you to a page that had links to automatically generated PDFs in addition to the HTML.
Would be nice, for sure.
100% agreed. John.
John Maddock wrote:
Also building the HTML documentation as a single "book" from doc/ simply isn't viable anymore IMO: it doesn't scale well (takes an age to build, breaks at the drop of a hat etc). It worked when we only had a few Boostbook libraries, but we have too many for this now.
I think this is an important point -- PDFs have to be *by library*. Full date-time user/reference docs are 400 pages so all of boost would be thousands. Up to now, I've been generating date-time PDFs and putting them on my site which obviously isn't the ideal system. Personally I don't think we're ready to solve this issue in time for 1.35 so I think we should take it as an independent effort. Jeff
-----Original Message----- From: boost-bounces@lists.boost.org [mailto:boost-bounces@lists.boost.org] On Behalf Of Jeff Garland Sent: 02 November 2007 13:23 To: boost@lists.boost.org Cc: Discussion of Boost Documentation Subject: Re: [boost] [Boost-docs] [1.35] Where to place PDF versions of docs?
John Maddock wrote:
I think this is an important point -- PDFs have to be *by library*. Full date-time user/reference docs are 400 pages
as are Math Toolkit ;-)
so all of boost would be thousands. Up to now, I've been generating date-time PDFs and putting them on my site which obviously isn't the ideal system. Personally I don't think we're ready to solve this issue in time for 1.35 so I think we should take it as an independent effort.
I agree - though I have to say that generating pdf for Math Toolkit was a hassle, even after John had cracked the difficult bits. But pdfs are really convenient because you can use your reader's Find to search the whole document. Without automatically generated indexes - something the Quickbook should be able to do, but making it work isn't a trivial task (GSoC project perhaps?) - the pdf has this big advantage over html. So I agree strongly with John that we need to agree a place to put pdfs, and that authors should be tasked with producing pdfs. (Those using Quickbook will now reap the benefits of their investment ;-) Paul --- Paul A Bristow Prizet Farmhouse, Kendal, Cumbria UK LA8 8AB +44 1539561830 & SMS, Mobile +44 7714 330204 & SMS pbristow@hetp.u-net.com
Jeff Garland wrote:
John Maddock wrote:
Also building the HTML documentation as a single "book" from doc/ simply isn't viable anymore IMO: it doesn't scale well (takes an age to build, breaks at the drop of a hat etc). It worked when we only had a few Boostbook libraries, but we have too many for this now.
I think this is an important point -- PDFs have to be *by library*. Full date-time user/reference docs are 400 pages so all of boost would be thousands. Up to now, I've been generating date-time PDFs and putting them on my site which obviously isn't the ideal system. Personally I don't think we're ready to solve this issue in time for 1.35 so I think we should take it as an independent effort.
FWIW, I agree. I'd even venture to suggest that we have one URL for placing all our generated docs (html/pdf). Then, we can simply redirect to it from our library doc's index.html. That would mean though that people who download a snapshot needs to have net access to get the docs. Regards, -- Joel de Guzman http://www.boost-consulting.com http://spirit.sf.net
Joel de Guzman wrote:
Jeff Garland wrote:
John Maddock wrote:
Also building the HTML documentation as a single "book" from doc/ simply isn't viable anymore IMO: it doesn't scale well (takes an age to build, breaks at the drop of a hat etc). It worked when we only had a few Boostbook libraries, but we have too many for this now. I think this is an important point -- PDFs have to be *by library*. Full date-time user/reference docs are 400 pages so all of boost would be thousands. Up to now, I've been generating date-time PDFs and putting them on my site which obviously isn't the ideal system. Personally I don't think we're ready to solve this issue in time for 1.35 so I think we should take it as an independent effort.
FWIW, I agree. I'd even venture to suggest that we have one URL for placing all our generated docs (html/pdf). Then, we can simply redirect to it from our library doc's index.html. That would mean though that people who download a snapshot needs to have net access to get the docs.
I don't really care how I have to get them (so long as it is less painful than setting up the quickbook toolchain on windows) but in the past I've had use for a local copy of the docs. For example if the network goes down or I'm working on a flight. - Michael Marcin
John Maddock wrote:
Folks I think we need to get organised with PDF's now that we have many more libraries with quickbook/boostbook docs.
I don't particularly want these in SVN trunk: apart from anything else it needlessly bloats the download size if folks are happy with HTML versions. Previously I've placed these in the vault, but there's a file size limit there and the new Boost.Math PDF's are too large :-(
Another alternative would be the sourceforge file release system, but I don't believe all developers have access to that?
So.... how about we either have a directory in the "website" area of SVN for these, or else in the sandbox maybe?
I don't think there's a need to version control docs. What we need is: 1. Docs for SVN state of Boost, in HTML and PDF, placed in some area of the web site (and preferrably, not placed in SVN). 2. Docs for the last release -- which clearly should not versioned either. - Volodya
on Thu Nov 01 2007, Vladimir Prus <ghost-AT-cs.msu.su> wrote:
John Maddock wrote:
Folks I think we need to get organised with PDF's now that we have many more libraries with quickbook/boostbook docs.
I don't particularly want these in SVN trunk: apart from anything else it needlessly bloats the download size if folks are happy with HTML versions. Previously I've placed these in the vault, but there's a file size limit there and the new Boost.Math PDF's are too large :-(
Another alternative would be the sourceforge file release system, but I don't believe all developers have access to that?
So.... how about we either have a directory in the "website" area of SVN for these, or else in the sandbox maybe?
I don't think there's a need to version control docs.
I disagree strongly! However, I would agree that in principle, we don't need to store *generated* documentation in version control. -- Dave Abrahams Boost Consulting http://www.boost-consulting.com
David Abrahams wrote:
on Thu Nov 01 2007, Vladimir Prus <ghost-AT-cs.msu.su> wrote:
John Maddock wrote:
Folks I think we need to get organised with PDF's now that we have many more libraries with quickbook/boostbook docs.
I don't particularly want these in SVN trunk: apart from anything else it needlessly bloats the download size if folks are happy with HTML versions. Previously I've placed these in the vault, but there's a file size limit there and the new Boost.Math PDF's are too large :-(
Another alternative would be the sourceforge file release system, but I don't believe all developers have access to that?
So.... how about we either have a directory in the "website" area of SVN for these, or else in the sandbox maybe?
I don't think there's a need to version control docs.
I disagree strongly! However, I would agree that in principle, we don't need to store *generated* documentation in version control.
Oops. I meant *generated* docs, of course. - Volodya
Vladimir Prus wrote:
John Maddock wrote:
Folks I think we need to get organised with PDF's now that we have many more libraries with quickbook/boostbook docs.
I don't particularly want these in SVN trunk: apart from anything else it needlessly bloats the download size if folks are happy with HTML versions. Previously I've placed these in the vault, but there's a file size limit there and the new Boost.Math PDF's are too large :-(
Another alternative would be the sourceforge file release system, but I don't believe all developers have access to that?
So.... how about we either have a directory in the "website" area of SVN for these, or else in the sandbox maybe?
I don't think there's a need to version control docs. What we need is:
1. Docs for SVN state of Boost, in HTML and PDF, placed in some area of the web site (and preferrably, not placed in SVN).
Currently the only way to have anything show up on the beta web site is to check them into SVN. This is not going to change because of management and security issues. Anything that isn't in SVN and needs to be in the web site needs special, programmatic, handling.
2. Docs for the last release -- which clearly should not versioned either.
I don't see why? Or maybe I just don't understand the statement. -- -- Grafik - Don't Assume Anything -- Redshift Software, Inc. - http://redshift-software.com -- rrivera/acm.org - grafik/redshift-software.com -- 102708583/icq - grafikrobot/aim - grafikrobot/yahoo
Rene Rivera wrote:
Vladimir Prus wrote:
John Maddock wrote:
Folks I think we need to get organised with PDF's now that we have many more libraries with quickbook/boostbook docs.
I don't particularly want these in SVN trunk: apart from anything else it needlessly bloats the download size if folks are happy with HTML versions. Previously I've placed these in the vault, but there's a file size limit there and the new Boost.Math PDF's are too large :-(
Another alternative would be the sourceforge file release system, but I don't believe all developers have access to that?
So.... how about we either have a directory in the "website" area of SVN for these, or else in the sandbox maybe?
I don't think there's a need to version control docs. What we need is:
1. Docs for SVN state of Boost, in HTML and PDF, placed in some area of the web site (and preferrably, not placed in SVN).
Currently the only way to have anything show up on the beta web site is to check them into SVN. This is not going to change because of management and security issues. Anything that isn't in SVN and needs to be in the web site needs special, programmatic, handling.
Well, then docs needs special, programmatic, handling.
2. Docs for the last release -- which clearly should not versioned either.
I don't see why? Or maybe I just don't understand the statement.
I would expect that a given release of Boost has docs for that release, not revision 1 of docs, followed by revision 2, and so on. So there seems to be little reason to put docs in SVN. - Volodya
participants (10)
-
David Abrahams -
Eric Niebler -
Jeff Garland -
Joel de Guzman -
John Maddock -
Michael Marcin -
Paul A Bristow -
Rene Rivera -
Stefan Seefeld -
Vladimir Prus