Please review my first ePub ebook

[AlexBell]

I've just uploaded The War Prayer by Mark Twain, which is the first ePub ebook I've been able to make by hand.

It's only a small and simple book, but I really would be grateful if some of the hand made ePub experts would review its format and style, and tell me how it looks on his or her reader. I want to go on to bigger and more complex ebooks, but also want to be sure that I'm starting from a good foundation.

Regards, Alex

[mtravellerh]

I don't find the book. Where have you placed it?

[AlexBell]

Originally Posted by AlexBell

I've just uploaded The War Prayer by Mark Twain, which is the first ePub ebook I've been able to make by hand.

It's only a small and simple book, but I really would be grateful if some of the hand made ePub experts would review its format and style, and tell me how it looks on his or her reader. I want to go on to bigger and more complex ebooks, but also want to be sure that I'm starting from a good foundation.

Regards, Alex

I thought I'd placed it in the ePub uploads forum, but there is no record of my post from a couple of hours ago, and nothing in the index. I'll try again.

PS I got it right this time; it's there now.

Regards, Alex

[charleski]

It generally looks great, and the css is much better than many commercial books I've seen. But here are a few observations if you want to tweak it.

1) Using absolute values for the cover image width and height causes its aspect ratio to change if the viewing window is smaller than the supplied values. Since the bulk of devices have a 4:3 aspect ratio and your picture is the same proportions it's often safe to leave out the width attribute and simply use height: 100%. But the best method is to wrap the image in some svg to ensure that any scaling is done proportionally.

<svg version="1.1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" width="100%" height="100%" viewBox="0 0 600 800" preserveAspectRatio="xMidYMid meet">
 <image width="600" height="800" xlink:href="images/TWPCover.jpg" />
 </svg>

2) Your idea of wrapping each element (toc, preface, body and colophon) in its own div is a good one. Unfortunately, you've run into a bug in ADE in which margin-top values are disregarded after a css pagebreak. To get your top margin to appear you should use the padding value instead:

div.section {
    margin: 0;
    padding: 1em 0 0 0;
    page-break-after: always;
    }  /* Sets top margin and page break for preface and chapters */

Personally, I'd set more space above and below the headings, but that's a matter of style.

3) You set the body margin to 2%. This will scale as the text is zoomed up viewport width changes [edit], potentially leading to margins that are too large. The page margins are the one portion that are better done using fixed lengths. I find that margin-left/right values of 12pt are enough the give the text some breathing room on my 505, and they're also enough so that the ADE page number on the right doesn't encroach on the text. To set the margins for the page top and bottom you can use the @page directive instead (the body top and bottom margins will apply to the entire text).

4) I see you defined a class for a flush paragraph but didn't use it. Personally I really think that setting the first paragraph of a section flush looks a lot better.

5) Although most well-behaved readers will respect the css pagebreaks you insert, some don't (they don't show up in the calibre reader for example). The only sure-fire way to make sure the reader puts in a pagebreak is to break the text into separate flows (separate xhtml files).

[mtravellerh]

While I appreciate your input, charleski, I have to disagree on some finer points. I am speaking from a practical standpoint here:

@1:Using the heigth: 100% for the cover is definitely a good idea, wrapping an image in svg is not always a really good idea as some readers misinterpret those covers or just don't show them at all (FBReader)

@3: I think defining the margin in percent is the most wise thing to do as the margin/body relation stays the same all through the hardware and adapts to the reflow.

The other points are really valuable.

Originally Posted by charleski

It generally looks great, and the css is much better than many commercial books I've seen. But here are a few observations if you want to tweak it.

1) Using absolute values for the cover image width and height causes its aspect ratio to change if the viewing window is smaller than the supplied values. Since the bulk of devices have a 4:3 aspect ratio and your picture is the same proportions it's often safe to leave out the width attribute and simply use height: 100%. But the best method is to wrap the image in some svg to ensure that any scaling is done proportionally.

