InDesign epub code cleanup

[Turtle91]

Originally Posted by paperwhite13

Oh, I see now. So they completely ignore the toc.ncx/toc.xhtml files? Are there many apps/devices that do that? I'm amazed they exist, given the emphasis on those files in the structure of an epub.

But other than that, would it be semantically correct to tag them as I did previously?

There are so many devices, and especially apps, that I couldn't really say how many did what, and how many didn't respect the standard in one way or another. That is why the recommendations are to be as simple as possible...it tends to work better on more devices. BUT, if the devices/apps in your target market are capable and standards compliant then you can get more creative.

[JSWolf]

Originally Posted by paperwhite13

Thank you all for your replies! I understand your reasoning, especially if the TOC gets generated at the end, but keeping in mind my case -- I already have the TOC generated from InDesign, what would be wrong about using this? Wouldn’t it be semantically correct? I though I was just getting the hang of this

h1 {
	font-family:"Font1", sans-serif;
	font-size:2em;
	font-style:normal;
	font-weight:normal;
	border-width:0;
	margin-bottom:5%;
	margin-left:0;
	margin-right:0;
	margin-top:10%;
	text-align:center;
	text-indent:0;
	padding:0;
}
h1.chapter-no {
	font-family:"Font2", serif;
	font-size:1em;
	margin-bottom:0;
	margin-top:5%;
}
------------------
<h1 class="chapter-no">1.</h1>
<h1 id="_idParaDest-3"><a id="_idTextAnchor005"></a>>Chapter Title</h1>

As you can see below, I've cleaned up the code. I've fixed the spacing, removed CSS not needed. and fixed what's not correct. You do not use % for margins for chapter headers. You use em. With different devices you'll have completely different spacing. On a phone, % can take up more of the screen. On 6", 7", 8", and 10" screen, the spacing will all be different. That's not good. indents are also not good to use %. You also don't need to reset everything such as padding. You don't need L/R margins, border width. and padding if they are 0. You don't need font style if it's not doing anything.

Onto the HTML. Your ID's do nothing so you don't need them. You also don't need an <a> that does nothing but holds an id that does nothing. If in your ToC, you have these ID's, then get rid of them. If your ToC entries are going to the top of each HTML file then forget IDs. They will slow things down as the Reader has to load the HTML and then go find the ID instead of just loading the HTML and starting from the top. Also, that's code bloat when you have code that does nothing.

I changed the second line in the chapter header to be a <p> because then it won't be used if you use calibre or Sigil to generate a ToC from your headers. The title= I put in will be the ToC entry if you do generate a ToC from calibre or Sigil.

The thing is, once you export your book from InDesign as an ePub, you will need to hand edit the code. After you've done this you and you make changes to the text in InDesign you will want to make the changes to the ePub and not generate a new ePub as you will then have to once again hand edit the code. InDesign can make some rather messy code. I've edited a lot of eBooks that came from InDesign and they messy. When you hand edit, I suggest you change class names to make sense if any of the InDesign classes don't make sense.

Do you need an embedded font for the chapter titles? If you do, change the font family names to the names of the font(s) being used. But you don't need two different fonts for the chapter title. That's ugly.

[code]

h1 {
  font-family: "Font1", sans-serif;
  font-size: 2em;
  font-weight: normal;
  margin-top: 0.5em;
  margin-bottom: 1em;
  text-align:center;
  text-indent: 0;
}
.chapter-no {
  font-family: "Font2", serif;
  margin-bottom: 0;
  margin-top: 1em;
}

<h1 class="chapter-no" title="1. Chapter Title">1.</h1>
<p class="chapter-no">Chapter Title</p>

[JSWolf]

Originally Posted by Turtle91

Not all devices/apps use your ToC; some create their own ToC dynamically based on your headings.

In your case it would see two <h1>s in a row.

Depending on your target market you may not see any problem at all…. Or it could look kinda ugly.

Which devices create a ToC on the fly and ignore an existing ToC?

[paperwhite13]

Originally Posted by JSWolf

Onto the HTML. Your ID's do nothing so you don't need them. You also don't need an <a> that does nothing but holds an id that does nothing. If in your ToC, you have these ID's, then get rid of them. If your ToC entries are going to the top of each HTML file then forget IDs. They will slow things down as the Reader has to load the HTML and then go find the ID instead of just loading the HTML and starting from the top. Also, that's code bloat when you have code that does nothing.

Thank you for the pointers!

