8 | Editorial Concerns

This section focuses on common things that cause rendering errors in EPUB and MOBI formats. All of these issues need to be revised or otherwise resolved to disarm any threats to reader immersion.

ACTION: Continue Working in prep_projectx

During this section, make any required changes in the prep_projectx file. Save frequently!

Section Index

• Tables

• Nested Lists

• Blank Lines

  • Manual Line Breaks, Page Breaks and Section Breaks

• Special Fonts

• Hyperlinks

• Special Characters

  • Ellipses, Hyphens, Em- and En-dashes

  • The Ampersand

  • Quotation Marks & Apostrophes

• Block Quotes

Tables

In EPUB and MOBI formats, tables will not render. Period. Any information delivered in table form must be revised into a plain-text format.

If all else fails, consider saving the table as an image file, but bear in mind that images (other than cover art) must never be wider than 350px. Also bear in mind that many e-reader devices only render in black and white.

ETA: It's not strictly true that tables will not render. They do, but the potential for alignment errors is extremely high, especially when a table is more than two columns wide. Best practice is to eliminate all tables in order to ensure the best possible reader experience.

ACTION: Go Table-less

Revise any tables into plain-text or image.

Return To Section Index

Nested Lists

Nested lists rarely render correctly.

This is how authors expect their lists to look:

Best case scenario, the example below is how the nested list will actually render. (Hey, at least the first level indented, right?)

More often than not, this is how lists render:

Revise all lists so that the lack of cascading, level-fluctuating indents will not confuse the reader. Better yet, why not get rid of all lists entirely? What purpose is the list really serving in straight-form fiction? Without an extremely compelling answer, ditch it.

ACTION: Refine or Re-Think Lists

Remove or simplify any lists in the prep_projectx file.

Return To Section Index

Blank Lines As Formatting Features

No. Just no. Every single e-book-making resource ever written has warned against using a blank line to represent a time jump, a swap in narrative point of view, or any other spatial-formatting convention.

This time, please listen. This is a deal-breaker issue. In this age of small screens, the chance of your blank line rendering at the very top of a screen or the very bottom is high enough to be a factor in good decision making.

Let's look at this from the ground up.

Readers are taught from day one that blank lines in the middle of narrative signal a change of some sort.

In print, a typesetter would NEVER place those blank lines at the very top or very bottom of a page. The reader would not notice the extra space. They would not be warned by this convention that a change was about to take place, and the change would break their immersion, jarring them off the page.

In this tutorial, that kind of thoughtless laziness is an unforgivable editorial mistake. ANYTHING that could potentially cause a reader to put a book down is considered an unforgivable editorial mistake, so no matter HOW we add padding space between paragraphs or other elements, we must always keep in mind that we are not dealing with fixed layout, here. We cannot begin to guess what will constitute a "page" on our end-users' devices. We can't know how much of our content will render onto a page, because we have no way of knowing screen sizes, orientation, resolution, nor what their settings might be.

Bottom line: do not rely on blank lines to signal a change. Too many variances out there make blank lines too unreliable for such an important job.

I know that a lot of authors and ebook producers view scene-break characters with the highest disdain. To avoid this, we can either pull the toffee out of our noses, or substitute a small, lightweight (I'm talking less than 10kb in size) graphic instead. 

• • The most common scene-break character strings are * * * or * * * * * or # # # or # # # # #.

  • More advanced productions can also use small, centered graphics as scene break characters. (Remember these pretty little things can increase file size dramatically and screw you for sale pricing later on.)

  • These scene-break characters actually have a name! "Fleuron". Who knew?

• Place a ##scene## slug before each set of scene-break characters. This makes them much easier to find during production.

  • Do not use blank lines. Don't use blank lines, because you will get pregnant and die! Don't use blank lines in the missionary position, don't use blank lines standing up, just don't do it, OK, promise? OK, now everybody take some rubbers. (For our humorless friends, yes, that was a Mean Girls reference.)

Example of slugged scene-break characters:

ACTION list: Manage Blank Lines

• 1. Insert scene-break characters in place of any blank lines used as formatting breaks

  2. Place a ##scene## slug before each set of scene-break characters

  3. Note the position of each scene break in key_projectx

Return To Section Index

Manual Line Breaks, Page Breaks and Section Breaks

None of these things require revision or removal. I only mention these here because they are forcibly removed during the housekeeping section, and I don’t want anyone to freak out later.

Remember, none of these things has any relevance in a digital format. They are removed to prevent non-printing cockroaches that can create a paragraph-container glitch later.

Special Fonts

Two main concerns with special fonts:

1. Usage

2. Attachment

Usage:

Currently, only bold, italic, strike-through and underline are supported in EPUB and MOBI.

• • Only bold and italic special fonts are recommended.

  • Depending on the user's font size settings, bold font can be damned hard to discern from normal.

  • There is no justifiable need for strike-through font. It’s an immersion breaker that reeks heavily of author intrusion.

  • Never use underline font for anything outside of footnotes. Readers will think it’s a hyperlink. (This is undoubtably the reason Annie took an axe to that cockadoodie Sheldon guy.)

  • Also, please remember that readers select the font. We don’t. The less dicking-around done with fonts, the better off the reader is.

This is why we can’t have nice things.

You can keep clicking that thing all day, and you won’t get anywhere. The above text is blue underlined font, not a hyperlink. It’s a good example of this highly scientific equation:

fancy + over-formatted text = confusing suck

Attachment:

When working on client files, I often find italic and bold font attached to stray spaces and punctuation, with none of the surrounding words italicized. This is an artifact of editing. While these stray bits of in-line formatting aren't visible in the file, they're visible in the code once we make it to the HTML stage.

For the most part, this is harmless. I haven't run across an instance where this has caused trouble in an EPUB or MOBI yet, but it is sloppy.

I've solved this problem in my own process by, just before (not after) I begin revisions or editing, nuking the manuscript without preserving italics or bold. (Nuking removes everything but the text character and most basic formatting coding -- that's a whole other tutorial, coming soon.)