<svg version="1.1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" width="100%" height="100%" viewBox="0 0 600 800" preserveAspectRatio="xMidYMid meet">
 <image width="600" height="800" xlink:href="images/TWPCover.jpg" />
 </svg>

2) Your idea of wrapping each element (toc, preface, body and colophon) in its own div is a good one. Unfortunately, you've run into a bug in ADE in which margin-top values are disregarded after a css pagebreak. To get your top margin to appear you should use the padding value instead:

div.section {
    margin: 0;
    padding: 1em 0 0 0;
    page-break-after: always;
    }  /* Sets top margin and page break for preface and chapters */

Personally, I'd set more space above and below the headings, but that's a matter of style.

3) You set the body margin to 2%. This will scale as the text is zoomed up, potentially leading to margins that are too large. The page margins are the one portion that are better done using fixed lengths. I find that margin-left/right values of 12pt are enough the give the text some breathing room on my 505, and they're also enough so that the ADE page number on the right doesn't encroach on the text. To set the margins for the page top and bottom you can use the @page directive instead (the body top and bottom margins will apply to the entire text).

4) I see you defined a class for a flush paragraph but didn't use it. Personally I really think that setting the first paragraph of a section flush looks a lot better.

5) Although most well-behaved readers will respect the css pagebreaks you insert, some don't (they don't show up in the calibre reader for example). The only sure-fire way to make sure the reader puts in a pagebreak is to break the text into separate flows (separate xhtml files).

[charleski]

Originally Posted by mtravellerh

@3: I think defining the margin in percent is the most wise thing to do as the margin/body relation stays the same all through the hardware and adapts to the reflow.

Actually, I was wrong. Setting the margin in % doesn't cause it to scale with text size, it scales with the size of the viewing port. This means that on very narrow devices the margin will almost disappear and on wider ones it will become needlessly large.

At small values like 2% the difference isn't that great, though the text will be on the verge of colliding with the border for those reading on a small phone. A fixed size allows you to avoid wall-to-wall text while preventing the gutter becoming too obvious.

There are ways to incorporate an html fallback for archaic browsers that don't support SVG.

[Jellby]

Originally Posted by charleski

Unfortunately, you've run into a bug in ADE in which margin-top values are disregarded after a css pagebreak.

While I agree it can be annoying, it's not a bug, it's allowed by the CSS spec:

When an unforced page break occurs here, the used values of the relevant 'margin-top' and 'margin-bottom' properties are set to '0'. When a forced page break occurs here, the used value of the relevant 'margin-bottom' property is set to '0'; the relevant 'margin-top' used value may either be set to '0' or retained.

[AlexBell]

Thanks so much to you all; you've given me a lot to think about, as has Paul Durrant in an email.

I'll try to respond to each persons comments in one message with as little quoting as possible.

