Documentation epub format

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

--
Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-hackers

"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

I would second Tom on this, and if ePub is really a longer term goal of the documentation, the various eBook formats have differing levels of support for hyperlinking that would merit retaining everything in a single book that can be linked from 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

--
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

--
Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-hackers

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

--
Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-hackers

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 have differing levels of support for hyperlinking that would merit retaining everything in a single book that can be linked from 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

--
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 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)

--
Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-hackers

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 unwieldily because of the depth and breadth, not the size of the file. Thinking in terms of common use cases, you would have the 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 epub and pdf. file:// uri's are far less robust in support, and it is quite hit or miss in the various readers. Other than local 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

--
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 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

--
Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-hackers

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

--
Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-hackers

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

--
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 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

--
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, 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.

--
Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-hackers

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

--
Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-hackers

On 05/02/2013 01: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 have differing levels of support for hyperlinking that would merit retaining everything in a single book that can be linked from direct references.

I also think we'd be trying to solve an issue that'll solve it self as
ereaders get smarter and faster anyway. eReader performance is growing
much, much faster than the Pg docs. A split of the existing docs along
chapter lines might be worth it for such devices if it's quick and easy,
but otherwise I don't really see the appeal.

I'm a fan of a single big file as well. It improves discoverability of
information because you don't have to find the *correct* manual to read
first, searching is more effective, etc.

As for search: the main thing that needs is a better ebook standard with
pre-built machine-readable keyword indexes, IMO.

--
Craig Ringer http://www.2ndQuadrant.com/
PostgreSQL Development, 24x7 Support, Training & Services

--
Sent via pgsql-docs mailing list (pgsql-docs@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-docs

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

--
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, 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.

--
Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-hackers

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

--
Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-hackers

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, je vous
préviens que si vous ne me dites pas que nous avons la guerre, si
vous vous permettez encore de pallier toutes les infamies, toutes
les atrocités de cet Antichrist (ma parole, j’y crois) — je ne
vous connais plus, vous n’êtes plus mon ami, vous n’êtes plus мой
верный раб, comme vous dites. Ну, здравствуйте, здравствуйте.
Je vois que je vous 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

--
Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-hackers

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.

--
Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-hackers

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.

--
Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-hackers

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. +

--
Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-hackers

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.

--
Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-hackers

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

--
Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-hackers

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. +

--
Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-hackers

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

--
Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-hackers

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.

--
Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-hackers

On 04/05/13 18:11, Fabien COELHO 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.

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:-)

Well you can at least wait patiently! :-)