InDesign epub code cleanup

[JSWolf]

Originally Posted by Turtle91

Please re-read my post... especially the explanation points below. We agree on most things, you just tend to tell everyone to do it a certain way because that is how you like it on your device, not because it's wrong or because it can't be made to work.

The example I gave, that you quoted above, was an example of using inline styling vs. css classes. It was not meant to tell people to style things any particular way.
Having said that, text-align:left is perfectly fine under certain circumstances, like forcing a left-alignment for stylistic purposes. Setting default font weight and size is also perfectly acceptable...it sets a baseline from which you can change with specific classes. Are they necessary - maybe not, but are they wrong - no.

I'm taking into account, Kobo, Kindle, and a cell phone. I'm trying to give advice that will work on all three.

Due to a bug in Modify ePub, your CSS section break graphic will be deleted if anyone uses the option to remove excess graphics. Modify ePub does not take into account graphics in CSS so any in CSS will get deleted. So you would have to put the <img> code in every section break. Also, for accessibility, the code has to be <hr.transition/>.

[Turtle91]

Originally Posted by JSWolf

As to the section break, you need to use <hr.transition> for accessibility. The following code works well.

hr.transition {
  margin-top: 0.9em;
  margin-right: 40%;
  margin-bottom: 0.9em;
  margin-left: 40%;
  border-top: 2px solid;
}

I'm pretty sure I mentioned using <hr/> as the section break...with multiple examples... and a picture!

According to Accessible Publishing Knowledge Base it says <hr/> is used for accessibility, and then it gives examples using <hr class="transition">. I didn't see anywhere where using that particular class was required. Maybe I missed it. Do you know where it says you must use class="transition"?? I checked my code with an online accessibility checker and it says there is nothing wrong with it. Also, the html5 standard doesn't use a class at all.

There's obviously nothing wrong with using 'transition', but I was just wondering if it is required.

[Turtle91]

Originally Posted by JSWolf

...
Due to a bug in Modify ePub, your CSS section break graphic will be deleted if anyone uses the option to remove excess graphics. Modify ePub does not take into account graphics in CSS so any in CSS will get deleted. So you would have to put the <img> code in every section break. Also, for accessibility, the code has to be <hr.transition/>.

I'm not going to change my correct code just because someone might use a plugin on Calibre that has a bug in it. If the user screws up the document, it's on them.

[nabsltd]

Originally Posted by Turtle91

A 'normal paragraph' is what makes up 98.7% of a chapter. Why have <p class="normal-paragraph"> when it is easier just to have that as a naked tag <p>?? When cleaning up a book's code, that is what I consider 'low hanging fruit', easy to fix, and makes a big improvement in readability.

The problem with this is that for any class you assign to a p element, you need to explicitly override every property that you set for the default. For example, since most people like some sort of indent on the general paragraphs, that means you have to remember to override that with an explicit text-indent: 0;. This can be easy to not notice if the "special" paragraph is centered.

My take is that "bare" elements should have all properties set to the default value as defined by the CSS standard. In other words, a normal "CSS reset".

I have seen EPUBs styled with a "bare" div being set as essentially a block quote:

div {
  margin-left: 2em;
  margin-right: 2em;
  margin-top: 1em;
  margin-bottom: 1em;
  font-size: 0.9em;
}

This is not a good default for something that is just supposed to be a container that can be styled. Nesting quickly results in an unreadable font size.

[j.p.s]

Originally Posted by Turtle91

Having said that, text-align:left is perfectly fine under certain circumstances, like forcing a left-alignment for stylistic purposes. Setting default font weight and size is also perfectly acceptable...it sets a baseline from which you can change with specific classes. Are they necessary - maybe not, but are they wrong - no.

Ooo, you'd better hope Hitch doesn't see the left-alignment bit.

In my opinion as a reader of ebooks, I think specifying "normal paragraph" text alignment, font weight and size is just as wrong as not using semantic tags where appropriate and such details should be left to the rendering software / end user partnership, with the rendering software giving high weight to end user preferences.