Charleski
- My ECO Reader uses the FB Reader, and as mtravellerh says does not cope with SVG. So though I'll copy your suggested markup for future reference I'll leave it aside for now.
- Paul Durrant suggests leaving the height undefined and setting width to 100%, so I guess I'll have to try each suggestion out separately.
- I really like your idea of using padding rather than margin, and will certainly try that out.
- 'I see you defined a class for a flush paragraph but didn't use it.' The CSS was designed to a standard to be used in other ePub books. Some of them will need to have flush paragraphs.
- 'Personally I really think that setting the first paragraph of a section flush looks a lot better.' I suggest we agree to disagree here; it's a matter of taste, I think.
- 'Although most well-behaved readers will respect the css pagebreaks you insert, some don't (they don't show up in the calibre reader for example). The only sure-fire way to make sure the reader puts in a pagebreak is to break the text into separate flows (separate xhtml files).' Could I suggest that this is a problem for the Calibre reader? The ebook meets W3C and ePubCheck standards. I don't think, at first glance, that it's any improvement to break a short book into separate pages.
- At small values like 2% the difference isn't that great, though the text will be on the verge of colliding with the border for those reading on a small phone. A fixed size allows you to avoid wall-to-wall text while preventing the gutter becoming too obvious.' I must confess that in this first ePub ebook I hadn't even thought of small phones or larger screens. I'll need to think more about this.

mtravellerh and Jelby Thanks for your clarifying comments.

I really appreciate the time you all spent in reviewing the book. Although I haven't agreed with all your suggestions I will certainly think more about them.

Regards, Alex

[AlexBell]

Originally Posted by charleski

There are ways to incorporate an html fallback for archaic browsers that don't support SVG.

I missed this first time through. Could you point me to a reference please where I can read on this? If I can make SVG work on my ECO reader I'll be more motivated to use SVG as a standard in future ebooks.

Regards, Alex

[charleski]

Originally Posted by Jellby

While I agree it can be annoying, it's not a bug, it's allowed by the CSS spec:

When an unforced page break occurs here, the used values of the relevant 'margin-top' and 'margin-bottom' properties are set to '0'. When a forced page break occurs here, the used value of the relevant 'margin-bottom' property is set to '0'; the relevant 'margin-top' used value may either be set to '0' or retained.

Aha, I didn't know that, thanks. So you're saying the css2 spec is even more b0rked with regard to paged media than I thought. I'll have to check this out as I've got a side-project on working out how to get epubs to work properly on a baseline grid (much harder than I'd thought) and post-break margin-top values have been a mystery.

Originally Posted by AlexBell

- 'I see you defined a class for a flush paragraph but didn't use it.' The CSS was designed to a standard to be used in other ePub books. Some of them will need to have flush paragraphs.
- 'Personally I really think that setting the first paragraph of a section flush looks a lot better.' I suggest we agree to disagree here; it's a matter of taste, I think.

Well, I'm not aware of any convention of style that recommends not setting the first paragraph of a section to be flush. To be frank, seeing a first paragraph that's indented screams 'amateur' - indented paragraphs indicate that they flow on from the previous text whereas setting it flush provides the visual clue needed to indicate a new strand of thought. It's not really an issue of taste, it's an issue of properly communicating the thoughts of the author.

'Although most well-behaved readers will respect the css pagebreaks you insert, some don't (they don't show up in the calibre reader for example). The only sure-fire way to make sure the reader puts in a pagebreak is to break the text into separate flows (separate xhtml files).' Could I suggest that this is a problem for the Calibre reader?

You could, of course, say exactly the same thing about FBReader's archaic inability to handle SVG. The calibre reader does at least have some excuse in that its basic design is scrolling rather than paged.

The ebook meets W3C and ePubCheck standards. I don't think, at first glance, that it's any improvement to break a short book into separate pages.

Ask kovid what he thinks of validation checks. At the end of the day, what matters is what people see on the screen. Breaking the text into separate flows is a trivial task in Sigil.

- At small values like 2% the difference isn't that great, though the text will be on the verge of colliding with the border for those reading on a small phone. A fixed size allows you to avoid wall-to-wall text while preventing the gutter becoming too obvious.' I must confess that in this first ePub ebook I hadn't even thought of small phones or larger screens. I'll need to think more about this.

This, I think, is a matter of taste. Having spent several years reading mobipocket books on my Palm T3 I'm sick of implementations that try to cram as much text on the screen as possible - text really does need some breathing room. mtravellerh's comments are valid, though, and a lot of commercial books use % for the margins.

Originally Posted by AlexBell

I missed this first time through. Could you point me to a reference please where I can read on this? If I can make SVG work on my ECO reader I'll be more motivated to use SVG as a standard in future ebooks.

Here's an example. I don't know if this will work on FBReader, but it should.

[AlexBell]

Originally Posted by charleski

Here's an example. I don't know if this will work on FBReader, but it should.

Thanks again for your help. I've bookmarked this page and will read it carefully

Regards, Alex