No, it is just in this case (main chapter titles, just a couple of them) where the TOC points to the top of the page, otherwise there are dozens of section titles which need the ID's for the TOC to work. I also need the text anchor IDs for the index references, which point to the physical version, so there have to be text anchors spread out for it to work.

Originally Posted by JSWolf

I changed the second line in the chapter header to be a <p> because then it won't be used if you use calibre or Sigil to generate a ToC from your headers. The title= I put in will be the ToC entry if you do generate a ToC from calibre or Sigil.

Like I said, I already have a perfectly working ToC from InDesign and that’s my workflow going forward, I’m not generating it from the headers.

Originally Posted by JSWolf

The thing is, once you export your book from InDesign as an ePub, you will need to hand edit the code.

It's the title of this thread, it's what I came here for

Originally Posted by JSWolf

Do you need an embedded font for the chapter titles? If you do, change the font family names to the names of the font(s) being used. But you don't need two different fonts for the chapter title. That's ugly.

Yes, it's the publisher’s request that on the devices that support publisher styles/font it should appear the same as the physical version, hence the fonts and the styling. It works very well on KBReader, Lithium, latest KOReader on my Kindle PW3, drop caps included on some of them. Whether that's beautiful or ugly is irrelevant for this thread.

[paperwhite13]

I randomly checked an epub from Oxford University Press with the same academic subject as the one I'm working on and here’s how they do the chapter number/chapter title:

<h2 class="ch_title1" id="oso-666-chapter-1"><a id="page_1"/><a href="04_Contents1.xhtml#n0001">1</a></h2>
<h2 class="ch_title2"><a href="04_Contents1.xhtml#n0001"><em>Movie Title</em> Something</a></h2>
-------
h2.ch_title1 {
font-size: 160%;
font-weight: bold;
text-align: center;
text-indent: 0em;
margin-left: 0em;
margin-right: 0em;
margin-top: 2em;
margin-bottom: 0em;
}
h2.ch_title2 {
font-size: 140%;
font-weight: bold;
text-align: center;
text-indent: 0em;
margin-left: 0em;
margin-right: 0em;
margin-top: 0em;
margin-bottom: 2.75em;
}

[Quoth]

Some renderers will ignore margin-top on an item that's at the start of a file, which is thus a new page. Using padding-top for any first item in a file (like a chapter heading, next title in omnibus, section heading etc that are on new pages) seems to work on everything.

The Elephant in the room is really InDesign. It's really Corporate DTP for paper books, magazines etc later fudged by Adobe for ebooks, which is why it works a bit better for Fixed Layout (electronic but not really ebooks) epub.

Almost no Kindle users will be jailbroken, which is needed for KOReader. Test azw3 as a minimum on a Kindle.

[JSWolf]

Originally Posted by paperwhite13

Thank you for the pointers!

No, it is just in this case (main chapter titles, just a couple of them) where the TOC points to the top of the page, otherwise there are dozens of section titles which need the ID's for the TOC to work. I also need the text anchor IDs for the index references, which point to the physical version, so there have to be text anchors spread out for it to work.

You don't need two IDs together. In your sample, you can drop the <a> and use the other ID in the index. Have a look and see where you have double IDs and drop one of them. Also, where the ToC is going to the top of the HTML file, if the ID is not needed for the index, you don't need that ID.

Yes, it's the publisher’s request that on the devices that support publisher styles/font it should appear the same as the physical version, hence the fonts and the styling. It works very well on KBReader, Lithium, latest KOReader on my Kindle PW3, drop caps included on some of them. Whether that's beautiful or ugly is irrelevant for this thread.

The thing is, do the fonts used in the book work well on an eInk Reader? Do they have enough weight? If they don't, then they won't work. I've seen plenty of eBooks using the same fonts as the pBook and they do not work as they are too light. Besides, On some Readers, such as a Kinde, these fonts probably won't be seen. On some you are forcing the user to use fonts that are not good. Tell that to whoever is in charge. Show him/her how well that fonts do not work.

[paperwhite13]

Originally Posted by Quoth

The Elephant in the room is really InDesign. It's really Corporate DTP for paper books, magazines etc later fudged by Adobe for ebooks, which is why it works a bit better for Fixed Layout (electronic but not really ebooks) epub.

Almost no Kindle users will be jailbroken, which is needed for KOReader. Test azw3 as a minimum on a Kindle.

It can’t really be the elephant in the room as long as it’s the title of its thread and the cleaning it implies With all its flaws, there is no better DTP program for print, and most typesetters are in my position--getting an epub out of a print publication. Even with all the redundant code it produces, I don’t expect to be that difficult to clean up in the future once I get better at this.

