Thread: Documentation epub format

Documentation epub format

From
Fabien COELHO
Date:
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.



Re: Documentation epub format

From
"Joshua D. Drake"
Date:
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



Re: Documentation epub format

From
Tom Lane
Date:
"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



Re: Documentation epub format

From
Andrew Satori
Date:
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





Re: Documentation epub format

From
"ktm@rice.edu"
Date:
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



Re: Documentation epub format

From
"Joshua D. Drake"
Date:
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



Re: Documentation epub format

From
"Joshua D. Drake"
Date:
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



Re: Documentation epub format

From
"Erik Rijkers"
Date:
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)






Re: Documentation epub format

From
Andrew Satori
Date:
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







Re: Documentation epub format

From
Ross Reedstrom
Date:
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





Re: Documentation epub format

From
Josh Berkus
Date:
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



Re: Documentation epub format

From
Josh Berkus
Date:
> 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


Re: Documentation epub format

From
Greg Stark
Date:
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



Re: Documentation epub format

From
Peter Eisentraut
Date:
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.





Re: Documentation epub format

From
Gavin Flower
Date:
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



Re: Documentation epub format

From
Andrew Dunstan
Date:
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



Re: Documentation epub format

From
Peter Eisentraut
Date:
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.





Re: Documentation epub format

From
Gavin Flower
Date:
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




Re: Documentation epub format

From
David Fetter
Date:
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



Re: Documentation epub format

From
Fabien COELHO
Date:
>> 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.



Re: Documentation epub format

From
Fabien COELHO
Date:
>> 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.



Re: Documentation epub format

From
Bruce Momjian
Date:
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. +



Re: Documentation epub format

From
Peter Eisentraut
Date:
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.




Re: Documentation epub format

From
Andrew Dunstan
Date:
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




Re: Documentation epub format

From
Bruce Momjian
Date:
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. +



Re: Documentation epub format

From
Alvaro Herrera
Date:
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



Re: Documentation epub format

From
Fabien COELHO
Date:
> 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.



Re: Documentation epub format

From
Gavin Flower
Date:
<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 />