On 10/31/2016 07:33 PM, Lutz Birkhahn wrote: > Hi, > > I have already manually created PDF versions of about 8 of the OpenStack > Manuals (within about 4-6 hours including setting up the tool chain and > locally fixing some bugs), and working on getting the rest done (at least > those that are in the openstack-manuals.git repository) within the next few > weeks, and make them available to the public. I’m currently working on an at > least 3-phase approach:
Lutz, see http://specs.openstack.org/openstack/docs-specs/specs/ocata/build-pdf-from-rst-guides.html Our goal is to publish these PDFs whenever we publish the HTML - so have always current version. > phase 1) get as many of the docs in git (openstack-manuals.git ) as possible > (mostly manually) converted to PDF and publish an URL where you can download > them. > > phase 2) set up a local build pipeline in our own OpenStack cloud to > regularly convert the latest git versions to PDF e.g. every night, and > publish them to the same location, possibly also providing docs for different > versions (e.g. mitaka, neutron, ocata) > > phase 3) work with the docs PTL (Lana) or whoever can help with it to set up > the build process on the regular OpenStack / Ubuntu or whatever build > environments so that the build process possibly could run on the standard > build servers, and no longer on our own machines. Maybe the PDF version will > not yet be a gate in the build process, but it should at least be flagged as > a warning when there are errors, so the right people can look into it and try > to fix it soon, without holding up the rest of the build and release process. See the referenced specs - and help Ian and others please. > I was about to contact Lana in Barcelona, and we did meet 2 times, but we > were both too busy with other meetings so didn’t get to talk about this in > Barcelona, but I should be able to track her down on IRC or email or some > other way soon (hopefully, if schedule permits it ;-) ) > > I absolutely see a case for PDF files, maybe some time also epub or mobi, and > the tool chain already includes Sphinx as far as I know, which already > provides the ability to create (La)TeX files which then can easily be typeset > into PDF format, probably a few others as well (unfortunately I also didn’t > have time to track down the Sphinx author, but at least got a lead on that). > > HTML is fine for online viewing, but any time you sit in an airplane (e.g. > from or to the Summit) or in a train with bad Internet connectivity, you’d > need to download the whole HTML source tree, which is much more of a hassle > than if you could just download a PDF or e-book file. > > Also even in todays time there are still people who prefer a printed copy > rather than some online doc, e.g. for sitting at the couch and have the > feeling of real paper in your hand, or for taking it to the beach. I’m > thinking about setting up a link somewhere on the docs site where you can > order a printed copy (e.g. some books-on-demand provider) where you can at > any time order a printed version of the latest doc version. I’ve even ran > into to a “collector” type of person in Barcelona who likes to have all the > books, but usually doesn’t even have time to read them, just the good feeling > of having a lot of beautiful or interesting books… Sure, this is not > everybody’s opinion about book formats, and many just like the HTML version > (which will of course stay nevertheless), but if there are only 2 to 5 > percent of all OpenStack users who’d like a PDF or printed version, this will > still be in the hundreds I’d guess, maybe thousands > > I also urgently request that the existing .Epub and .Mobi versions are kept > at least in some “archives” location, since those are so far the only > examples (that I know of) of carefully edited versions of the book, even > though they are a bit outdated. Not sure if O’Reilly has some sort of > copyright on the looks of the Ops book (we certainly cannot copy the front > page with the "crested agouti” animal), but in my opinion it can at least be > used as an example to how the future PDF and printed versions of the Ops book > might look like, also including Table of Contents, an Index, and a Colophon. Why would a 2 years old epub or mobi be beneficial for you - even in an archives location? Andreas > I will certainly keep a copy of these 2 files around, and I strongly suggest > to keep a copy on some publicly available location (if need be, I will > provide that copy on our servers and make it available to anyone interested > in them). > > Just my 2 cents, and no, I’m not yet committing to all of this, just my > current thoughts (Steve Martinelli, I heard you in the panel… "Do not over > commit!”) > > Cheers, > > /lutz > > > >> On 31 Oct 2016, at 18:10, Jonathan D. Proulx <j...@csail.mit.edu> wrote: >> >> >> I always use the HTML versions and can't think of a case where I'd >> want the epub or mobi. >> >> If they are also out dated I definitly think they should be removed >> just to prevent confusion. >> >> If there's a wider desire for these formats (which I doubt) then >> they'd need to be published much more frequently. I would be >> surprised if there were a need for this and just dropping them is >> likely the best option. >> >> -Jon >> >> On Mon, Oct 31, 2016 at 05:51:44PM +0100, Andreas Jaeger wrote: >> :Operators, a quick question from the docs team: >> : >> :We currently publish a frozen epub and mobi version of the O'Reilly >> :Operations Guide - in the version from 20th May 2014. This is now quite >> :different from the HTML version. >> : >> :The same for the Architecture Design Guide. Our epub is frozen and from >> :from 30th October 2014. >> : >> :We plan to add current PDFs for these documents in the Ocata cycle. >> : >> :Is there any reason these ancient epub/mobi versions should still get >> :published? >> : >> :Andreas >> :-- >> : Andreas Jaeger aj@{suse.com,opensuse.org} Twitter: jaegerandi >> : SUSE LINUX GmbH, Maxfeldstr. 5, 90409 Nürnberg, Germany >> : GF: Felix Imendörffer, Jane Smithard, Graham Norton, >> : HRB 21284 (AG Nürnberg) >> : GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126 >> : >> : >> :_______________________________________________ >> :OpenStack-operators mailing list >> :OpenStack-operators@lists.openstack.org >> :http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-operators >> >> -- >> >> _______________________________________________ >> OpenStack-operators mailing list >> OpenStack-operators@lists.openstack.org >> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-operators > -- Andreas Jaeger aj@{suse.com,opensuse.org} Twitter: jaegerandi SUSE LINUX GmbH, Maxfeldstr. 5, 90409 Nürnberg, Germany GF: Felix Imendörffer, Jane Smithard, Graham Norton, HRB 21284 (AG Nürnberg) GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126 _______________________________________________ OpenStack-operators mailing list OpenStack-operators@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-operators