That way, I'm starting over fresh and can attach italics and bold more precisely, following these guidelines:

• Attach italics or bold only to words.

• Do not attach italics or bold to punctuation, except in cases where an exclamation point or question mark would require it.

• Do not attach italics or bold to quotation marks.

• Do not attach italics or bold across a paragraph return. Stop before the end punctuation on one paragraph and start italics over again on the next — don't cross the streams.

ACTION: Manage Special Fonts

• Revise out any gratuitous or confusing use of special fonts.

• Clean up your code following safe special-font attachment guidelines.

Return To Section Index

Hyperlinks

Some (probably skewed) semantics:

• • This is an embedded link: embedded link

  • This is an activated URL: http://tinyurl.com/xzg777

  • This is just a visible URL: http://tinyurl.com/xzg777

Please do not embed hyperlinks in projectx. The entire URL must always be visible on the screen, as shown by GOOD in the example below.

An embedded hyperlink will not survive the conversion to HTML. For now, show only the URL on the page. Even when we activate these later in Sigil, we will still never embed a hyperlink.

Why? Not every e-reader device is browser-enabled. These devices cannot retrieve and display the content targeted by hyperlinks. Look into options such as tinyurl.com that shorten links so that a reader can easily type the shortened URL into a different web-enabled device with browser capability.

Ellipsis marks:

An ellipse can be end punctuation. An ellipse can be followed by end punctuation. Regardless, for the purposes of this tutorial, the ellipse itself is a single punctuation character, not three or four.

• • The use of three periods (with or without spaces between) as an ellipse can lead to the periods broken up from one line to the next. One or two will render on one line, the remainder on the next. This is NOT what you want.

  • Do not leave a space before an ellipse. The mark should always be flush with the text that precedes it. If this travesty should occur at the end of a paragraph and fall at the end of a line, the space may ‘orphan’ the ellipse and it will render on its own line. #barf

  • Just about every word processor has a function to insert special characters. If your word processor does not auto-correct your ellipses, you may need to insert each mark manually using Insert symbol, your computer's character map, or by substituting the ellipse's HTML number …

For instance, to get this:

No... filtered... HTML... evar!

Use this:

No… filtered… HTML… evar!

Hyphens, en dashes and em dashes:

These marks are not interchangeable. Each has its own use(s).

Two of them cause a crap-ton of rendering errors. The en dash and em dash are notorious for rendering improperly or not at all.

I have never yet seen a problem with the hyphen mark itself. The eye-tripping trouble starts where authors use hyphens in place of the longer en or em dashes. Make sure each usage is correct. When in doubt, consult the style guide of your choice. Then check EVERY SINGLE dash, hyphen, en dash and em dash in the file.

If unsure how to properly create en and em dashes on your specific keyboard and system, it’s Google time. (It would take an entire page for me to list off the various legal methods for umpteen setups.)

The tricks to EPUB/MOBI-safe dashes are:

• • Make sure to use a ‘legal’ en or em dash, inserted via Insert, Character Map, or keyboard shortcut. Yes, this could mean going through every single character in projectx to make sure each is properly encoded. Look on the bright side, Dorothy. I can guarantee you'll never make another dash mistake while writing again.

  • Be consistent in usage.

  • Make sure the same symbol is used in every instance.

  • Create or insert the characters exactly the same way each time.

  • Use the yellow-helmet test to check en or em dashes. Highlight text containing an en or em dash in the projectx file. Copy and paste that text into a plain-text editor like Notepad or TextEdit. If the dash renders properly, you’re probably safe, but make sure to check it again in the final EPUB version.

More EPUB/MOBI-safe symbol guidelines:

• • Em dashes should not have a space on either side. Spaces can cause an orphaned em dash that renders on its own line. #puke

  • Same with en dashes. No spaces on either side, please.

  • Do not use two (or more) hyphens in a row instead of an en or em dash. If this disaster appears at the end of a line, devices may leave one or two hyphen(s) on one line and slip the rest down to the next line.

The real trouble with en and em dashes is inconsistency. Going back to my editing days, I learned that a majority of authors have no idea how to properly create these symbols. So they improvised a lot and ended up with different symbols or combinations of symbols in their content. Sometimes they used an en dash or two en dashes, two hyphens, a hyphen and an en dash or whatever other weird combination or pattern of usage.

If the mess isn't caught and dealt with during the editing phase, the inconsistencies create hell on earth come production time. Imagine trying to use Find/Replace to normalize these when you have no idea how the symbols were used (improperly, properly, or consistently) let alone whether they were all created the same way every time.

There are plenty of freelance editors out there who don't pay attention to these things. THE PRODUCER HAS TO PAY ATTENTION. These symbols, if not properly and consistently embedded in the projectx file, will render incorrectly or not at all, breaking the reader's immersion. Game. Over.

Visit this glorious, glorious page for more encoding information. 

Should rendering issues occur with any of these symbols, at Sigil stage, insert the HTML number right into the text.

• • … is the HTML number for the horizontal ellipse

  • – is the HTML number for the en dash

  • — is the HTML number for the em dash

For example, to get this:

Dashes suck—Bet you won’t use so many next time.

Use this:

Dashes suck—Bet you won’t use so many next time.

Ironically, in order to get an em dash to render in this tutorial, I had to use the em dash entity name instead of the number. —

Quotation Marks And Apostrophes

I believe this falls under OCD craziness, but since I find myself fixing these for people more and more, I think it's worth covering in the tutorial.

Here's the bad news: Kindle's encoding language, ISO 8859-1, has no unique name/number for oriented left or right (opening or closing) quotation marks, probably better known as the oriented or curly quotes. This language allows only for straight quotes. 

Here's the good news: HTML does have unique characters for each of these important symbols, and Kindle does recognize and render the HTML numbers. (the names are iffy across versions)

Unless a user encodes these especially, this tutorial will yield all oriented single and double quotation marks... as long as these marks were properly handled in the first place. Users who want more control over these characters will have to substitute the character codes in at the word processor stage, which, be warned, is a LOT of work. It's up to the user to decide whether it's worth the fuss.

This craziness grew lengthy enough to earn its own page.

The Ampersand

Oh, this troublesome little devil…

Notice how HTML names and numbers all start with the ampersand? (&) Yeah, well, no HTML-based rendering device can tell the difference between a plain-old ampersand and an ampersand used at the start of an HTML name or number. You'd think it would work fine if the ampersand had a space on either side, but the ampersand tends to fail the yellow-helmet test too, so...

Short of saying NEVER USE THIS SYMBOL, I cannot stress enough how problematic this symbol can be. Certainly never butt an ampersand up against other text unless in the case of an HTML name or number.

For the EPUB and MOBI formats, this symbol must never appear in a filename or header. Never. Never, never, ever. Use the word ‘and’ instead.

Best practice: If used in regular text, the ampersand should be replaced by its HTML name: &

Except where used as part of an HTML name or number, users should replace every instance of & with &

For instance, to get this:

EPUB & MOBI Tutorial

Use this:

EPUB & MOBI Tutorial

ACTION list: Manage Special Characters

• 1. Go through projectx symbol by symbol to ensure each special character is proper and consistent.

  2. (Optional): Take note in the key of where special characters appear in the story text so these symbols can be checked in post-production for rendering issues.

Return To Section Index

Block Quotes

These are commonly used for framing sections of text, like showing a note or a letter, or perhaps a dream sequence or flashback.

During the production process, we place slugs before each paragraph of block-quoted text.

I repeat: Production slugs must be placed before each paragraph of block-quoted text. EACH. PARAGRAPH. Even if that paragraph is only one word or one sentence long, EACH PARAGRAPH must be slugged. I don't know why, exactly, but people new to this process tend to miss block-quote paragraphs, so you lucky devils get all the preaching about EACH PARAGRAPH.

There are two different block quote types defined in our CSS file: those that require a first-line indent, and those that don’t. Each needs to be slugged differently in your manuscript file.

First-line indent slug = ##bqi##

No first-line indent slug = ##bqnoi##

Heads Up: The CSS file we’ll use automatically italicizes block-quoted text. While going through your file placing these slugs, please de-italicize the block-quoted text. This eliminates some wonky in-line CSS that can show up during tagging stage.

BEFORE:

AFTER:

ACTION list: Manage Block Quotes

• 1. Place the appropriate block quote slug (##bqi## or ##bqnoi##) before each paragraph of block-quoted text.

  2. De-italicize block quoted text in the projectx file to prevent issues later.

  3. Note the location of each block quote tag in key_projectx, as shown below:

Return To Section Index

Previous << Finalize Partitions | Next >> Images