(JSWolf's "... all have to go. They are excess code" comment was in the context of a "normal paragraph". I have also experienced the large first letter problems he describes on kindles. In addition, they play havoc with word search reseults.)

[j.p.s]

Originally Posted by Turtle91

I'm not going to change my correct code just because someone might use a plugin on Calibre that has a bug in it. If the user screws up the document, it's on them.

[Turtle91]

Hmmm…. I think I’m just going to say “yadda, yadda” whenever I put up example code…

Again, the intent of the example was for showing the differences between inline styling, classes on everything, and basic tags with classes only on special cases. Y’all can certainly code however you want to! lol

As for having to override the bare tag settings when you have special classes… umm, yeah… that’s what you are supposed to do. When you have a special class, then that class is listed after/below the basic tag so you take advantage of cascading style. Can you miss something, sure, I’ve missed a bunch of things over the years. That doesn’t change the idea of setting a base tag with your 98.7% solution.

Real, the problem is, with nested div/font-size shrinking. So, be aware of it when coding. I rarely use a nested div… when I do, I don’t set the font size in the parent div… it really shouldn’t be there in the first place. I will set a default <div> with styling of the div (basic margins, borders, corners, colors, etc.), but then all the other, non div specific, styling goes in the child tags.

The large first letter word search problem is because people use a work-around to compensate for inadequate devices/apps. They use <span>s around the first letter to enable styling it differently. I don’t use that work-around. I use css to style the first letter that way there is no issue with word search or spelling corrections. Yes, I know some older devices are incapable of using current technology… that’s why I said it was possible ‘in some circumstances’ and that they needed to test on their target devices/apps to see if it works. If not, then use fall-back coding.

The simple coding I use for drop-caps or large-first-letter is:

HTML:
<p class="first">This is the first paragraph in the chapter.</p>

CSS:
p.first {yadda yadda yadda}
p.first:first-line {yadda yadda small-caps yadda}
p.first:first-letter {yadda yadda large letter or drop cap yadda}

[nabsltd]

Originally Posted by JSWolf

I've given no opinion. Its all best practices.

You gave lots of styling opinions. For example, you don't like a line-height greater than 1.1, yet many people find that too tight. This results in your "never use line-height", which is wrong.

As for line-height, there's no need for it as you're not going to be using a dropcap of large first letter.

I use the line-height attribute whenever it is appropriate. I use it on multi-line headings to reduce or increase the spacing between lines. This allows it to change along with font size, instead of remaining fixed. It also allows me to change the space between lines that are part of the same paragraph, split with a <br />.

A large first letter does not work properly on a Kindle because you cannot set the line-height to be smaller.

I have absolutely no problem using line-height of less than 1 so that the span holding larger characters is not used to compute the overall line height. It works perfectly on my Kindle Scribe. I also use it on sub and sup (or anything else that moves text up or down and would often cause a larger computed line height).

The problem with a blank space is that the way most do it, it can be a major fail. If you use a margin to give you that space and it falls at the end/top of a page, the space gets swallowed-up.

I'll bet you didn't know that this happened all the time on physical books too. You just never noticed it because you didn't get to see the "code" underneath. If a section break without a decoration fell at a page break, it often basically disappeared, and the only indicator was the non-indented paragraph.

Also, in a pBook you get *** when the space hits the top/bottom of the page.

This is not universally true. I've got printed books where there is a mixture of "space only" and "decoration" for section breaks, and sometimes the "decoration" falls in the middle of the page, and sometime the "space only" gets swallowed and a new page starts with a non-indented paragraph.

Most embedded fonts do not work well.

Embedded fonts should only be used for something that is not the base reading font. The user gets to pick the base reading font. Using this principle, all embedded fonts work perfectly.

Also, on a Kindle, most people won't see your embedded fonts as they don't switch to Publisher Font.

Choosing "publisher font" is only necessary if the eBook tries to replace the default reading font with an embedded font. When that happens, Kindle ignores it and uses the user-chosen default font. For fonts that are not used to replace the default reading font, embedded fonts display perfectly on Kindle. I have books where entire chapters are a different font from my chosen, and it still works.

Do not use % where em will work better.

% and em are identical for font size, so you can use either in that case. For actual lengths (margins, padding, indents, etc.), both em and % have times when they work better to create the desired look. In general, though, an eBook creator needs to be aware that "em" scales with the font size scaling the device offers while "%" does not. This means that if a user picks a really huge font, "em" for margins can make things very silly (two words per line, or a handful of lines per page), while you can keep your layout somewhat closer to your ideal by using "%" instead.

[JSWolf]

Originally Posted by Turtle91

I'm pretty sure I mentioned using <hr/> as the section break...with multiple examples... and a picture!

According to Accessible Publishing Knowledge Base it says <hr/> is used for accessibility, and then it gives examples using <hr class="transition">. I didn't see anywhere where using that particular class was required. Maybe I missed it. Do you know where it says you must use class="transition"?? I checked my code with an online accessibility checker and it says there is nothing wrong with it. Also, the html5 standard doesn't use a class at all.

There's obviously nothing wrong with using 'transition', but I was just wondering if it is required.

Any ePub 3 I've seen that use hr use <hr class="transition/>. I thought it had to be with the class transition. Seems my sections breaks are accessible.

[nabsltd]

Originally Posted by Turtle91

I didn't see anywhere where using that particular class was required. Maybe I missed it. Do you know where it says you must use class="transition"??

It's not required. Jon doesn't understand how example code works.

[JSWolf]

Originally Posted by nabsltd

The problem with this is that for any class you assign to a p element, you need to explicitly override every property that you set for the default. For example, since most people like some sort of indent on the general paragraphs, that means you have to remember to override that with an explicit text-indent: 0;. This can be easy to not notice if the "special" paragraph is centered.

My take is that "bare" elements should have all properties set to the default value as defined by the CSS standard. In other words, a normal "CSS reset".

I have seen EPUBs styled with a "bare" div being set as essentially a block quote:

div {
  margin-left: 2em;
  margin-right: 2em;
  margin-top: 1em;
  margin-bottom: 1em;
  font-size: 0.9em;
}

This is not a good default for something that is just supposed to be a container that can be styled. Nesting quickly results in an unreadable font size.

I prefer to have a blank <blockquote> instead. I've seen a lot of blank <div> that doesn't need to exist. I'd rather not see <div> anywhere. The problem with the CSS (IMHO) is the font size. If it's smallcaps, it's too large. If it's not smallcaps, it's too small.

I use a left/right margin of 1.5em for <blockquote> and I have another class called .blockquote for when a <blockquote> may be the last bit in the chapter so the margin does not maybe run into the next page and cause a blank page. The bottom margin is set to 0.

This is what I use for a naked <p>.

p {
  margin-top: 0;
  margin-bottom: 0;
  widows: 1;
  orphans: 1;
  text-indent: 1.2em;
}

I see no reason to add bloat when it's not needed. I don't need <p class="someuselessclass"> when <p> works. Also, it makes the code easier to read.

I prefer no class in most cases where possible except <div> where I think it should have a class to differentiate a <div> I can dump.

For chapter headers, this is what I prefer... <h2>Chapter 01</h2>.

[JSWolf]

Originally Posted by j.p.s

Ooo, you'd better hope Hitch doesn't see the left-alignment bit.

In my opinion as a reader of ebooks, I think specifying "normal paragraph" text alignment, font weight and size is just as wrong as not using semantic tags where appropriate and such details should be left to the rendering software / end user partnership, with the rendering software giving high weight to end user preferences.

(JSWolf's "... all have to go. They are excess code" comment was in the context of a "normal paragraph". I have also experienced the large first letter problems he describes on kindles. In addition, they play havoc with word search reseults.)

I didn't think of search results. I would say the same thing happens with a dropcap as well.

Yes, my comment about the CSS code that should go is in terms of a normal paragraph.

I find a lot of CSS has extra code and when I edit an eBook, I'll remove the extra code.

[JSWolf]

Originally Posted by Turtle91

Hmmm…. I think I’m just going to say “yadda, yadda” whenever I put up example code…

Again, the intent of the example was for showing the differences between inline styling, classes on everything, and basic tags with classes only on special cases. Y’all can certainly code however you want to! lol

As for having to override the bare tag settings when you have special classes… umm, yeah… that’s what you are supposed to do. When you have a special class, then that class is listed after/below the basic tag so you take advantage of cascading style. Can you miss something, sure, I’ve missed a bunch of things over the years. That doesn’t change the idea of setting a base tag with your 98.7% solution.

Real, the problem is, with nested div/font-size shrinking. So, be aware of it when coding. I rarely use a nested div… when I do, I don’t set the font size in the parent div… it really shouldn’t be there in the first place. I will set a default <div> with styling of the div (basic margins, borders, corners, colors, etc.), but then all the other, non div specific, styling goes in the child tags.

The large first letter word search problem is because people use a work-around to compensate for inadequate devices/apps. They use <span>s around the first letter to enable styling it differently. I don’t use that work-around. I use css to style the first letter that way there is no issue with word search or spelling corrections. Yes, I know some older devices are incapable of using current technology… that’s why I said it was possible ‘in some circumstances’ and that they needed to test on their target devices/apps to see if it works. If not, then use fall-back coding.

The simple coding I use for drop-caps or large-first-letter is:

HTML:
<p class="first">This is the first paragraph in the chapter.</p>

CSS:
p.first {yadda yadda yadda}
p.first:first-line {yadda yadda small-caps yadda}
p.first:first-letter {yadda yadda large letter or drop cap yadda}

Note: if an eBook is being created for sale, you want to use the fall back coding (aka <span class="firstletter">) because you want your eBook to work in as many programs as possible. You want ot use as much ePub 2 compatible code as possible and you don't want to use any ePub 3 code where it's going to cause a problem with ePub 2 only programs.

Can you create code for a large first letter that works with a Kindle so the first line of the paragraph has the same height?

[Turtle91]

Originally Posted by JSWolf

Note: if an eBook is being created for sale, you want to use the fall back coding (aka <span class="firstletter">) because you want your eBook to work in as many programs as possible. You want ot use as much ePub 2 compatible code as possible and you don't want to use any ePub 3 code where it's going to cause a problem with ePub 2 only programs.

Can you create code for a large first letter that works with a Kindle so the first line of the paragraph has the same height?

Ummm. Not true. I exclusively use ePub 2 as I haven’t gotten around to learning ePub3 yet.

Yes, I can, and do. I’ll take a screen shot and post it when I get home.

Edit:
Looks like you changed your comment while I was writing mine . You had said that code was only good for ePub3, which is not true. We’ve had this discussion before where you think pseudo-selectors are only ePub3, they are not.

Also, here is a screenshot from my phone. I used the above code, ePub2, and have a large first letter, small-caps for the first line - all with no spans or forced uppercase.

Edit-Edit:
I'm not sure what the MR rules are about an excerpt from a copyright book. The copyright notice in the book says brief quotes are allowed for book reviews. So, I'll put a quick review here if anyone is interested.

Spoiler:

The Emmisary by Michael J. Edwards
Available on Amazon here
I'm only on Chapter 7, but so far it has grabbed my attention. Aliens, space ships, politics, teachers... Great Job! Other than an eyebrow raising, heart beating, ohhh 'I'm all a-twitter' beginning of Chapter 2, it's been clean... I'd say mid-tweens or higher.

[JSWolf]

Originally Posted by nabsltd

You gave lots of styling opinions. For example, you don't like a line-height greater than 1.1, yet many people find that too tight. This results in your "never use line-height", which is wrong.

A lot of software these days allows you to set a line height. But some do not completely override and you can only go larger. That's why not to use line height. It's nothing to do with my preference. If you like a large line height and oyu use a program that allows you to set a line height, set it as you like and I'll set it as I like. Put in a line height and we may not be able to set it as we like.

I use the line-height attribute whenever it is appropriate. I use it on multi-line headings to reduce or increase the spacing between lines. This allows it to change along with font size, instead of remaining fixed. It also allows me to change the space between lines that are part of the same paragraph, split with a <br />.

Use a margin instead of a line height.

I have absolutely no problem using line-height of less than 1 so that the span holding larger characters is not used to compute the overall line height. It works perfectly on my Kindle Scribe. I also use it on sub and sup (or anything else that moves text up or down and would often cause a larger computed line height).

Maybe it works on your Scribe, but I know for sure that older Kindles would not work with a line height of 1. You could not normalize the large letter and the line it is in was offset because the line height changed,

I'll bet you didn't know that this happened all the time on physical books too. You just never noticed it because you didn't get to see the "code" underneath. If a section break without a decoration fell at a page break, it often basically disappeared, and the only indicator was the non-indented paragraph.

That's because the section break space was a margin and not padding. Padding works as the space does not disappear. But overall, it's easier to see the section break if it falls at the end/beginning of a page if there is something other then just space.

This is not universally true. I've got printed books where there is a mixture of "space only" and "decoration" for section breaks, and sometimes the "decoration" falls in the middle of the page, and sometime the "space only" gets swallowed and a new page starts with a non-indented paragraph.

Maybe it's not always true, but it's mostly true. I've read a lot of pBooks where there was blank space for a section break except for when it falls at the end of a page.

Embedded fonts should only be used for something that is not the base reading font. The user gets to pick the base reading font. Using this principle, all embedded fonts work perfectly.

Have you ever read the eBook The Martian by Andy Weir? It was made with free-serif, free-sans, and free-mono as embedded fonts. These are terrible fonts. There are bits in the book that are supposed to be monospace and free-mono is very hard to read on an eInk screen because it's very much too lightweight. The next worse is free-sans followed by free-serif. Overall it's a reading experience that would make you stop reading the book even if you are enjoying it.

Choosing "publisher font" is only necessary if the eBook tries to replace the default reading font with an embedded font. When that happens, Kindle ignores it and uses the user-chosen default font. For fonts that are not used to replace the default reading font, embedded fonts display perfectly on Kindle. I have books where entire chapters are a different font from my chosen, and it still works.

Does this appy to KF8 or just KFX?

% and em are identical for font size, so you can use either in that case. For actual lengths (margins, padding, indents, etc.), both em and % have times when they work better to create the desired look. In general, though, an eBook creator needs to be aware that "em" scales with the font size scaling the device offers while "%" does not. This means that if a user picks a really huge font, "em" for margins can make things very silly (two words per line, or a handful of lines per page), while you can keep your layout somewhat closer to your ideal by using "%" instead.

I'm not meaning font size. I've seen many cases where the margin uses % and that changes based on the screen. So using em will be consistent regardless of the screen.