I know about Kindle, I was using KOReader as just another epub reader for testing, this book probably won’t even end up in the Kindle ecosystem.

Originally Posted by JSWolf

You don't need two IDs together. In your sample, you can drop the <a> and use the other ID in the index. Have a look and see where you have double IDs and drop one of them. Also, where the ToC is going to the top of the HTML file, if the ID is not needed for the index, you don't need that ID.

Got it, thank you. Like I said, there are just a few places with double IDs.

Originally Posted by JSWolf

The thing is, do the fonts used in the book work well on an eInk Reader? Do they have enough weight? If they don't, then they won't work. I've seen plenty of eBooks using the same fonts as the pBook and they do not work as they are too light. Besides, On some Readers, such as a Kinde, these fonts probably won't be seen. On some you are forcing the user to use fonts that are not good.

Both my publisher and I think they do work.

Originally Posted by JSWolf

Tell that to whoever is in charge. Show him/her how well that fonts do not work..

But you seem to be certain, without even knowing what they are, that they don’t On top of being a typesetter, I read a lot of ebooks and I already have an opinion of what does and what doesn’t work on en eink screen.

[JSWolf]

Originally Posted by paperwhite13

Both my publisher and I think they do work.

But you seem to be certain, without even knowing what they are, that they don’t On top of being a typesetter, I read a lot of ebooks and I already have an opinion of what does and what doesn’t work on en eink screen.

Which fonts are you embedding? I've seen many eBooks that are embedding Adobe Garamond Pro. The problem is not that you cannot embed it. The problem is that the weight of the font is too light and for a lot of people, it's unreadable. There is not enough contrast. So you have to use fonts that either have enough contrast or you are not using these lightweight fonts too much.

Adobe Garamond Pro is a terrible font for an eInk screen. So using it as the body font does not work because of the poor contrast. That's what I mean when I say fonts may not work. They have to have the contrast needed for an eInk screen. The problem is that if you want to use a font that has enough contrast on eInk, it may be too heavy for the pBook. This is why you should not try to duplicate the pBook. An eBook is not a pBook. It doesn't always work.

[paperwhite13]

Originally Posted by JSWolf

Which fonts are you embedding? I've seen many eBooks that are embedding Adobe Garamond Pro. The problem is not that you cannot embed it. The problem is that the weight of the font is too light and for a lot of people, it's unreadable. There is not enough contrast. So you have to use fonts that either have enough contrast or you are not using these lightweight fonts too much.

Adobe Garamond Pro is a terrible font for an eInk screen. So using it as the body font does not work because of the poor contrast. That's what I mean when I say fonts may not work. They have to have the contrast needed for an eInk screen. The problem is that if you want to use a font that has enough contrast on eInk, it may be too heavy for the pBook. This is why you should not try to duplicate the pBook. An eBook is not a pBook. It doesn't always work.

It's not Garamond Pro, but I'm not telling you what it is, you're just gonna have to trust me on this

[Turtle91]

I'm so sorry it took me longer than expected to get these examples...I couldn't find the images I had made, and my search-fu is not strong...

