On Mon, Oct 31, 2016 at 2:44 PM, Andreas Jaeger <[email protected]
<mailto:[email protected]>> wrote:
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
<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 <[email protected]
<mailto:[email protected]>> 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 <http://suse.com>,opensuse.org
<http://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
>> :[email protected]
<mailto:[email protected]>
>>
:http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-operators
<http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-operators>
>>
>> --
>>
>> _______________________________________________
>> OpenStack-operators mailing list
>> [email protected]
<mailto:[email protected]>
>> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-operators
<http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-operators>
>
--
Andreas Jaeger aj@{suse.com <http://suse.com>,opensuse.org
<http://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
[email protected]
<mailto:[email protected]>
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-operators
<http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-operators>
_______________________________________________
OpenStack-operators mailing list
[email protected]
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-operators
