Thread: Documentation epub format
Hello devs, I've given a try to the PostgreSQL documentation in epub format. I must admit that there is a bit of a disappointement as far as the user experience is concerned: the generated file is barely usable on an iPad2 with the default iBooks reader, which was clearly not designed for handling a "4592" pages book (from its point of view). The table of contents too much detailed, so it is long and slow to scan, and there is no clear shortcut. Flipping pages in the documentation takes ages (well, close to one second or more if I flip a few pages). Do not try "search". This seems to suggest that instead of generating one large ebook, the build should generate a set of ebooks, say one for each part. At the minimum, a less detailed toc could be more usable and help navigate the huge contents. -- Fabien.
On 05/01/2013 09:27 AM, Fabien COELHO wrote: > > > Hello devs, > > I've given a try to the PostgreSQL documentation in epub format. > > I must admit that there is a bit of a disappointement as far as the user > experience is concerned: the generated file is barely usable on an iPad2 > with the default iBooks reader, which was clearly not designed for > handling a "4592" pages book (from its point of view). > > The table of contents too much detailed, so it is long and slow to scan, > and there is no clear shortcut. Flipping pages in the documentation > takes ages (well, close to one second or more if I flip a few pages). Do > not try "search". > > This seems to suggest that instead of generating one large ebook, the > build should generate a set of ebooks, say one for each part. At the > minimum, a less detailed toc could be more usable and help navigate the > huge contents. Once upon a time we had multiple books as documentation, then at some point we merged them. It was quite a few years ago. I would agree at this point that we need to consider breaking them up again. The documentation is unwieldy. JD -- Command Prompt, Inc. - http://www.commandprompt.com/ PostgreSQL Support, Training, Professional Services and Development High Availability, Oracle Conversion, Postgres-XC @cmdpromptinc - 509-416-6579
"Joshua D. Drake" <jd@commandprompt.com> writes:
> Once upon a time we had multiple books as documentation, then at some
> point we merged them. It was quite a few years ago.
> I would agree at this point that we need to consider breaking them up
> again. The documentation is unwieldy.
The reason we merged them was to allow hyperlink cross-references between
different parts of the docs. I would be sad to lose that.
regards, tom lane
I would second Tom on this, and if ePub is really a longer term goal of the documentation, the various eBook formats havediffering levels of support for hyperlinking that would merit retaining everything in a single book that can be linkedfrom direct references. Dru On May 1, 2013, at 1:52 PM, Tom Lane <tgl@sss.pgh.pa.us> wrote: > "Joshua D. Drake" <jd@commandprompt.com> writes: >> Once upon a time we had multiple books as documentation, then at some >> point we merged them. It was quite a few years ago. >> I would agree at this point that we need to consider breaking them up >> again. The documentation is unwieldy. > > The reason we merged them was to allow hyperlink cross-references between > different parts of the docs. I would be sad to lose that. > > regards, tom lane > > > -- > Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org) > To make changes to your subscription: > http://www.postgresql.org/mailpref/pgsql-hackers
On Wed, May 01, 2013 at 01:52:43PM -0400, Tom Lane wrote: > "Joshua D. Drake" <jd@commandprompt.com> writes: > > Once upon a time we had multiple books as documentation, then at some > > point we merged them. It was quite a few years ago. > > I would agree at this point that we need to consider breaking them up > > again. The documentation is unwieldy. > > The reason we merged them was to allow hyperlink cross-references between > different parts of the docs. I would be sad to lose that. > > regards, tom lane > Yes, please keep that feature! Regards, Ken
On 05/01/2013 10:52 AM, Tom Lane wrote: > "Joshua D. Drake" <jd@commandprompt.com> writes: >> Once upon a time we had multiple books as documentation, then at some >> point we merged them. It was quite a few years ago. >> I would agree at this point that we need to consider breaking them up >> again. The documentation is unwieldy. > > The reason we merged them was to allow hyperlink cross-references between > different parts of the docs. I would be sad to lose that.\ Defintely. Is there no way to cross reference multiple documents? Peter? JD > > regards, tom lane > > -- Command Prompt, Inc. - http://www.commandprompt.com/ PostgreSQL Support, Training, Professional Services and Development High Availability, Oracle Conversion, Postgres-XC @cmdpromptinc - 509-416-6579
On 05/01/2013 10:56 AM, Andrew Satori wrote: > > I would second Tom on this, and if ePub is really a longer term goal of the documentation, the various eBook formats havediffering levels of support for hyperlinking that would merit retaining everything in a single book that can be linkedfrom direct references. I don't think ePub is a problem here, we will have the same problem with PDF. The issue is the sheer size of the manual. If we can solve the cross referencing issue, breaking them up makes sense I would think. JD -- Command Prompt, Inc. - http://www.commandprompt.com/ PostgreSQL Support, Training, Professional Services and Development High Availability, Oracle Conversion, Postgres-XC @cmdpromptinc - 509-416-6579
On Wed, May 1, 2013 20:13, Joshua D. Drake wrote: > I don't think ePub is a problem here, we will have the same problem with > PDF. The issue is the sheer size of the manual. If we can solve the > cross referencing issue, breaking them up makes sense I would think. I like the one-huge-chunk pdf: you can always find all occurrences of a word because they are in single search-space. (as opposed to searching the many .html pages)
On May 1, 2013, at 2:11 PM, "Joshua D. Drake" <jd@commandprompt.com> wrote: > > On 05/01/2013 10:52 AM, Tom Lane wrote: >> "Joshua D. Drake" <jd@commandprompt.com> writes: >>> Once upon a time we had multiple books as documentation, then at some >>> point we merged them. It was quite a few years ago. >>> I would agree at this point that we need to consider breaking them up >>> again. The documentation is unwieldy. >> >> The reason we merged them was to allow hyperlink cross-references between >> different parts of the docs. I would be sad to lose that.\ > > Defintely. Is there no way to cross reference multiple documents? > > Peter? > The weakness (IMO) is that you are trading off one large file for several smaller ones. The documentation is unwieldilybecause of the depth and breadth, not the size of the file. Thinking in terms of common use cases, you would havethe the published document on an offline device. For external linking you would have to assume a directory structure,or multiple files all local in the same directory, and that's assuming the various formats for doing the linking. While there is fairly broad support for link points within a document, or to an http(s) url in formats like epuband pdf. file:// uri's are far less robust in support, and it is quite hit or miss in the various readers. Other thanlocal HTML, I cannot think of a format that has good local file/relative path support for linking multiple documents,and broad device/platform support. Dru
On Wed, May 01, 2013 at 09:33:23AM -0700, Joshua D. Drake wrote: > > On 05/01/2013 09:27 AM, Fabien COELHO wrote: > > > > > >Hello devs, > > > >I've given a try to the PostgreSQL documentation in epub format. > > > >I must admit that there is a bit of a disappointement as far as the user > >experience is concerned: the generated file is barely usable on an iPad2 > >with the default iBooks reader, which was clearly not designed for > >handling a "4592" pages book (from its point of view). > > > >The table of contents too much detailed, so it is long and slow to scan, > >and there is no clear shortcut. Flipping pages in the documentation > >takes ages (well, close to one second or more if I flip a few pages). Do > >not try "search". > > > >This seems to suggest that instead of generating one large ebook, the > >build should generate a set of ebooks, say one for each part. At the > >minimum, a less detailed toc could be more usable and help navigate the > >huge contents. > > Once upon a time we had multiple books as documentation, then at > some point we merged them. It was quite a few years ago. > > I would agree at this point that we need to consider breaking them > up again. The documentation is unwieldy. In my day job, we're building epubs that encompass entire college textbooks (Physics, Algebra, etc.) There is in fact an issue w/ attempting to use existing readers with such large files. There is a bit of a trap you can fall into, though, limiting yourself to what the current generation of reading tools (both software and dedicated devices) can do: newer devices will have greater capabilities, and can make use of features of the content that only work well in the context of the whole work. This happens right now when using the large work on a less-mobile platform (though my new laptop is both mobile and more capable than many db servers I've adminned in the past ...) There are significant costs to splitting the docs up: both the author and the reader have to agree on where a piece of information should live, and for the (potentially naive) reader, this can be a problem. Structurally, I think since the "one book to bind them" work has been done, there's much better cross-referencing going on. In fact, that seems to be the reason for doing it. If those xrefs can survive splitting into multiple docs, that can help relieve the newbie-finding problem, though current reading tools may not support linking across books, putting the burden of finding things back on the reader. That said, creating a different format of the docs -- multiple epubs that are more easily moved around and read on current devices -- has merit, if it doesn't break the existing all-one-document presentation on the web. In that sort of case, the multiple parts are a convenience, and have less burden to carry for searchability and findability than if they are presented as the primary format for using the material. If the split version is not primary, automated, less-than-perfect means of splitting (page count?) can be considered. Ross -- Ross Reedstrom, Ph.D. reedstrm@rice.edu Systems Engineer & Admin, Research Scientist phone: 713-348-6166 Connexions http://cnx.org fax: 713-348-3665 Rice University MS-375, Houston, TX 77005 GPG Key fingerprint = F023 82C8 9B0E 2CC6 0D8E F888 D3AE 810E 88F0 BEDE
On 05/01/2013 10:52 AM, Tom Lane wrote: > "Joshua D. Drake" <jd@commandprompt.com> writes: >> Once upon a time we had multiple books as documentation, then at some >> point we merged them. It was quite a few years ago. >> I would agree at this point that we need to consider breaking them up >> again. The documentation is unwieldy. > > The reason we merged them was to allow hyperlink cross-references between > different parts of the docs. I would be sad to lose that. Also the divisions between sections were totally arbitrary and unintuitive. I think it would make a lot more sense to modify the SGML export to create a book per chapter. -- Josh Berkus PostgreSQL Experts Inc. http://pgexperts.com
> Also the divisions between sections were totally arbitrary and unintuitive. > > I think it would make a lot more sense to modify the SGML export to > create a book per chapter. Also ... why is this discussion not on pgsql-docs, where it belongs? Crossing it over. -- Josh Berkus PostgreSQL Experts Inc. http://pgexperts.com
On Wed, May 1, 2013 at 5:27 PM, Fabien COELHO <coelho@cri.ensmp.fr> wrote: > I must admit that there is a bit of a disappointement as far as the user > experience is concerned: the generated file is barely usable on an iPad2 > with the default iBooks reader, which was clearly not designed for handling > a "4592" pages book (from its point of view). Surely that just means you need a better reader? Fwiw I routinely use PDFs of Oracle docs that are about that size. They're *way* more useful than the html docs that are broken up into a lot of smaller files. Being able to search and jump around in them is extremely handy. This would have been unwieldy in older generations of PDF readers but newer ones don't actually load the whole file into memory and can read and uncompress just the sections they need. Sometimes (though I can never predict when) even over the web. I also find it hard to believe the Postgres docs are really that big. Surely a big chunk of it is just some reference material like tables of data or something? The other section of the docs that can reasonably be broken out imho is the man pages. But the rest really belong in a single document. -- greg
On Wed, 2013-05-01 at 18:27 +0200, Fabien COELHO wrote: > I must admit that there is a bit of a disappointement as far as the > user experience is concerned: the generated file is barely usable on > an iPad2 with the default iBooks reader, which was clearly not > designed for handling a "4592" pages book (from its point of view). Well, clearly there are mainstream books that have 1000 pages, so it ought to be designed for that. It's not clear to me then why it necessarily must fail at 4000 pages. I think you might want to run some experiments to see what the reader can handle before we start doing anything.
On 02/05/13 15:23, Peter Eisentraut wrote: > On Wed, 2013-05-01 at 18:27 +0200, Fabien COELHO wrote: >> I must admit that there is a bit of a disappointement as far as the >> user experience is concerned: the generated file is barely usable on >> an iPad2 with the default iBooks reader, which was clearly not >> designed for handling a "4592" pages book (from its point of view). > Well, clearly there are mainstream books that have 1000 pages, so it > ought to be designed for that. It's not clear to me then why it > necessarily must fail at 4000 pages. I think you might want to run some > experiments to see what the reader can handle before we start doing > anything. > > There might be something silly in some eReaders, like reserving 12 bits for page numbers internally - as 'no one will ever want a book with more than 4095 pages!'? Cheers, Gavin
On 05/01/2013 11:36 PM, Gavin Flower wrote: > On 02/05/13 15:23, Peter Eisentraut wrote: >> On Wed, 2013-05-01 at 18:27 +0200, Fabien COELHO wrote: >>> I must admit that there is a bit of a disappointement as far as the >>> user experience is concerned: the generated file is barely usable on >>> an iPad2 with the default iBooks reader, which was clearly not >>> designed for handling a "4592" pages book (from its point of view). >> Well, clearly there are mainstream books that have 1000 pages, so it >> ought to be designed for that. It's not clear to me then why it >> necessarily must fail at 4000 pages. I think you might want to run some >> experiments to see what the reader can handle before we start doing >> anything. >> >> > There might be something silly in some eReaders, like reserving 12 > bits for page numbers internally - as 'no one will ever want a book > with more than 4095 pages!'? > > > My ancient Sony PRS-505 e-reader has the epub paginated at 5200 pages, and it seems to work just fine, if a bit slowly. It's possibly worth noting that the epub is about 1.5 times the size of that for War and Peace. cheers andrew
On Wed, 2013-05-01 at 18:27 +0200, Fabien COELHO wrote: > The table of contents too much detailed, so it is long and slow to > scan, and there is no clear shortcut. Flipping pages in the > documentation takes ages (well, close to one second or more if I flip > a few pages). Do not try "search". EPUB is essentially a zip file with per-section simplified HTML files. So any device that can render simple web pages should be able to handle that with ease. What I think iBooks is doing is it internally pre-renders all the pages in order to be able to attach page numbers to all the table of contents entries. I suspect other readers that don't do that will be able to handle this better. That said, I think trimming down the table of contents nesting depth might be worth checking into for this output format.
On 03/05/13 15:16, Peter Eisentraut wrote: > On Wed, 2013-05-01 at 18:27 +0200, Fabien COELHO wrote: >> The table of contents too much detailed, so it is long and slow to >> scan, and there is no clear shortcut. Flipping pages in the >> documentation takes ages (well, close to one second or more if I flip >> a few pages). Do not try "search". > EPUB is essentially a zip file with per-section simplified HTML files. > So any device that can render simple web pages should be able to handle > that with ease. What I think iBooks is doing is it internally > pre-renders all the pages in order to be able to attach page numbers to > all the table of contents entries. I suspect other readers that don't > do that will be able to handle this better. > > That said, I think trimming down the table of contents nesting depth > might be worth checking into for this output format. > I don't think that you don't need to trim down the nesting depth in pdf, as the table of contents can be displayed in a tree structure, and you only need to expand branches as far you need. I would have assumed ePub would have the same facility, or am I mistaken? Cheers, Gavin
On Thu, May 02, 2013 at 03:42:33AM -0400, Andrew Dunstan wrote: > > On 05/01/2013 11:36 PM, Gavin Flower wrote: > >On 02/05/13 15:23, Peter Eisentraut wrote: > >>On Wed, 2013-05-01 at 18:27 +0200, Fabien COELHO wrote: > >>>I must admit that there is a bit of a disappointement as far as the > >>>user experience is concerned: the generated file is barely usable on > >>>an iPad2 with the default iBooks reader, which was clearly not > >>>designed for handling a "4592" pages book (from its point of view). > >>Well, clearly there are mainstream books that have 1000 pages, so it > >>ought to be designed for that. It's not clear to me then why it > >>necessarily must fail at 4000 pages. I think you might want to run some > >>experiments to see what the reader can handle before we start doing > >>anything. > >> > >> > >There might be something silly in some eReaders, like reserving 12 > >bits for page numbers internally - as 'no one will ever want a > >book with more than 4095 pages!'? > > My ancient Sony PRS-505 e-reader has the epub paginated at 5200 > pages, and it seems to work just fine, if a bit slowly. > > It's possibly worth noting that the epub is about 1.5 times the size > of that for War and Peace. At least ours doesn't start out like this: Eh bien, mon prince. Gênes et Lueques ne sont plus que des apanages, des поместья, de la famille Buonaparte. Non, jevous préviens que si vous ne me dites pas que nous avons la guerre, si vous vous permettez encore de pallier toutesles infamies, toutes les atrocités de cet Antichrist (ma parole, j’y crois) — je ne vous connais plus, vous n’êtesplus mon ami, vous n’êtes plus мой верный раб, comme vous dites. Ну, здравствуйте, здравствуйте. Je vois que jevous fais peur, садитесь и рассказывайте. Cheers, David. -- David Fetter <david@fetter.org> http://fetter.org/ Phone: +1 415 235 3778 AIM: dfetter666 Yahoo!: dfetter Skype: davidfetter XMPP: david.fetter@gmail.com iCal: webcal://www.tripit.com/feed/ical/people/david74/tripit.ics Remember to vote! Consider donating to Postgres: http://www.postgresql.org/about/donate
>> This seems to suggest that instead of generating one large ebook, the >> build should generate a set of ebooks, say one for each part. At the >> minimum, a less detailed toc could be more usable and help navigate the >> huge contents. > > Once upon a time we had multiple books as documentation, then at some point > we merged them. It was quite a few years ago. > > I would agree at this point that we need to consider breaking them up again. > The documentation is unwieldy. PostgreSQL documentation in PDF seemed quite usable on the same ipad, so maybe there is no unique answer. I like the principle and simplicity of "one" document to move around, so sticking to that if possible seems better. -- Fabien.
>> The table of contents too much detailed, so it is long and slow to >> scan, and there is no clear shortcut. Flipping pages in the >> documentation takes ages (well, close to one second or more if I flip >> a few pages). Do not try "search". > > EPUB is essentially a zip file with per-section simplified HTML files. > So any device that can render simple web pages should be able to handle > that with ease. What I think iBooks is doing is it internally > pre-renders all the pages in order to be able to attach page numbers to > all the table of contents entries. I suspect other readers that don't > do that will be able to handle this better. Indeed, iBooks computes page numbers, which mean processing the whole contents. > That said, I think trimming down the table of contents nesting depth > might be worth checking into for this output format. That at least would be a relief. The TOC on iBooks is shown as a very long scrolling window, without collapsable parts. -- Fabien.
On Fri, May 3, 2013 at 07:57:07AM +0200, Fabien COELHO wrote: > > >>This seems to suggest that instead of generating one large ebook, the > >>build should generate a set of ebooks, say one for each part. At the > >>minimum, a less detailed toc could be more usable and help navigate the > >>huge contents. > > > >Once upon a time we had multiple books as documentation, then at > >some point we merged them. It was quite a few years ago. > > > >I would agree at this point that we need to consider breaking them > >up again. The documentation is unwieldy. > > PostgreSQL documentation in PDF seemed quite usable on the same > ipad, so maybe there is no unique answer. I like the principle and > simplicity of "one" document to move around, so sticking to that if > possible seems better. No question that PDF readers with collapsable index sections is a huge win for our documentation. It isn't really the docs itself that control that. -- Bruce Momjian <bruce@momjian.us> http://momjian.us EnterpriseDB http://enterprisedb.com + It's impossible for everything to be true. +
On 5/3/13 2:05 AM, Fabien COELHO wrote: >> EPUB is essentially a zip file with per-section simplified HTML files. >> So any device that can render simple web pages should be able to handle >> that with ease. What I think iBooks is doing is it internally >> pre-renders all the pages in order to be able to attach page numbers to >> all the table of contents entries. I suspect other readers that don't >> do that will be able to handle this better. > > Indeed, iBooks computes page numbers, which mean processing the whole > contents. After trying out a few different EPUB readers on iOS (iPhone), I think this is simply a quality-of-implementation issue with iBooks. For example, NeoSoar's reader is much more responsive with the same file on the same hardware. Its page counting is much more nonsensical, but that just seems to support my earlier theory.
On 05/02/2013 11:16 PM, Peter Eisentraut wrote: > On Wed, 2013-05-01 at 18:27 +0200, Fabien COELHO wrote: >> The table of contents too much detailed, so it is long and slow to >> scan, and there is no clear shortcut. Flipping pages in the >> documentation takes ages (well, close to one second or more if I flip >> a few pages). Do not try "search". > EPUB is essentially a zip file with per-section simplified HTML files. > So any device that can render simple web pages should be able to handle > that with ease. What I think iBooks is doing is it internally > pre-renders all the pages in order to be able to attach page numbers to > all the table of contents entries. I suspect other readers that don't > do that will be able to handle this better. > > That said, I think trimming down the table of contents nesting depth > might be worth checking into for this output format. > > I don't think we should be governed by the silly behaviour of one epub reader. My ereader doesn't collapse the contents into one giant list. If ibooks is doing stuff badly, complain to Apple. cheers andrew
On Fri, May 3, 2013 at 12:05:45PM -0400, Andrew Dunstan wrote: > > On 05/02/2013 11:16 PM, Peter Eisentraut wrote: > >On Wed, 2013-05-01 at 18:27 +0200, Fabien COELHO wrote: > >>The table of contents too much detailed, so it is long and slow to > >>scan, and there is no clear shortcut. Flipping pages in the > >>documentation takes ages (well, close to one second or more if I flip > >>a few pages). Do not try "search". > >EPUB is essentially a zip file with per-section simplified HTML files. > >So any device that can render simple web pages should be able to handle > >that with ease. What I think iBooks is doing is it internally > >pre-renders all the pages in order to be able to attach page numbers to > >all the table of contents entries. I suspect other readers that don't > >do that will be able to handle this better. > > > >That said, I think trimming down the table of contents nesting depth > >might be worth checking into for this output format. > > > > > > I don't think we should be governed by the silly behaviour of one > epub reader. My ereader doesn't collapse the contents into one giant > list. If ibooks is doing stuff badly, complain to Apple. I tend to agree. Losing the ability to link across books is a big loss, and I am unclear how we would allow that for books split into files. -- Bruce Momjian <bruce@momjian.us> http://momjian.us EnterpriseDB http://enterprisedb.com + It's impossible for everything to be true. +
Bruce Momjian wrote: > On Fri, May 3, 2013 at 12:05:45PM -0400, Andrew Dunstan wrote: > > I don't think we should be governed by the silly behaviour of one > > epub reader. My ereader doesn't collapse the contents into one giant > > list. If ibooks is doing stuff badly, complain to Apple. > > I tend to agree. Losing the ability to link across books is a big loss, > and I am unclear how we would allow that for books split into files. This article (written in 2008!) seems to say that there's enough infrastructure in the epub format to support the linking we need: http://frontmatters.com/2008/03/29/links-pointers-bookmarks-highlights-how-should-epub-do-it/ It refers to RFC 3987, though I'm not clear exactly how that is to be used. That said, I haven't tested the current epub in my reader. -- Álvaro Herrera http://www.2ndQuadrant.com/ PostgreSQL Development, 24x7 Support, Training & Services
> I don't think we should be governed by the silly behaviour of one epub > reader. My ereader doesn't collapse the contents into one giant list. If > ibooks is doing stuff badly, complain to Apple. Indeed that makes sense as the issue is specific to this reader. I was afraid that the problem was more wide spread... I've filled a feedback to Apple. Wait and see... or not:-) -- Fabien.
<div class="moz-cite-prefix">On 04/05/13 18:11, Fabien COELHO wrote:<br /></div><blockquote cite="mid:alpine.DEB.2.02.1305040753570.9292@localhost6.localdomain6"type="cite"><br /><blockquote type="cite">I don't thinkwe should be governed by the silly behaviour of one epub reader. My ereader doesn't collapse the contents into one giantlist. If ibooks is doing stuff badly, complain to Apple. <br /></blockquote><br /> Indeed that makes sense as the issueis specific to this reader. I was afraid that the problem was more wide spread... <br /><br /> I've filled a feedbackto Apple. Wait and see... or not:-) <br /><br /></blockquote><font size="-1">Well you can at least <font size="-1">waitpatientl<font size="-1">y!</font></font></font> :-)<br /><br /><br />