Attached are a few examples of how using a basic chapter header tag works. From testing accomplished by others it works very well on almost all devices...the one exception if you try and send your ePub through the kepubify service it requires a more precise descriptor (you need to add a class="..." to the <span>.

CSS:
h3 {yadda yadda}
h3 span {display:block; yadda yadda}

HTML:
<h3>Chapter 1 <span>Chapter Title</span></h3>

<p class="first">This is the first paragraph in the chapter.</p>
<p>This is the second, and subsequent, paragraph(s) in the chapter.</p>

You can do all kinds of fun display stuff just by manipulating the CSS. You can, and should, also provide fallback CSS for those devices that don't support current standards. And, best of all, if the device/app completely ignores the CSS and uses their own, then it is still completely readable and searchable!


Edit:
And yes, Jon, we know you don't approve of anyone else's coding...but the great part is you can change it to whatever YOU want!

[JSWolf]

Originally Posted by Turtle91

I'm so sorry it took me longer than expected to get these examples...I couldn't find the images I had made, and my search-fu is not strong...

Attached are a few examples of how using a basic chapter header tag works. From testing accomplished by others it works very well on almost all devices...the one exception if you try and send your ePub through the kepubify service it requires a more precise descriptor (you need to add a class="..." to the <span>.

CSS:
h3 {yadda yadda}
h3 span {display:block; yadda yadda}

HTML:
<h3>Chapter 1 <span>Chapter Title</span></h3>

<p class="first">This is the first paragraph in the chapter.</p>
<p>This is the second, and subsequent, paragraph(s) in the chapter.</p>

You can do all kinds of fun display stuff just by manipulating the CSS. You can, and should, also provide fallback CSS for those devices that don't support current standards. And, best of all, if the device/app completely ignores the CSS and uses their own, then it is still completely readable and searchable!


Edit:
And yes, Jon, we know you don't approve of anyone else's coding...but the great part is you can change it to whatever YOU want!

I don't like the 2nd example. There is too much space between the chapter number and the title.

In the first example, there is too much space between the chapter title and the first paragraph (IMHO).

In the third example, I think the chapter header would look better if it was more centered vertically in the space there. Then it would look better. I also like that it does not have an excess of white space. I've seen some chapter headers that use 15% of wasted space.

[Turtle91]

What the, actual, Frack, Jon!


Let’s try a learning experiment. You, actually READ someone’s post BEFORE you complain…


You might actually learn something….

[ZOOM]
Edit:
And yes, Jon, we know you don't approve of anyone else's coding...but the great part is you can change it to whatever YOU want!
[/ZOOM]

[nabsltd]

Originally Posted by JSWolf

For a large first letter, a line height of 0 works. No need to have to figure anything out.

This causes problems if the letter has a descender. Using (1 / font-size) causes the renderer to deal with descenders correctly.

But on a Kindle, you cannot use a line height as small as you are saying as it won't work.

For eBooks that use the "small-caps for enough of the first line to fill a 6-inch screen, but look stupid on a Scribe because the intent is to affect the entire first line", I use the following all the time and it works perfectly on my Scribe:

.para-firstinchapter {
	text-align: justify;
}
.para-firstinchapter::first-line {
	font-variant: small-caps;
	font-size: 120%;
	line-height: 0.8;
}
.para-firstinchapter::first-letter {
	font-size: 200%;
	line-height: 0.5;
}

Maybe. But for most Kindles a line height small enough to fix a large first letter won't work. It will be ignored.

This is absolutely not true. You don't understand how line-height works in an inline element. It's not an absolute. It tells the renderer "use this when computing what this inline element does to the absolute line height of the entire line". You can't reduce the absolute line height of body text below 1.2 on a Kindle, but you can make sure that a character or two of a larger font does not contribute to the calculation to make it larger.

You can see in the attached screenshot that the Kindle renders the same space between each line, despite the large first character, and overall larger font size that my code uses. Note that the "H" in "He" is 13 pixels high, while the "E" in "English" on the next line is only 11 pixels. The whole first line uses a larger font, but the line spacing is 25 pixels (baseline to baseline). This is actually 2 pixels less than the line spacing in the rest of the page, likely due to the exact way Kindle determines the value.

Padding works if you insist on having blank space for a section break. Margins can get swallowed. There's no visual difference except if the padding falls at the bottom/top of the screen. If it does, then you do see the space.

I don't need to see a blank space at the top of a page...it's a new page, and the paragraph isn't indented. That enough cue for me to know it's a section break.

The thing with em is that I have my Libra 2 and you can have your scribe and the indents will be exactly the same at the same font size. With %, we'd have different indents.

Again, you don't understand how this has been done for years. Physical books do use an first line indent based on em, so the indent is the same on a hardback or a paperback. That's one case where "em" is the right way to state a length. A margin change, on the other hand (like for a blockquote), is the same size relative to the page (i.e., smaller absolutely in a paperback), so it's better to use percent.

[nabsltd]

Originally Posted by paperwhite13

Wouldn’t it be semantically correct?

h1 {

/* elided */

}

My personal take is that I never directly style a bare element. I create a class selector and apply the attributes to that, then apply the style to the element (h1 in this case).

I do this because h1 has semantic meaning, and so all headings at the same level should use that element. But, many books want "special" chapters (like "Acknowledgements" or "Epilogue") to look slightly different from "normal" chapters. For example, some books use a fairly large (3em to 4em) font for chapters that are just a bare number (i.e., 7), while the "Epilogue" is only 1.5 to 2em. Those "special" chapters are still at the same level as the "normal" ones...they aren't parents or children...so they need the same element.

By directly styling the h1, you have to "undo" the base formatting for the "special" chapters. You would then use something like h1.normalchapter and h1.specialchapter. But, if you are going to do that, why bother restricting to h1? If you decide you need to change the level of headings down or up, then the stylesheet has to be changed to match. Without restricting to a single element and a class, instead only using a class, it's more flexible.