Advanced Mobi and EPUB Machines

Frank Sergeant

copyright © 2013-2014 Frank Sergeant

all rights reserved

published by Nepo Press (http://nepotism.net)

5th Edition, May, 2014

(formatted May 16, 2014 at 11:32 AM)

cover image credits:

- movable type © Can Stock Photo Inc. / sax http://www.canstockphoto.com/movable-type-background-12140062.html

font credits

- The printed and PDF versions of this book are set in the Libertine font (http://linuxlibertine.org/) licensed under the Open Font License (http://scripts.sil.org/OFL).

- Noto Serif (from Google Fonts http://www.google.com/fonts/)
Apache License Version 2.0, http://www.apache.org/licenses/

- The Girl Next Door (from Google Fonts http://www.google.com/fonts/)
Copyright (c) 2010, Kimberly Geswein (kimberlygeswein.com) This Font Software is licensed under the SIL Open Font License, Version 1.1.

About This Book

Advanced Mobi and EPUB Machines is the third of the three user manuals for the Nepo Press web-based book formatting system. We might call the system Mobi Machine when making Mobi files, EPUB Machine when making EPUB files, and PDF Machine when making “camera-ready” PDF files for printing paperback books—the same system does all three—but we will usually refer to all three as just Mobi Machine.

This book is a supplement to the two beginning manuals. If your main focus is novels and eBooks, one of the beginning manuals will cover everything essential.

This third manual is for authors who, after reading one of the beginning books, want to go beyond the basic formatting or want to create a “camera-ready” PDF file for printing a paperback edition.

For self-publishers, this system hits the sweet spot with the best combination of high quality, low cost, ease of use, and flexibility.

What do you need? You need a computer with a web browser, a word processor or text editor, an internet connection, and a Nepo Press book account at nepotism.net/formatting (you can start with a free trial account). You don’t need to install any software. Your same manuscript will work for Mobi files, EPUB files, and PDF files, giving you “one-stop” formatting with nearly instant turn-around. Format your books on your schedule, not someone else’s. No limit to the number of revisions, so fixing typos or changing your list of “Other Books by This Author” can be done whenever you wish.

If you are already using the Nepo Press service, or planning to use it, this is the “missing manual” for when you want to go beyond the basic formatting or create printed books from your same manuscript.

Contents

- About This Book

- Introduction

- Part One - Advanced Formatting

- Headings and the Table of Contents

- Paragraph Indentation

- Block Tags, Literals, and Quotations

- Images

- Comments and Notes

- Drop Caps

- Small Caps

- Special Characters

- Time and Date Stamps

- Lists

- Links

- Additional Boilerplate

- Font Size, Subscripts, and Superscripts

- Style Sheets

- Custom Fonts

- Custom Classes

- HTML Snippets

- EPUB Validation

- Only eBooks versus PDF

- Templates

- Part Two - How to Create a Camera-ready PDF

- Introduction

- Generate Mobi and EPUB Files First

- The Minimum

- Front Matter versus Main Matter

- Limitations

- Running Headings

- Page and Book Size

- Font and Font Size

- Proof versus Final

- Even versus Odd Pages

- TOC Levels

- Lines That Are Too Long

- Line Breaks and Hyphenation

- Page Breaks

- Automatic Title Page

- Only PDF

- Page Numbers in the TOC

- PDF Summary

- Appendix

- List of Tags

- Text Editors

- Mac OS X Basics

- Linux Basics

- References

- About the Author

Introduction

This book is a supplement to the beginning books:

- Mobi Machine (Your Kindle Formatting Butler)

- EPUB Machine (Your EPUB Formatting Butler)

You need to read at least one of them before starting on this book.

The beginning books cover all the essentials for making eBooks for the typical novel.

This book extends the basic eBook formatting information by discussing additional tags that might be helpful in certain circumstances.

It also includes the information needed to make “camera-ready” PDF files for use in publishing and selling printed books through CreateSpace (or other print-on-demand services) and Amazon.

The Sweet Spot

As an author, you have many choices when it comes to eBook (and PDF) formatting, but we think this system hits the sweet spot, balancing quality, cost, effort, convenience, turn-around time, and flexibility.

You could do it all yourself, working in raw HTML, but that is not nearly as pleasant or efficient.

You could pay for custom formatting, but this is a lot more expensive and there might be limits on the number of revisions you can make.

If you do either of the above, do you get higher quality? Not for the typical novel, and not unless you have specific and unusual requirements.

How about turn-around time? Even if you pay for custom formatting, do you work at your schedule or your formatter’s schedule? With the Nepo Press system, the turn-around time (the time between uploading your manuscript and being able to download the eBook or PDF) is typically less than one minute. You can format in the middle of the morning or the middle of the night, or whenever you are ready, weekends and holidays included. And, you can revise at any time, re-uploading to your book account and re-formatting as often as you like, to fix typos or change the front or end matter, etc.

Once you have tried this system, I don’t think you will ever want to do it any other way. That’s certainly the way I feel about it. I can work in raw HTML, but I prefer to let this system do all that for me—it’s a lot easier. Plus, the same manuscript works for both the eBooks and for the paperback book (through CreateSpace or other print-on-demand services).

Getting Started

Hopefully, you are already started. That is, you have read at least one of the beginning manuals and are now happily making either Mobi or EPUB eBooks or both.

If you haven’t read at least one of those manuals yet, please do so before continuing with this manual.

After starting to make eBooks, you might wish to exercise a little more control over the appearance of your eBooks—or you might want to make a “camera-ready” PDF for publishing and selling a printed book through CreateSpace and Amazon. That’s where this book comes in. It discusses the additional formatting tags and other customizing methods available to you—methods that might have been “too much information” for the beginner.

Take this book a chapter at a time. Skim to get an overview—not all the information will be needed by any one author or for any one book—then dive into the details that most interest you.

Part One
Advanced Formatting

The chapters in this Part discuss

- advanced tags (tags not mentioned in the beginning books)

- additional notes about other tags

- controlling the appearance of book elements with the style sheet

Many books, especially fiction, do not need any markup other than what was covered in the beginning books. So, you almost certainly will not need all the markup discussed in this Part.

Start by skimming these chapters to get an idea of what is possible, then zero in on specific chapters as you find a need for them.

Headings and the Table of Contents

Chapter headings

The basic chapter heading is simple:

* Chapter One

As shown above, on a line by itself (with a blank line above and below) type an asterisk followed by a space followed by the chapter title.

The asterisk must start in column one (at the left margin). It must be followed by one or more spaces.

Chapter headings can also start with two asterisks, like this:

** Chapter One

With one asterisk, a chapter heading is called a level-one heading. With two asterisks, a chapter heading is called a level-two heading.

In either case, by default, the heading will be listed in the table of contents.

If a book has a single level of chapters, then use level-one headings for all of them and do not use level-two headings at all.

If a book has a two-level hierarchy, i.e., parts with chapters below them, use level-one headings for the parts and use level-two headings for the chapters.

Both level-one and level-two headings will start on a new page in the formatted book.

All chapters could use level-one headings or they could use both level-one and two headings to create a hierarchy, such as in the following example that divides a novel into chapters within parts.

* Stormy Night
...
* Acknowledgments
...
* Introduction

* Part One

** Chapter 1
...
** Chapter 2
...
* Part Two

** Chapter 3
...
** Chapter 4
...

Subheadings

Heading levels three through six provide various levels of subheadings.

A level-three heading has three asterisks, a level-four heading has four asterisks, etc.

Unlike level-one and level-two headings, these subheadings will not force a new page and will not appear in the table of contents.

Splitting a heading over several lines

Suppose we have a chapter named “Chapter One - The Beginning”. That would look OK all on one line, which is how it would appear if we marked it like this

* Chapter One - The Beginning

However, we might prefer it to appear split across two lines (especially if it is long).

That is easy to achieve with the <break> tag. Just mark the heading this way

* Chapter One <break> The Beginning

It will appear as a heading split onto two lines at the beginning of the chapter. The Table of Contents listing will be a single line: “Chapter One The Beginning”.

We can write the heading on two lines but that won’t make any difference. It’s the <break> tag that causes it to appear on two lines.

To show the difference, here are two versions of level-three headings:

*** Subsection One
The Beginning

*** Subsection Two <break>
The Middle

and the following is how they would appear in the book:

Subsection One The Beginning

Subsection Two
The Middle

The Book’s Table of Contents

A table of contents (TOC) is a listing of Chapters (or Parts and Chapters). It is active in that a reader can click on an entry in the TOC and jump directly to that part of the book. It is generated automatically, by the <contents> tag, from the level-one and level-two headings, i.e., the chapters.

The first two heading levels will appear in the table of contents. The logical table of contents is always generated (also using the first two heading levels).

A table of contents is optional but generally recommended. It should go near the beginning of the book. We place a <contents> tag where we want it to appear. Mobi Machine will take care of everything else.

If we don’t want a table of contents, we just omit the <contents> tag. Note that some booksellers require a table of contents.

By default, the title of the table of contents will be “Table of Contents” and will be a level-one heading, but we can change the wording or the level, as shown below. Here are some ways to format the table of contents (just pick one of them):

<contents>
* <contents>
* <contents> Contents
** <contents>
** <contents> List of Chapters

Hand-crafted Table of Contents

It is also possible to create a table of contents or a sub-table of contents “by hand”. An example of this is shown in the Appendix where a sub-table of contents contains active links to individual sections of the appendix. This sub-TOC is created with <link...> and <target> tags, so the details of how to do this are shown in the Internal Links section.

Overriding Automatic TOC Entries

Imagine we want the chapter heading “The Missing Ugly Green and Purple Parrot” to be listed in the table of contents as “The Missing Parrot”. The solution is to provide two items of information. The first will appear at the beginning of the chapter and the second will appear in the table of contents.

* "The Missing Ugly Green
and Purple Parrot"  "The Missing Parrot"

Note the above title was written on two lines, although it could have been written entirely on a single line. Either way, it must be in a single paragraph. Remember, as always, the double quotation marks must be straight quotes, not curly quotes (although the formatting program attempts to correct for this automatically).

Supplying two items to a heading is useful whenever we want the listing in the TOC to be different from the title in the body of the book.

For example, we want a “chapter” that marks the book’s title page, thus it contains the name of the novel, like this

* Stormy Night

However, that title doesn’t make as much sense as a table of contents entry. So, we could write it this way

* "Stormy Night"   "Title Page"

The title page in the book will say “Stormy Night” like we want it to, while the entry in the table of contents will say “Title Page”.

However, even that would look a little strange. Normally, books do not list the title page in the table of contents. Instead, we would ordinarily write it as follows so that no entry for it would appear in the table of contents:

* "Stormy Night"   ""

Note in the above heading the two items of information. The first item is Stormy Night and the second item is empty. It is possible for either or both of the two items to be empty. For example, suppose we want no title to appear in the body of the book for the copyright page, but we still want “Copyright Page” listed in the TOC. Here is how:

*   ""   "Copyright Page"

The pair of quotes with no space between them forms an empty item.

Unless we have placed the copyright page in an unusual location (such as near the end of the book), we probably do not want to list it in the table of contents. Thus, we would usually write the copyright page heading as a completely blank heading:

*

This forces the copyright page to start on a new page but doesn’t put a title in the body of the book and doesn’t list it in the table of contents.

Although we don’t particularly recommend it, another use for a blank heading (perhaps a level-three or level-four heading) would be to indicate a scene change (as an alternative to the <scene> tag discussed in the beginning books). For example

... end of this scene.

****

Start of new scene ...

Images for Chapter Headings

Did you notice the silly image at the beginning of this chapter? It might look like a bunny rabbit with a slash drawn through it: No bunnies allowed! Here it is again:

This is the markup that placed it at the start of this chapter:

** Headings and the Table of Contents

<image> sillypattern30x30.jpg

Some novels display an image, a curlicue graphic of some sort, at the beginning of each chapter. Well, we can do it too.

We could use the same graphic for each chapter or we could use a custom graphic for each chapter.

Also, we could render the entire chapter title as a graphic. For example, suppose we used an image processing program to draw a fancy “Chapter 13” script with ivy growing all over it and saved it as “ivychapter13.jpg”. We could use it instead of a text heading like this:

* ""   "Chapter 13"

<image> ivychapter13.jpg

Note the two heading items. The first ("") is empty, so no regular heading will appear in the body of the book (just the image). The second ("Chapter 13") is how the chapter will be listed in the table of contents.

Paragraph Indentation

As mentioned in the Mobi and EPUB manuals, the indentation of the first line of each paragraph follows the convention for fiction:

- paragraphs that start a chapter or section or that follow a break: first lines are not indented

- paragraphs that follow another paragraph: first lines are indented

In fiction, the convention is no vertical space between paragraphs, thus the first line indentation is used to separate paragraphs. However, Mobi Machine still adds a little vertical space between paragraphs in the HTML version. We can eliminate this vertical space in the HTML or we can add some to the Mobi and EPUB versions by customizing the style sheets as described the Stylesheets chapter.

In non-fiction, the convention is to use vertical space to separate paragraphs and not to indent the first lines of paragraphs, but generally the fiction convention will still look OK. If we do wish to change it, we can do so for the HTML, Mobi, and EPUB versions by customizing the stylesheets.

If we need to change the first line indentation for just a single paragraph, we can do so with the <indent> or <noindent> tags.

For example, to force a first line indent for a paragraph following an <image> tag, add an <indent> tag like this:

<image> author.jpg

<indent>

The author is clearly photogenic.

Similarly, the <noindent> tag would prevent the following paragraph from having its first line indented.

Block Tags, Literals, and Quotations

Non-block tags

Some tags, the most often used tags, appear on a line by themselves, not within a paragraph. Alternatively, we could say that the tag forms its own paragraph. Such tags must start at the left margin. The most common example is a heading tag. Other examples would be the <scene> and <image> tags.

These tags form their own paragraphs in that they are separated above and below by blank lines. They are usually written on a single line, such as

<image> author.jpg  "The author at the keyboard"

or

* Chapter 7 - The Pendulum

but the tags can also be written across two or more lines (if we are using a text editor), such as

<image> author.jpg
"The author at the keyboard"

* Chapter 7 -
The Pendulum

however the following would be bad

* Chapter 7 - The Pendulum
<image> author.jpg

because, without a blank line to separate them, the <image> tag would look like part of the chapter heading. Actually, the formatting program may be smart enough to handle the above example, but why take a chance? Leave a blank line before and after such headings and tags.

Here is a more extreme example:

* The Moose
When I first saw the moose through
the mist, I thought I was imagining it.

Because of the missing blank line, the above example would produce a very long title (17 words), with no first paragraph; not what was intended at all.

Block Tags

Other tags also start at the beginning of a line but must be used in pairs to delineate a block of text, for example, the <quote> and <box> tags described in the beginning books.

These sorts of block tags have an opening tag (such as <quote>) and a closing tag (such as </quote>). Each must begin at the left margin, on a line by itself. They cannot be used within a paragraph.

Both box blocks and quote blocks will have their paragraphs wrapped to fit the eReader. This wrapping is independent of where the lines break in the manuscript, unless we add <break> tags.

Literal blocks and in-line literals

Sometimes, especially in non-fiction, we might want the formatting to be more fixed for short sections, with leading white space and line breaks respected. For this purpose, a literal block is available. This sort of block is marked by a colon in the first column of each line. In such a block, what we write will appear literally. That is, no markup will be applied to it. Also, it will be set in a mono-space font and have a box drawn around it. For example,

: How to use pairs of asterisks
:  *this* is in italics
:  **this** is  bold
:  ***this*** is overdoing it

Above is the sort of markup used throughout this book to show examples. (An example block like the one shown above is usually only practical with a text editor. In a pinch, in a word processor, we could use a combination of <ex> and <break> and <box> tags instead.)

Unlike most types of blocks, the literal block is marked with the leading colons, rather than with a pair of tags.

Like the box block, the literal block will have a border drawn around it, although whether the border is visible or not depends upon the particular eReader.

Occasionally, it might be handy to mark a literal section within a paragraph to prevent the rendering of any markup or just to force the font to mono-space. That is done with the <ex> tags. (<ex> stands for “example”.)

This paragraph will
have <ex>some words</ex>
in mono-space font

and will look like

This paragraph will have some words in mono-space font

Quotations

Mobi Machine provides two main methods for displaying quotations.

Small Quotes

The first is the <smallquote> tag discussed in the beginning books. For example,

<smallquote> "Experience keeps a
dear school,<break> but fools will
learn in no other" "--- Franklin"

would appear as

Experience keeps a dear school,
but fools will learn in no other — Franklin

The quotation can be as long as we wish, but this display method usually works best for short quotations, the kind that often appear at the start of chapters (epigraphs).

Quote Blocks

The other method is to use quote blocks, like this:

<quote>

first paragraph ...

second paragraph ...

etc. ...

</quote>

There are four sets of quote tags:

- <quote>

- <quotei>

- <quotation>

- <quotationi>

These are handy for longer quotations and they can handle multiple paragraphs. They use wider margins (shorter lines). They differ as to the margin size and whether they use italics.

When in doubt as to which of the four to use, try them all out to see which suits you best. (Copy the section several times, using <quote> and </quote> tags around the first, <quotei> and </quotei> tags around the second, etc. After looking at them on an eReader or in a PDF, remove all except the one that looks best.)

Images

The beginning books showed the simple ways of using the <image> tag, such as

<image> myphoto.jpg

<image> "frank.jpg"  "the author"

<image> "thinker.jpg" "The Thinker" "Rodin"

where we must give the file name, but the caption and the attribution are optional.

There are two other optional items we can use on an image tag: width and height (in pixels).

For example,

<image>  "frank6.jpg"
"The author at play"
"photo by Newman Studios"
"600" "800"

The items must appear in the specified order. To skip an item, put in an empty item (a pair of double quotes) as a place holder. The above example would be written as follows to leave out the credit, yet still include the width and height:

<image>  "frank6.jpg"
"The author at play"
""
"600" "800"

The image tag may be written entirely on a single line or split across several lines (but must be in a single paragraph).

A comment may be placed in the manuscript as a reminder of the order of the items, like this

# <image> file
#   caption
#   credit
#   X Y

<image>  "photo.jpg"
"The Author"
"Silvia"
"600" "800"

The comment will not show up in the book.

Comments and Notes

Comments (lines beginning with a pound sign) can be used throughout the manuscript to make notes—notes that will not appear in the eBook or PDF.

However, sometimes, when working on a book, we might want to include notes that do appear in the book, so that we will see them as we proofread on an eReader or in a web browser. For this, a “FIXME” is handy as it is easy to search for:

FIXME above paragraph needs work

or

Later he moved to XXX, Ohio.
(FIXME -- what is the capital of Ohio?)

An alternative or addition is to use square brackets like this:

Later he moved to XXX, Ohio.
[what is the capital of Ohio?]

To make these stand out better, the default style sheet displays “FIXME” in red and displays the square brackets and their contents in green. Of course, the color coding is more useful in a web browser or on a color eReader, rather than on a grayscale eReader.

If we used square brackets that should appear in the finished book, we would need to adjust the style sheet to turn off the green. The Style Sheets chapter shows how.

Drop Caps

The beginning books covered the basics of drop caps but barely mentioned the <dc> tags.

By default, the first character of the first paragraph of each chapter will be set as a “drop cap”, but only if it is an ordinary letter or number (not punctuation, etc.).

We can turn this off with

<dropcaps> off

and back on with

<dropcaps> on

In addition, we can apply drop caps manually with the <dc> tags.

Suppose we wish to exclude the double quote mark and include the first two characters of “nobody”. We could do it manually like this

<dropcaps> off

"<dc>NO</dc>body knows the trouble
I've seen."

<dropcaps> on

and it would look like this:

“NObody knows the trouble I’ve seen.”

Not every eReader will necessarily render drop caps the same way.

If the first word of a chapter is dialog, such as

* Chapter One

"Hand me that beer," said Bobby.

then drop caps will not be applied automatically (because the first character is not a letter or number).

If this suits us, no problem. If it doesn’t suit us, here are some alternatives to consider:

- Don’t start the chapter with dialog:

* Chapter One

Bobby plopped down in his easy chair
and said, "I'm tired."

- Omit the beginning quote mark, letting the reader guess it is dialog based on context and the presence of the ending quote mark. I rather like this, but note that due to an odd number of double quote marks, we must use the <rdquo> tag to force a right double quote mark. (See the Special Characters chapter for more information.)

* Chapter One

Hand me that beer,<rdquo> said Bobby.

- The general solution is to turn off drop caps temporarily, just for that chapter, and then mark any drop caps manually. Here is an example using the <dc> tags to apply the drop cap formatting to the “H” while the asterisks apply italics to the rest of the word.

<dropcaps> off

"<dc>H</dc>*and* me that
beer, please," said Bobby.

<dropcaps> on

which would look like this (which may or may not suit you in an eBook but probably wouldn’t suit anyone in a PDF):

“Hand me that beer, please,” said Bobby.

The drop cap is not limited to a single character, although that is most common. For example,

<dc>NOW</dc> is the time

would set three characters as drop caps.

A quick way to turn off drop caps for, say, the title page or copyright page, is to put a subheading of some sort before any other text. Even a blank subheading will work. For example:

*

*****

copyright <copy> 2012 Nepo Press
...

or even

*

*** copyright <copy> 2012 Nepo Press
...

The exact styling of the drop caps in the eBooks is controlled by the style sheet. Feel free to change it as described in the Style Sheets chapter. Here is the snippet from style.css:

span.dropcaps {
font-size: 160%;
font-weight: bold;
}

Small Caps

notice that this first paragraph of this chapter did not begin with a drop cap. Instead, it began with the first three words set in small caps.

Setting the first three or four words of a chapter in small caps is a common alternative. The <sc> and </sc> tags are used the same way as the <dc> and </dc> tags.

Here is how the first paragraph of this chapter was marked up:

<sc>notice that this</sc> first
paragraph of this chapter
did *not* begin with a drop cap.
Instead, it began with the first
three words set in small caps.

Just as with drop caps, the exact styling is controlled by the style sheet, which we are free to customize. Here is the snippet from style.css:

span.smallcaps {
font-variant: small-caps;
}

Here is how we could change it to make the small caps appear in green (in full-color eReaders):

span.smallcaps {
font-variant: small-caps;
color: green;
}

Special Characters

Mobi Machine provides several tags to represent special characters.

- <copy> stands for the copyright symbol ©

- <reg> stands for the registered trademark symbol ®

- <trade> stands for the trademark symbol ™

- <ldquo> stands for left double curly quote mark (“)

- <rdquo> stands for right double curly quote mark (”)

- <nbsp> stands for a non-breakable space

If we need other special characters to appear in the book, characters that are not available from the keyboard or from the text editor’s menu, we can insert them using a numeric format (called HTML Special Entity Codes).

See the following site or other web resources for a list of such characters and their numeric equivalents.

- http://en.wikipedia.org/wiki/List_of_XML_and_HTML_character_entity_references

Suppose we would like to use the single “¾” character rather than writing the three characters “3/4”.

When we look for that symbol on the web, we see that its decimal numeric code is 190. So, we just write that in the manuscript like this:

I prefer to use <#190> cups
of rice per quart of water.

# Note to myself: 190 is the
# numeric code for the 3/4 symbol.

Then, it will print in the book as

I prefer to use ¾ cups of rice per quart of water.

Of course, if the text editor or word processor allows the entry of special characters directly, then we don’t need to use the numeric codes as described above.

Macros

If we need to use a few numeric codes often in the manuscript, we might want to define new tags for them with the <define> tag.

Let’s say we want to use the ¾ character (numeric code 190) and the double-dagger character ‡ (numeric code 8225) within the manuscript. We could define new tags named <3/4> and <dag> and then use those tags directly, like this

<define> "<3/4>"  "<#190>"
<define> "<dag>"  "<#8225>"
...
<dag> When I cook rice, I use <3/4> cups
of water <dag>.

and it will look like this

‡ When I cook rice, I use ¾ cups of water ‡.

The tags we create with the <define> tag just perform simple substitution.

Another use, besides naming special characters, would be to set up a shorthand for a longer word or phrase. Suppose “The University of Notre Dame” appeared many times in the novel and we don’t want to type it each time. We could define the tag <U> like this

<define> "<U>" "The University of Notre Dame"
...
I attended <U> in 1996

and it would look like this:

I attended The University of Notre Dame in 1996

Time and Date Stamps

Mobi Machine provides tags to insert the date and time the manuscript was formatted.

- <date> inserts the date

- <time> inserts the time

For example, as we are working on the manuscript, and possibly printing hard-copies to make proofreading easier, it might be useful to see a date and time so we can tell which version we are looking at. We could put something like this on the title page or the copyright page:

formatted on <date> at <time>

Note, when used in this fashion, the <date> tag must not start at the left margin. If the <date> tag starts at the left margin (as described in the Additional Boilerplate chapter), it is used for a different purpose—for the purpose of setting the date meta data (in case we don’t want to use the default date for some reason).

Lists

A list item is indicated by a hyphen. The hyphen should not start at the left margin. Indent it by at least one space, then follow the hyphen by at least one space.

Nested lists are OK. The indentation indicates the nesting. Keep the list items lined up as shown below. These are called “unordered” lists (because they do not have numbers, unless we add the numbers).

My favorite types of wine are

- red
- white

The next example shows a nested list.

My schedule tomorrow looks like this:

- Morning
- 10am    --- arrive at the office
- 11am    --- take a nap
- 12 noon --- break for lunch
- Afternoon
- 2pm     --- return from lunch
- 2:30pm  --- schedule a golf game
- 3pm     --- leave for the day

Note that lists must be separated above and below by blank lines but there must not be any blank lines within the list. Practically speaking, this means we must use a text editor instead of a word processor if we wish to use nested lists.

A list item can span multiple lines as long as it starts properly with a hyphen. Here’s an example:

- Morning is
not my favorite time
of the day
because:
- it is early
- it is too bright

and it would be rendered like this

- Morning is not my favorite time of the day because:

- it is early

- it is too bright

We can use a double colon to change to a “definition list” style. Such a list has two parts:

- the term

- the definition

The double colon separates the term from the definition, as shown below:

Three commonly used terms are

- up :: a direction toward the sky
- down :: a different direction
- elephant :: a large gray mammal

It would look like this

Three commonly used terms are

up

a direction toward the sky

down

a different direction

elephant

a large gray mammal

Not all eReaders necessarily render lists the same way. For example, some eReaders that support ordinary nested lists, may not support nested definition lists. If we try to nest them, Mobi Machine currently displays some warning messages when generating a Mobi file. (The Mobi file will still be created with the nested lists, but keep in mind the nested lists may not display properly on all Kindles.)

Links

In addition to the table of contents links, which are created automatically, we can create two types of links explicitly:

- internal links

- external links

Internal Links

An example of internal links is the Table of Contents. Those links are generated automatically by Mobi Machine. As with any internal link, to jump to a particular chapter from the Table of Contents, just click on the link.

Also, we can add our own internal links. This is not very common in fiction, but it might come in handy for a non-fiction book such as this one.

Since the destination is within the same book, this type of link is called an internal link. (It is also possible to link to a destination outside of the book, as discussed in the external links section).

Internal links let the reader jump directly to another part of the book. This is similar to how links work in a web browser. When the reader clicks on a link, the eReader jumps to a different section of the book. Then, to go back, the reader presses the eReader’s back button. Here is a link to the Headings and the Table of Contents chapter. Note that the link is underlined. If we arrow down to that link (on eReaders that have arrow keys), the cursor typically changes to a hand symbol. Then, click on the link to make the actual jump. Then, click on the back button to return.

The exact interface varies from eReader to eReader. On some, we take a link by pressing the center button of a 5-way controller. On eReaders with a touch interface, we would simply touch the link.

We were able to jump to that chapter because it was marked as a target with the <target> tag like this:

<target> "headings"

** Headings and the Table of Contents

Then, here in this chapter, we linked to it by using the <link...> tag like this:

Here is a link to the <link "Headings
and the Table of Contents" "headings">
chapter.  Note that ...

Internal links involve two tags:

- <target>

- <link...>

The place we click is the link and the place the link jumps to (the destination) is the target. Only headings can be used as targets. Give the target a distinctive name, then refer to that exact name in the link.

For example, if Chapter Two is to be the target, we would insert a <target> tag on a line before the Chapter Two heading, like this:

<target> ch2

* Chapter Two - Napoleon's Revenge

Keep the target name simple. “ch2” is good. Don’t use any spaces in the target name. Make the target name at least somewhat memorable—we’ll need to use it when we create the link.

Then, later in the book (or earlier in the book—it doesn’t matter), we can create a link to chapter two like this:

See more in <link "Chapter Two" "ch2">.

The link tag has two items of information, each item is enclosed in double quotes. (As covered in the beginning books these must be straight quotes.) The first item of information is the text that will appear underlined in the book. The second item of information is the target name. In the above example, the text “Chapter Two” would be underlined to indicate it is a link.

Put the target tag at the start of a line, on a line by itself.

Targets are not limited to major headings. We can link to any heading, even an empty heading. So, if there is no heading where we would like to put a target, just insert a blank heading, perhaps a level-four or level-six heading. Here is another example:

<target> "elephants"

****

(Boring discussion of the history of elephants.)

As I showed <link "in a previous chapter"
"elephants"> the subject of elephants can
be quite boring.

Remember, a target refers to the immediately following heading.

As mentioned in the table of contents section, it is possible to hand craft a table of contents. Here is how we did it for the Appendix:

* Appendix

The following sections include
supplemental material that
may be of use in some cases.

- <link "List of Tags" "tags">
- <link "Text Editors" "texteditors">
- <link "Mac OS X Basics" "macbasics">
- <link "Linux Basics" "linuxbasics">

The <link...> tags are shown above. To make it all work, we also needed to add <target> tags above each of the destination headings, as shown below:

<target> "tags"
* List of Tags
...
<target> "texteditors"
* Text Editors
...
<target> "macbasics"
* Mac OS X Basics
...
<target> "linuxbasics"
* Linux Basics

The main limitation is that a hand-crafted table of contents won’t show page numbers in the PDF, whereas the table of contents generated automatically by the <contents> tag will.

External Links

An external link uses the <url...> tag. It is similar to the <link...> tag except it jumps to somewhere other than within the book. This points the reader to additional material on the web. A common use in both fiction and non-fiction books is to link to the author’s web site or to the author’s additional books on Amazon, Barnes & Noble, Apple, Kobo, etc.

Here are some examples:

To be notified of updates to this
book, please visit my web site
at <url "http://nepotism.net"
"http://nepotism.net">
where you can sign-up for my
once-a-decade newsletter.

The <url...> tag includes two quoted items. The first is what appears in the book (underlined) and the second is the actual web destination. In the above example, both were identical. When they are the same, we can just list the information once, e.g.,

... <url "http://nepotism.net/videos">

When the user clicks on the link, the eReader’s web browser (if it has one) will visit that web page.

There are several reasons why we might want to provide two items:

- to make the sentence read more smoothly, such as

... visit my <url "web site"
"http://nepotism.net/videos"> where ...

- to spare the reader from having to see a miserably long web address (this is essentially the same as the previous reason)

As a special case, for simple web addresses, we can create an external link without using any tags at all. Just write the full url like the following examples.

1 at http://nepotism.net/videos.
2 See http://nepotism.net/formatting, for more
3 (https://nepotism.net/downloads)
4 <https://nepotism.net/about>
5 https://nepotism.net

and they will look like this:

1 at http://nepotism.net/videos.
2 See http://nepotism.net/formatting, for more
3 (https://nepotism.net/downloads)
4 <https://nepotism.net/about>
5 https://nepotism.net

Dead Links

A dead link is a link that goes nowhere when we click it.

A dead internal link is caused by the destination name not matching a <target> tag’s name. A typo can cause this or we might have switched the order of the items in the <link...> tag.

The following is bad because the link’s items are in the wrong order:

<target> cats
* Big Cats of Africa
...
See <link "cats" "the big cats chapter">

Instead, it should have been:

<target> cats
* Big Cats of Africa
...
See <link "the big cats chapter" "cats">

The following is bad because, in the link tag, the target name is (mis)spelled as “ctas” instead of “cats”.

<target> cats
* Big Cats of Africa
...
See <link "the big cats chapter" "ctas">

Additional Boilerplate

The beginning books covered the basic boilerplate tags

- <publisher>

- <cover>

Certain tags provide “meta data”. This is information that the eReader might use or display in some fashion, but which does not necessarily appear directly in the text of the book.

Examples of meta data would be the author and title of the book, which are set up automatically by your Nepo Press book account (so there is no need for <author> or <title> tags). The author and title meta data are used by the eReader to display the author’s name and title within the eReader’s list of books, and to sort that list properly.

Mobi Machine will set most of these tags to reasonable defaults, so we do not need to use them directly. If they apply, we should set the <publisher> and ISBN tags.

If the book has an ISBN, set either or both of the <isbn13> and <isbn10> tags. The <date> and <datecopyrighted> and <modified> tags will default to the current date (the date the Mobi or EPUB file was created) if we omit them.

Here is an extensive example with fake values:

<cover>     stormy.jpg
<publisher> Nepo Press
<isbn13> 978-3-16-148410-0
<isbn10> 817525766-0
<creator>   Sergeant, Frank
<modified>  2012-06-09T21:24:50Z
<date>      2012-06-09
<datecopyrighted>  2012
<uuid> f0b332b7-d7c4-440b-9e14-0b47b1bb7610

Each of the boilerplate tags should be on a line by itself. Although we recommend the rule of putting each tag into its own paragraph (separating tags with one or more blank lines), as this gives a consistent rule for the entire manuscript, the blank lines can be omitted between boilerplate tags as shown in the above example.

For most places we can publish an eBook, an ISBN is not necessary. If we do use an ISBN, it should be one acquired specifically for the eBook. That is, do not reuse a printed book’s ISBN for an eBook or vice versa.

Omit the ISBN tags unless the eBook has an ISBN. Although both the <isbn13> and <isbn10> tags are available, ordinarily we would use only the <isbn13> tag. If we have a 10-digit ISBN (unlikely), we would go to our ISBN supplier and have it converted to a 13-digit ISBN (see http://www.isbn.org/converterpub.asp).

Every eBook should have a unique identifier. If we don’t want to use the one generated automatically, the <uuid> tag lets us supply our own unique identifier. Normally, we would not do this.

If the <uuid> tag is omitted, Mobi Machine generates the unique identifier for the book automatically, and saves it in the book directory in a file with a .uuid extension.

Mobi Machine reuses this identifier each time it formats the eBook.

The <modified> tag provides a last-modified date and time in the format CCYY-MM-DDThh:mm:ssZ (the Z indicates UTC). Use this same format to set this explicitly. As an example, 2012-06-09T21:24:50Z means June 9, 2012 at not quite half-past 9 p.m. in Greenwich, England.

There are two uses for the <date> tag. When used at the left margin, it sets the “meta data” date as described above.

If the <date> tag is used anywhere else (that is, not starting at the left margin), it will be replaced by the date the manuscript was formatted. Similarly, the <time> tag can be used within a paragraph to insert the time the manuscript was formatted.

For example, we could put a line like the following on the copyright page (or elsewhere):

(formatted on <date> at <time>)

Font Size, Subscripts,
and Superscripts

Generally, for an eBook, we should not try to set a font size. Leave it up the eReader’s default and the human reader’s preferences.

However, for short sections of text, it might be convenient to be able to ask for a larger or smaller font.

The big (<big> </big>) tags can be used within a paragraph to make text larger than normal.

Similarly, the small (<small> </small>) tags make the text smaller.

Here is an example:

This is <big>bigger</big> and
this is <small>smaller</small>.

and it would look like this:

This is bigger and this is smaller.

The subscript and superscript tags raise or lower text within a line, like this

r<sup>2</sup> = 3X<sub>1</sub> + 2X<sub>2</sub>

to produce

r^2 = 3X_1 + 2X_2

Of course, if we need to write a lot of math expressions, this is the hard way to do it. Instead, we would use some other program to generate the figures as images, then include them in the manuscript with the <image> tag.

Style Sheets

A style sheet controls the overall style for the eBooks and HTML (not the PDF). Mobi Machine supplies a default style sheet named style.css for the eBooks and htmlstyle.css for the HTML. We can override the default by supplying our own style sheets.

Most authors will be happy with the default and will not need to create custom style sheets.

When no style sheet named style.css is present, Mobi Machine creates it automatically. Ditto for htmlstyle.css.

We are free to edit style.css to customize it. To do this, we first download style.css and rename it to, e.g., custom.css, edit it, then upload custom.css to the book account. To use a custom style sheet for the HTML, download htmlstyle.css, rename it to customhtml.css, edit it, and upload it to the book account.

Do not edit the style sheets in a word processor. Use a text editor. We have a video showing how to do this at

- http://www.youtube.com/user/nepopress

- http://nepotism.net/videos

To tell Mobi Machine to use the new style sheets, rather than the ones named style.css and htmlstyle.css, use the style tags to specify the custom style sheet names like this:

<style> custom.css

<htmlstyle> customhtml.css

A single style sheet applies to the entire manuscript, so use at most a single <style> tag and a single <htmlstyle> tag in the manuscript. Put them near the top of the manuscript with the other boilerplate tags.

Omit the style tags altogether to use the default style sheets.

Why would we want to change the style sheet? Let’s take a simple example. Suppose we don’t like how the horizontal rule looks. Here is the default style applied to horizontal rules:

hr { width: 50%}

If we want a wider rule or a narrower rule, we could find that line in the style sheet and change it to one of the following

hr { width: 75%}

or

hr { width: 25%}

We could make other changes such as altering the defaults for various heading levels (we could make level-five headings be the same size as level-four headings, but make them right justified and green) or change the size of drop caps.

In the default style sheet, square brackets (and their contents) are displayed in green. This is useful for temporary notes, as described in the Comments and Notes chapter. However, if we wish to use square brackets in the finished book, we need to change the style sheet from:

span.note {
color: green;
}

to

span.note {
/* color: green; */
}

Search the web to find out more about style sheets (search for “CSS” or “how to use an html style sheet”), or get one of the many books on the subject, such as HTML, XHTML, and CSS, Sixth Edition by Liz Castro.

See also

- the Custom Fonts chapter

- the Custom Classes chapter

for further information about editing the style sheet.

Custom Fonts

Do we want to use a custom font in an eBook? In general, no. The manufacturer of the eReader device has already done a lot of work to make the default fonts work well. We might be undoing that and worsening the “reader experience” if we meddle.

Also, setting a custom font affects only the eBooks, not the PDF.

On the other hand, if you feel strongly about it and want a specific font, Mobi Machine will let you do it for the eBooks. Maybe a good compromise would be to use your custom fonts sparingly, perhaps just for chapter titles, and leave the bulk of the text alone.

Also, just because we specify a font doesn’t mean the eReader will use it. We are at the mercy of the particular eReader model and the version of its software. For example, the Kindle Fire respects our font choice, but at least some of the grayscale Kindles require the reader to turn on a “Use Publisher Font” setting (e.g., press the “Aa” key on a Kindle Keyboard to find this setting), else the custom fonts will be ignored. We will have gone to the trouble of specifying custom fonts and many of our readers will never even know they exist.

Keep in mind the licensing requirements of the chosen font. Here are two places to look for fonts:

- http://www.dafont.com/

- Google Fonts (http://www.google.com/fonts/)

See http://code.google.com/p/googlefontdirectory/ for instructions on downloading the Google fonts.

To specify a custom font:

- upload the font file to the book account

- specify the name of the font file in a <font> tag in the manuscript

- add an @font-face declaration to the style sheet file

- indicate in the style sheet file which elements of the manuscript should use the custom font

For an example, we will use two fonts from http://www.google.com/fonts/. Find the fonts we want, then click on Add to Collection, then click on the down arrow. This will pop up a notice that we do not need to download the font to use it on our webpages. We do need to download it, though, to use it in our eBook. Click on the .zip file link to begin downloading a zip file containing all the fonts we have added to our collection. Save it to disk then unzip it. In addition to the font files themselves, we will have the license files. For example, for The Girl Next Door font, we would have these two files:

- OFL.txt

- TheGirlNextDoor.ttf

Copy the .ttf file to the manuscript directory and upload it to the Nepo Press book account, then open the license file (OFL.txt in this case) and copy the first part of it to the manuscript to give proper attribution. The copyright page of this book shows an example.

We will use two fonts for this example:

- NotoSerif-Regular.ttf

- TheGirlNextDoor.ttf

Be sure to copy them to the manuscript directory (and upload to the book account) and note their exact names. The file names must match the <font> tags exactly, as shown below.

In the manuscript, right after the boilerplate section, add <font> tags, like this

<publisher> Nepo Press
<cover> cover.jpg

<font> "NotoSerif-Regular.ttf"

<font> "TheGirlNextDoor.ttf"

Then, edit the style sheet file. We will need an @font-face section for each font. The information comes from the Google Fonts page for this font, or we can just specify them as shown below. (Liz Castro reports that for iBooks, we must specify font-weight and font-style, even though this shouldn’t be necessary.)

@font-face {
font-family: "NotoSerif-Regular";
font-weight: normal;
font-style: regular;
src: url(NotoSerif-Regular.ttf);
}

@font-face {
font-family: "TheGirlNextDoor";
font-weight: normal;
font-style: regular;
src: url(TheGirlNextDoor.ttf);
}

Then, still in the style sheet, specify which elements should use each font. In the following, we say that a level-six heading and the “girl” paragraph class will use the “TheGirlNextDoor” font and the “noto” paragraph class will use the “NotoSerif-Regular” font.

h6 {
font-family: "TheGirlNextDoor";
color: green;
}

p.girl {
font-family: "TheGirlNextDoor";
color: brown;
}

p.noto {
font-family: "NotoSerif-Regular";
color: purple;
}

To make the examples more interesting on full-color eReaders, we have also specified some colors.

Then, if we use a level-six heading in the manuscript, like this:

****** This is a dummy level-six heading

it will look like this (ignore example for PDFs):

This is a dummy level-six heading

Then, in the manuscript, we could mark certain paragraphs to be in the class “girl” or the class “noto”, like this:

<custompara> "noto"

This paragraph will use the
Noto Serif Regular font.

This is an example of
purple prose (on a color
eReader).

</custompara>

<custompara> "girl"

This paragraph will use
The Girl Next Door font.

And so will this one.

</custompara>

which, if the eReader supports custom fonts, would be rendered as follows (ignore example for PDFs):

This paragraph will use the Noto Serif Regular font.

This is an example of purple prose (on a color eReader).

This paragraph will use The Girl Next Door font.

And so will this one.

Some fonts will look bad on some eReaders—another reason to be cautious about using custom fonts.

See the Custom Classes chapter for more information about the <custompara> tag.

Keep in mind that there are two style sheets:

- the one that applies to the eBooks

- the one that applies to the HTML

We need to edit both of them if we want the custom fonts to appear in the eBooks and in the HTML.

Custom Classes

Consider the <quotei> and </quotei> tags. Paragraphs within those tags are set in italics and indented (wider margins).

How is that accomplished? Take a look at the style sheet file (style.css and/or htmlstyle.css). Within the style sheet, is a section that specifies how to display a paragraph whose class is quotei:

p.quotei {
text-indent: 0;
margin: 1em 1em 0.5em 1.5em;
padding: 0;
font-style: italic;
text-align: left;
}

The <quotei> tags mark paragraphs as having the quotei class, thus those paragraphs will have the text-indent, margins, etc., as specified above.

This is an example of a paragraph class that is built into the formatting program. However, if the margins (or other aspects) of that class don’t suit us, we can edit the style sheet to change them.

Further, we are not limited to that single paragraph class (and similar quote, quotation, and quotationi classes). We can set up as many different paragraph classes as we need by using the <custompara> tags in the manuscript and adding an appropriate section to the style sheet. (Caution: the <custompara> tags work for eBooks but are ignored for PDFs.)

An example of this was shown in the Custom Fonts chapter where we defined a “noto” class and set up the style sheet to use the NotoSerif-Regular font (and the color purple) for paragraphs of that class.

The <customdiv> tags are similar to the <custompara> tags. These allow us to have a division class as well as a paragraph class. Suppose we would like to wrap several paragraphs (of possibly different classes) in a box with a thick, dashed border. We could define a thickbox division class by adding the following to the style sheet:

div.thickbox {
page-break-inside: avoid;
border-style: dashed;
border-width: thick;
margin-left: 1%;
padding-left: 0.5%;
}

and then use it in the manuscript like this:

<customdiv> "thickbox"

This is a normal paragraph.

<custompara> "noto"

This is purple prose
(in a *noto* class
paragraph).

</custompara>

This is another normal
paragraph.

</customdiv>

and it would look like this:

This is a normal paragraph.

This is purple prose (in a noto class paragraph).

This is another normal paragraph.

HTML Snippets

The <html> tags let us apply snippets of HTML directly to the manuscript. Caution: these tags work only for the eBooks, not the PDF. Everything between the beginning (<html>) and ending (</html>) tags will be ignored when generating a PDF.

These tags can be used either as block tags (where the opening and closing tags each start at the beginning of a line by itself, with blank lines before and after), like this:

<html>

Strike out
<del>this</del>
and <del>that</del>.

</html>

or they can be used within a paragraph, like this:

Strike out
<html><del>this</del></html>
and <html><del>that</del></html>.

which would look like this (note that in a PDF the <html> and everything between them are missing):

Strike out this and that.

Here is another example (although, because the <sup> and <sub> tags are recognized directly by Mobi Machine as described earlier, we don’t really need the <html> tags in this case):

Water's symbol is
H<html><sub>2</sub></html>O
but x<html><sup>2</sup></html>
is 16 when x is 4.

which would be rendered like this (again, this won’t work in the PDF):

Water’s symbol is H_2O but x^2 is 16 when x is 4.

If we wanted to use an ordered (numbered) list (instead of an unordered list), we could do it this way:

<html>

<ol>
<li> get up </li>
<li> go to work </li>
<li> drink coffee </li>
<li> go home </li>
</ol>

</html>

and it would look like this (again, this won’t work in the PDF):

1. get up

2. go to work

3. drink coffee

4. go home

However, the style sheet controls whether the numbers will actually appear or not on some eReaders, but other eReaders may ignore the style sheet and show the numbers anyway.

Hopefully we won’t need to add very many HTML snippets; they tend to make the manuscript look cluttered, and they are ignored by the PDF.

EPUB Validation

When we make an EPUB file, EPUB Machine automatically runs the EpubCheck program on it to verify that it conforms to the EPUB 3 specification. This helps make sure that EPUB 3 eReaders will be able to read the eBook successfully and that booksellers will accept it on the first try.

Only eBooks versus PDF

Nobody wants to maintain separate copies of a manuscript, yet sometimes the version for eBooks needs to be slightly different from the one for the printed book. Or, the one for Mobi needs to be different from the one for EPUB.

Is there a way to say “use the following section only for the eBooks” or “use the following section only for the PDF”?

Yes.

There are four block tags that let us include a section conditionally:

- <onlyebooks>

- <onlymobi>

- <onlyepub>

- <onlypdf>

For example, suppose we have two copyright pages. One is for the printed book and has an ISBN issued by CreateSpace. The other, for the eBooks, has no ISBN. Here is how we could mark it in the manuscript:

<onlyebooks>

*

******

<align> center

copyright 2014 Frank Sergeant

all rights reserved

<align> default

</onlyebooks>

<onlypdf>

*

******

<align> center

copyright 2014 Frank Sergeant

all rights reserved

<isbn13> 978-3-16-148410-0

ISBN: 978-3-16-148410-0

<align> default

</onlypdf>

Note that if we turn something on within the conditional section, we should turn it back off within the same conditional section. Thus the two <align> tags.

The above example could be written more succinctly (since only the ISBN information differed) like this:

*

******

<align> center

copyright 2014 Frank Sergeant

all rights reserved

<align> default

<onlypdf>

<isbn13> 978-3-16-148410-0

ISBN: 978-3-16-148410-0

</onlypdf>

This facility is also often needed for the title page. A title page is created automatically for the PDF. If an explicit title page is included in the book, the eBooks would have the single (explicit) title page, but the PDF would have two title pages. This is not a problem and is exactly what we want sometimes. We see this often in printed books: an initial, fairly simple title page, followed by a title page with more detail.

Sometimes, though, we want to exclude the explicit title page from the PDF so that it will contain only the automatically generated title page. Here is how to do it:

<onlyebooks>

* "Stormy Night"  ""

***

Frank Sergeant

</onlyebooks>

Everything between <onlyebooks> tags will appear in both the Mobi and EPUB files but not the PDF file.

Everything between <onlypdf> tags will appear in the PDF file, but not the Mobi or EPUB files.

Everything between <onlymobi> tags will appear in the Mobi file, but not the EPUB or PDF files.

Everything between <onlyepub> tags will appear in the EPUB file, but not the Mobi or PDF files.

Templates

Once you are formatting your first manuscript successfully, it is easy to create a template for future, similar books. Just make a copy of your first manuscript, naming it something like noveltemplate.doc or noveltemplate.txt (depending on whether you use a word processor or a text editor). Then, edit the template to remove the bulk of the first book, leaving just the tags and perhaps the start of a chapter or two.

Then, when you are ready to start on a new novel, open the template and then save it under the new name. For example, if the new novel will be named Windy Day, open noveltemplate.doc and “save-as” windy.doc.

Also, the manuscript for the sample Nepo Press novel Sam Speedo (Bathing Suit Detective) can be used as a simple template:

- http://nepotism.net/formatting/

Also, a longer template (in several formats) is available at:

- http://nepotism.net/formatting/documentation.html

Part Two
How to Create a Camera-ready PDF

Introduction

The main use of the Nepo Press web-based formatting service is to produce Mobi and EPUB eBooks for Kindle, NOOK, iPad, etc.

However, once the eBook is finished, or even before, we might want to create a PDF version.

A PDF is handy for

- proofreading

- handing out to beta readers

- distributing directly as a PDF

- publishing as a printed book

Once we can produce a clean eBook, producing a PDF is as simple as clicking the PDF button on the book account page.

This is not just a PDF. It is a camera-ready PDF, suitable (once a few adjustments are made) for submitting to CreateSpace so we can make printed books in addition to eBooks. Of course, cameras aren’t used anymore; it’s all digital.

The goal of this section is to provide the key additional information needed to turn the eBook manuscript into a camera-ready PDF, once you are already producing clean eBooks.

If you are not already using the formatting service, don’t start here. Instead, start by producing Mobi and EPUB eBooks.

Once you are able to turn your manuscript into a Mobi or EPUB eBook, then you are ready for the extra details that apply to creating a PDF.

Generate Mobi and EPUB Files First

First, log into your book account at http://nepotism.net/login.html and make sure you can create a Mobi file and/or an EPUB file. Upload your text file if you haven’t done so already.

To create a Mobi file, click on the Mobi button. When it has finished processing, click on the mobireport.txt file to see if there are any errors or warnings to tend to.

To create an EPUB file, click on the EPUB button. When it has finished processing, click on the epubreport.txt file to see if there are any errors or warnings to tend to.

Then, view the results. The best way is to download the EPUB or Mobi file to your eReader or eReader app and look at it there. The easy way is to click on the HTML version and view it in your web browser.

Once you have a clean manuscript that works for Mobi and/or EPUB files, you are ready for the next step.

The Minimum

Once you can create a mobi file or an EPUB file without errors, the minimum you need to do to create a PDF file is simply to click on the PDF button on your book account page.

This produces a PDF file that you can download or view in your web browser.

It may be “camera ready” at this point but it is not quite ready to publish. You will need to do a little more than the minimum, as described in the next chapters.

Front Matter versus Main Matter

Our default styling is to use no page numbers for the front matter and Arabic numerals for the main matter.

To achieve this, you must indicate where the front matter ends and the main matter begins. Do this by adding a <mainmatter> tag at the appropriate place. A common place is after the various front matter (table of contents, acknowledgments, preface, dedication, whatever) and before the introduction or first chapter.

For example:

<contents>

<mainmatter>

* Introduction

The main use of the Nepo Press
web-based formatting service is
to ...

Note that pages prior to the introduction have no page numbers and the later pages use Arabic numerals.

Limitations

This web service is not quite “one size fits all”, but neither is it infinitely customizable. Certain things can be changed but not everything. Think of it as “semi custom”.

Not all of the formatting available to the eBooks will carry forward to the PDF. Aspects that don’t apply or that aren’t available are silently ignored, thus no tags need to be removed—the same manuscript will work for both the eBooks and the printed book.

Our goal is to produce a PDF that is suitable for publishing a typical novel. If your book is not a typical novel (or even if it is), then you can override a few choices, such as page size (and thus the book’s trim size) and font size. If that isn’t enough, then the web-based formatting might not be suitable for your printed book. Instead, your manuscript may need custom formatting.

Running Headings

The running headings are produced automatically at the top of the pages.

The odd-numbered pages (the right hand or recto pages) show the title of the book at the top. This cannot be changed. So, very long titles may cause a problem.

The even-numbered pages (the left hand or verso pages) show an uppercase version of the chapter title at the top. We do have some control here. If we create a chapter title like this:

* Lost in Dixie

or

* "Lost in Dixie"

that is, with a single item, then the body of the chapter and the entry in the table of contents (TOC) will both say Lost in Dixie, and the left-hand running heading will say LOST IN DIXIE.

If we override the TOC entry by supplying two items (note the two pairs of double quotation marks), like this:

* "Lost in Dixie" "Lost"

then the body of the chapter will say Lost in Dixie, the TOC entry will say Lost, and the even-page running heading will say LOST.

But, we have even more control. We can specify a third item (using three pairs of double quotation marks). Then, the first item will be used for the body of the chapter, the second item will be used for the TOC entry, and the third item will be used for the even-page running heading. For example:

* "Lost in Dixie" "Lost" "Lost"

Then the third item (Lost) will be used for the left-hand running heading, rather than the uppercase version (LOST).

If we don’t want the chapter title to appear in the running heading at all, we can provide an empty third item, such as one of the following:

* "Lost in Dixie" "Lost" ""

* "Lost in Dixie" "Lost in Dixie" ""

Page and Book Size

The PDF currently defaults to a size of 5.25 inches wide by 8 inches tall with a 0.76 inch inner margin and a 0.5 inch outer margin, and a 0.8 inch top margin and a 0.8 inch bottom margin. Thus, the PDF will be generated as if these tags were in the manuscript:

<width>   5.25
<height>  8
<inner>   0.76
<outer>   0.5
<top>     0.8
<bottom>  0.8

To override the defaults, just add one or more of those tags to the manuscript and change the value (in inches) to whatever you prefer. They can go anywhere in the manuscript, but the usual and best place to put them is near the beginning. For example, if we want a 6 inch by 9 inch book with wider margins, we could use these tags:

<width>   6
<height>  9
<inner>   1.2
<outer>   1

Font and Font Size

The PDF currently defaults to using 12-point Libertine (a replacement for Times Roman-like fonts). We have a choice of 10-point, 11-point, or 12-point. Here is how to specify the current defaults. If we leave these out of the manuscript, the defaults will be used, but we might want to add the tags to make the font and size choices clear:

<pdffont>  libertine
<fontsize> 12

Note, the <pdffont> tag is not the same as the <font> tag that can be used for Mobi and EPUB files. When creating Mobi and EPUB files, <pdffont> and <fontsize> tags are ignored. When creating a PDF file, the <font> tag is ignored. Thus, a single manuscript can serve for both eBooks and printed books.

To override the font size, use the <fontsize> tag, e.g.,

<fontsize> 11

Libertine is licensed under the Open Font License and an acknowledgment in the book is appropriate. See the copyright page of this book for an example.

We may offer more font choices in the future.

Proof versus Final

The final PDF is the one suitable for printing as a book. For example, this is the file we would submit to CreateSpace or other printer to produce printed books. It is set to print on 5.25x8 inch paper (or whatever trim size we select for our book with the <width> and <height> tags).

If we wish to print a copy on our home or office printer, it might not be convenient to use 5.25x8 inch paper. That’s why a proof PDF is available.

The proof PDF is similar to the final PDF, except it is designed to be printed on 8.5x11 inch paper (standard letter-size paper in the United States). If this is an inconvenient size for our foreign friends, please let us know and we might add some additional options, such as A4.

The proof PDF is easy to print on letter-size paper. The book page images are the same size in either case (such as 5.25x8), but with the proof PDF the book pages are printed in a visible frame centered within the 8.5x11 sheet of paper.

Just to the right of the PDF button are two small buttons labeled final and proof. Select the one you want (by default, final is selected) before clicking on the PDF button.

Even versus Odd Pages

All chapters (level-one and level-two) will begin on an odd-page (a right-hand page). This is generally what we want for a printed book. (It makes no difference in eBooks, viewing a single page at a time.)

However, there may be certain pages that we want to print on the next page regardless of whether it is odd or even. To force this to happen, use a completely empty chapter title. The common case is the copyright page. We probably want the title page to appear on an odd page with the copyright page immediately following.

To achieve this, give the copyright page a completely empty chapter heading like this:

*

<align> center

***

copyright 2013 Frank Sergeant

all rights reserved

<align> default

The key is the level-one heading (the single asterisk on a line by itself). This starts a new page, just like a chapter. However, because it is a completely blank heading, it starts on the very next available page whether odd or even. Note that the <align> center tag goes after the copyright page heading. This doesn’t matter for the eBooks, but is necessary for the PDF.

The level-three subheading is not necessary, but it provides a little extra vertical spacing and turns off the drop caps so copyright won’t have a large initial “C”.

Alternatively, for less vertical spacing, use a level-six subheading or use no subheading at all and add a <dropcaps> off tag.

The copyright page near the beginning of this book shows how it would look with <dropcaps> off and no subheading.

TOC Levels

By default, the first two heading levels will appear in the table of contents. We can change this with the <toclevels> tag. For example, if we want the first three levels to appear in the TOC, we could say:

<toclevels> 3

Note, the <toclevels> tag applies only to the PDF. It has no effect on the eBooks or HTML.

Lines That Are Too Long

Sometimes manual intervention is necessary to get lines to break where we want them to.

One common situation is a line containing a long url. There may not be a perfect place to break it. So, when we proofread the PDF, we might see a line extending into the margin. Somebody has to decide where to break that line.

The way we mark such a break is to use the <brk> tag. Note that this is similar to the <break> tag that forces a line break in Mobi and EPUB files.

These two tags (<brk> and <break>) are not the same tag. The <break> tag works the same for Mobi, EPUB, and PDF files.

The <brk> tag is ignored when making Mobi and EPUB files. For PDF files, it gives the magic clue needed by the formatting program.

For example, the manuscript might look like this:

The best place to learn
about eBook formatting is
http://nepotism.net/formatting.
It is the place to go for all
your eBook needs.

First note two things:

- The line breaks in the manuscript have nothing to do with where line breaks will occur when viewing the eBook in an eReader. Unless forced with a <break> tag, where the line breaks will fall depends upon the eReader settings such as screen width and font size. The author has no control over this.

- The line breaks in the manuscript have nothing to do with where line breaks will occur in the PDF file. The formatting program decides where the lines will break independent of where the lines break in the manuscript. Here, just as with an eReader, the <break> tag forces a line break. However, to fix lines-overflowing-into-the-margin problems, it is better to use the <brk> tag. This forces a line break in the PDF file without disturbing where the lines break in an eReader.

Let’s say that when we view the PDF of the above, a line starts with “formatting is” and continues into the margin by the time it finishes displaying the url. Something has to give. Where do we want to have the line break? We could add some words prior to the url and perhaps the lines would break better. Or, we could decide to break it after .net and before /formatting. We would simply add the <brk> tag like this:

The best place to learn
about eBook formatting is
http://nepotism.net<brk>/formatting.
It is the place to go for all
your eBook needs.

It is generally best to do this as one of the last steps in preparing the book for publication. If we edit the book further, after adding <brk> tags, we might need to adjust or remove them or add new ones in different places.

Line Breaks and Hyphenation

It may occasionally happen that a word is hyphenated in the wrong place. For example, “CreateSpace” should not be hyphenated like this:

CreateS-
pace

Or, perhaps we would rather a word never be hyphenated, such as someone’s name.

John-
ny

Perhaps “editorial” is being hyphenated as “edit-orial” but we would prefer it to be hyphenated as “editor-ial”.

We can specify our preferred hyphenation with the <hyphenation> tag. Just provide a list like this:

<hyphenation> create-space johnny
editor-ial

Case is ignored, so the hyphenation rules will apply equally to “CreateSpace” and “createspace”, to “Johnny” and “johnny”, etc. The above example says never hyphenate “johnny” but, if “CreateSpace” needs to hyphenated, break it between “Create” and “Space”, and if “editorial” needs to be hyphenated, break it between “editor” and “ial”.

Put the tag anywhere in the manuscript (near the top of the file is a good place). As usual, be sure a blank line precedes and follows it. Continue across as many lines as needed as long as they are all in the same paragraph, with a space between words.

For most words, the formatting program takes care of hyphenation automatically and correctly. Only words that aren’t hyphenated correctly need to be added to the <hyphenation> tag. (Don’t try to fix hyphenation problems by adding a hyphen directly in the text of the manuscript.)

The <hyphenation> tag is ignored for eBooks.

Page Breaks

Generally, page breaks are handled automatically.

If we need to force a page break, a new chapter (either a level-one or a level-two heading, even a blank level-one or level-two heading) will do it. For example, this is how we force the copyright page to start on a new page.

However, the above method also resets the running headings, which might not be what we want.

Instead, we can use the <newpage> tag. This should be used sparingly if at all, and usually as one of the final steps in preparing the book.

Suppose we start a scene with a date or location line but it happens to fall at the end of the page. We would prefer it to start at the top of the next page so it will be on the same page where the scene begins. Here is a way to do it:

end of previous scene

<newpage>

<align> center

<small>*Southampton, May, 1963*</small>

<align> default

I remember my first trip to England ...

The <newpage> tag applies to PDFs but is ignored for Mobi, EPUB, and HTML.

Automatic Title Page

A title page is created automatically for the PDF. The information (author and title) comes from the book account.

If you include an explicit title page, which you would for the Mobi and EPUB files, then the PDF will have two title pages. This is not necessarily a problem. Often the explicit title page will have slightly more detail.

<align> center

* "Stormy Night"  ""

*****

The Continuing Adventures of Bobby and Judy

***

Frank Sergeant

<align> default

On the other hand, sometimes we don’t want two title pages in the PDF, so we isolate the explicit title page so it will appear just in the eBooks (Mobi and EPUB).

We do that with the conditional tags as shown in the Only eBooks versus PDF chapter.

Only PDF

The previous chapter (Automatic Title Page) showed how to exclude a section from the PDF, but sometimes we wish to include something in the PDF that should not appear in the eBooks, such as an ISBN.

This is easily done using the <onlypdf> tags, as shown in the Only eBooks versus PDF chapter.

Page Numbers in the TOC

The table of contents is generated automatically using the chapter title and page number information from the previous PDF formatting run.

So, when you are ready to publish, spot check the page numbers and click on the PDF button an extra time if necessary.

PDF Summary

Here is a quick review of the most important points.

Before trying to create a PDF file, create a Mobi and/or EPUB file. This helps find any problems in the manuscript. Fix any errors or warnings mentioned in the report file (named mobireport.txt or epubreport.txt).

Once we have handled any errors, creating a PDF is as simple as clicking on the PDF button on the book account page.

We can proofread the PDF in an on-screen PDF viewer (view as “Dual, even pages on the left”) or we can print a copy.

When we create the PDF, we can choose either final or proof. The page image is the same. The proof is suitable for printing on letter-size paper, showing each book page in a visible frame. Either is OK for viewing on the screen.

Use final when ready to submit the PDF to CreateSpace or other book distributor or printer.

However, just because it produces a PDF file does not mean we are ready to publish. We should consider doing the following:

- Add a <mainmatter> tag to indicate where page numbers should begin.

- Use a blank level-one header wherever we need a new page that starts on the next available page, regardless of whether that page is odd or even.

- If we want something other than the default sizes, use the appropriate tags to override page width and height, inner, outer, top, bottom margins, and font size.

- In proofreading the PDF file, look especially for:

- running heading on even-numbered pages (chapter titles) that is too wide. Override by adding a third item to the chapter title.

- any line that extends into the margin. Add a <brk> tag to force a line break where needed.

- any word not hyphenated correctly. Correct by adding the offending word to the <hyphenation> tag.

- Before publishing, spot check the TOC page numbers. Format once more if necessary.

Appendix

The following sections include supplemental material that may be of use in some cases.

- List of Tags

- Text Editors

- Mac OS X Basics

- Linux Basics

List of Tags

This appendix contains a list of the Mobi Machine tags introduced (or expanded upon) in this book. Refer to the beginning books for other tags. For tags used in pairs, only the opening tag will be listed.

Each tag is linked to the main chapter or chapters that discuss it. Also, the eReader’s search facility can locate every occurrence of a specific tag.

- colon to mark a literal block

- <big> Font Size, Subscripts, and Superscripts

- <bottom> Page and Book Size

- <box> Block Tags

- <break> Splitting a heading over several lines, Block Tags

- <brk> Lines That Are Too Long

- <contents> The Book’s Table of Contents

- <copy> Special Characters

- <cover> Additional Boilerplate

- <creator> Additional Boilerplate

- <custompara> Custom Classes

- <customdiv> Custom Classes

- <date> Time and Date Stamps, Additional Boilerplate

- <datecopyrighted> Additional Boilerplate

- <dc> Drop Caps

- <define> Special Characters

- <dropcaps> Drop Caps

- <ex> Literal blocks and in-line literals

- <font> Custom Fonts

- <fontsize> Font and Font Size

- <height> Page and Book Size

- <html> HTML Snippets

- <htmlstyle> Style Sheets

- <hyphenation> Line Breaks and Hyphenation

- <image> Images

- <indent> Paragraph Indentation

- <inner> Page and Book Size

- <isbn10> Additional Boilerplate

- <isbn13> Additional Boilerplate

- <ldquo> Special Characters

- <link...> Internal Links

- <modified> Additional Boilerplate

- <nbsp> Special Characters

- <newpage> Page Breaks

- <#nnn> Special Characters

- <noindent> Paragraph Indentation

- <onlyebooks> Only eBooks versus PDF, Automatic Title Page

- <onlyepub> Only eBooks versus PDF

- <onlymobi> Only eBooks versus PDF

- <onlypdf> Only eBooks versus PDF, Only PDF

- <outer> Page and Book Size

- <pdffont> Font and Font Size

- <publisher> Additional Boilerplate

- <quotation> Quote Blocks, Block Tags

- <quotationi> Quote Blocks, Block Tags

- <quote> Quote Blocks, Block Tags

- <quotei> Quote Blocks, Block Tags

- <rdquo> Special Characters

- <reg> Special Characters

- <small> Font Size, Subscripts, and Superscripts

- <smallquote> Small Quotes

- <style> Style Sheets

- <sub> Font Size, Subscripts, and Superscripts, HTML Snippets

- <sup> Font Size, Subscripts, and Superscripts, HTML Snippets

- <target> Internal links

- <time> Time and Date Stamps, Additional Boilerplate

- <toclevels> TOC Levels

- <top> Page and Book Size

- <trade> Special Characters

- <url...> External Links

- <uuid> Additional Boilerplate

- <width> Page and Book Size

Text Editors

Efficiency, Comfort, and Health

The less friction between thinking and having those thoughts appear in your manuscript, the better.

This section won’t deal with how you create those thoughts, just with the mechanics of getting them into your manuscript.

There are three main areas that I believe can help:

environment

Are your desk, monitor, keyboard, chair, etc., set up correctly?

touch typing

Do you “hunt and peck” or do you type by touch?

text editor

Do you use a professional text editor or do you use a word processor (or a poor text editor)?

Environment

I don’t have strong opinions on the environment, except that it is probably important for efficiency, comfort, and health. The right keyboard at the right height; monitor at the right height and possibly eyeglasses so you don’t need to bend your neck at a bad angle. A chair (or stand-up desk) that doesn’t injure your back. That sort of thing.

Touch Typing

If you don’t touch type, learning to do so may give you the best bang for the buck. If you hunt and peck, it is hard to learn to touch type because you will type more slowly at first, and that is painful. You will be tempted to resort to your old ways.

Learning to touch type is a capital investment. Instead of money, it costs some up-front time. If you plan to write just one more paragraph, then there is no point in making the investment because it will never pay off. How many paragraphs do you plan to write in the future? Figure out your break-even point and give it a try.

The web is filled with touch-typing tutorials.

I think the trick to learning to type fast is this (and it is counter intuitive): go slowly. Type at a pace that is metronomically precise. Deliberately go slowly so the keystrokes keep an even rhythm. This means do not speed up on the easy keys and combinations. Instead, type slowly enough that the typing speed for each keypress is the same, while making sure you use the correct fingering (and without looking at the keyboard). If you do this, the speed will come. If you try to type fast, it is more difficult to train the fingers to do it correctly and you will put an unnecessarily low ceiling on your maximum typing speed.

If anyone tries this, I would be delighted to hear how it works out (frank@nepotism.net).

Text Editor

I’m going to give you my best advice here, even though I know it will not be popular.

I think a serious author using a word processor should switch to a text editor. And, not to just any text editor, switch to a professional text editor. By that, I mean one of the two outstanding text editors:

- Emacs

- vi

Both of these are free. Neither is exactly like a word processor, therefore both require an investment of time. This is the same problem as with learning to touch type. For a while, your productivity will be less than if you keep doing it the old way. But, there is a big payoff. Again, it is the question of how many paragraphs you expect to write during the rest of your career.

With either Emacs or vi, you will need to work through a tutorial or two. It will help to print out a quick reference card. Again, the web is filled with Emacs and vi tutorials.

I wish I remembered where I saw it, but I read a comment years ago by a technical writer working for Microsoft. She said her manager asked her how come she was so much more productive than the other technical writers (was she twice as productive or ten times as productive?—I forgot). Her answer was that she used the vi editor while the others used Microsoft Word.

I think the reason so many authors use a word processor is that they didn’t know any better when they started, and now inertia keeps them using what they are most familiar with. Certainly Microsoft and WordPerfect have not gone out of their way to encourage the use of anything else.

On Windows, Emacs is a bit difficult to install, but vi is very easy:

- http://www.vim.org

On a Mac, Emacs and vi are both installed by default, but the versions are probably out of date. Up-to-date versions are easy to install on a Mac:

- http://www.vim.org

- http://emacsformacosx.com/

On Linux, Emacs and vi are both installed or are very easy to install with the package manager.

If you are willing to give Emacs or vi a try, I think within a week you will be back up to your previous editing speed and will then continue to speed up until you are considerably more productive than with your word processor. Work through a tutorial or two. Watch some YouTube videos. It’s easy (except for the initial pain of going more slowly). Tip: Even though Emacs has a menu that you can work with the mouse, do not use it. Instead, use the keyboard exclusively. Both Emacs and vi have keyboard shortcuts for everything.

That’s my best advice regarding text editors. If you try it, please email me to let me know how it goes (frank@nepotism.net).

I used to recommend some alternative text editors for those who couldn’t bring themselves to try Emacs or vi, but I no longer do so. There are numerous text editors that are more efficient than using a word processor, and Google will lead you to them if you wish.

One immediate benefit of using a text editor is that you will no longer need the extra save-as-text step (because a text editor keeps your manuscript in plain text).

The next section explains the difference between a text editor and a word processor. The one after that explains how to convert your manuscript to plain text (hint: Mobi Machine can do this for you automatically).

Text Editors versus Word Processors

A word processor is a computer program that combines text editing with presentation, trying to show what the final printed result would look like. Such a program is often described as WYSIWYG, which stands for “what you see is what you get”.

Unfortunately, word processors have a number of costs associated with them.

They do their magic by inserting lots of hidden codes into your document.

Some people who use a word processor feel like they spend more time fighting with it, trying to trick it into doing what they want, than they spend writing their books.

Most of the time for authors, a word processor just gets in the way compared to a text editor.

A text editor, on the other hand, sticks to the task of letting you enter and edit text—visible text. It doesn’t hide anything from you. I might call it WYSIWRT (“what you see is what’s really there”).

A text editor is a smaller, faster program.

The professional (albeit free) text editors Emacs and vi have many facilities for improving the efficiency of entering text.

Convert Your Manuscript to Plain Text

To edit your manuscript in a text editor, you first need to convert the manuscript to plain text.

The “save-as” or “save-a-copy” step you do for Mobi Machine converts it to plain text, but that format is awkward to work with because, if you open it in a text editor, you will see a series of very long lines (one line per paragraph).

When the Mobi Machine runs, if it detects very long lines, it creates an additional copy of your manuscript with a name that starts with plain-text. For example, plain-text-stormynight.txt. That version of your manuscript is the one you want. Download it from your book account, rename it to, e.g., stormynight.txt, and use it thereafter with your text editor.

So there is really nothing much to do. If your manuscript is named stormy.doc, each time you run Mobi Machine, it automatically creates a plain text version named plain-text-stormy.txt. All you have to do is just rename that file from plain-text-stormy.txt to stormy.txt.

You can even do that renaming in your text editor. Fire up Emacs or vi. Open plain-text-stormy.txt then immediately save it as stormy.txt. Thereafter, just edit stormy.txt.

When using a text editor, there is no need for the extra save-as step needed with a .doc file, since stormy.txt is already a text file.

When you start a new book, just start it in the text editor instead of a word processor.

Formatting Differences
Between Text Editors and Word Processors

In a word processor, you typically organize things by paragraphs. You type and type without pressing the Enter key until you reach the end of a paragraph.

In a text editor, you typically organize things first by lines and then by paragraphs. At the end of each line, you press the Enter key. At the end of each paragraph, you press the Enter key at least twice. (Text editors often have a setting to type the line-ending Enter key for you automatically when the line is close to the length you have set.)

Mobi Machine expects lines, rather than paragraphs, to end in an end-of-line character and expects paragraphs to end in at least two end-of-line characters. The end-of-line character varies between operating systems, but just think of it as whatever character the Enter or Return key inserts.

If you use a word processor, when you do the temporary “save as” to produce a plain text version of your manuscript, that text file contains a single line per paragraph. This may be a very long line. Further, there may be only that single end-of-line character between paragraphs, although Mobi Machine expects to see at least two end-of-line characters between paragraphs.

Mobi Machine solves this problem by checking the line lengths of the text file before processing it. If it finds several very long lines, it assumes the text file was “saved as” a text file by a word processor. In this case, Mobi Machine doubles up every end-of-line prior to processing the file. It also creates a copy of that text file with the long lines wrapped to a more reasonable length. This copy is the file named something like plain-text-stormy.txt.

That way, regardless of whether the text file is an ordinary text file (with many end-of-lines in a paragraph but at least two between paragraphs) or is from a word processor (with only a single end-of-line between paragraphs), at processing time, there will indeed be at least two of them per paragraph, allowing paragraph breaks to be identified correctly.

Mobi Machine ignores extra end-of-lines (i.e., blank lines), so you can put in as many extra blank lines as you like between paragraphs, whether in a word processor or in a text editor.

Consider what this means for nested lists, for example.

Mobi Machine expects the entire list to be in a single paragraph. That is, the following would be a single list (with a sublist under the first item):

- first item
- sub 1
- sub 2
- second item
- third item

And, within that paragraph, it uses the indentation level to determine which items form a sublist. Forget about trying to use nested lists in a word processor. The best you can hope for in a word processor is a single level (no nested lists). With a text editor, it is easy to mark nested lists.

Of course, you could put a blank line between list items (which will happen, even if you don’t want it to, in a word processor if you separate items by pressing the Enter key), but it would look like this to Mobi Machine:

- first item

- sub 1

- sub 2

- second item

- third item

The above would be formatted as five separate lists (all at the same level). With a single level, this would not be a problem, it would just have a little more space between items.

Mac OS X Basics

If you are not comfortable using your Mac, here are a few things about the Mac user interface that might help.

Here is a quick summary:

“click”

This means to click the left mouse button.

“right click”

This means to click the right mouse button.

“drag”

This means to move the mouse while holding down the left mouse button, to move whatever you “grabbed” with the mouse.

Dock

The Dock is usually positioned at the bottom of the screen. Move the mouse pointer to the bottom of the screen to make the Dock pop up (if it is not always visible). Move the mouse left or right along the Dock to find the icon for the application you would like to run, then click on the icon to bring up the application. You can add or remove icons from the Dock. When you run an application (from Spotlight or Launchpad, etc.) that wasn’t in the Dock, its icon will be added to the Dock temporarily while the application is running. To keep the icon in the Dock permanently, right click on its icon in the Dock while it is running, click on Options, then click on Keep in Dock.

Spotlight

This is the magnifying glass icon at the top of the screen, toward the right side. Click on it to bring up the Spotlight search box. This is a fast way to find an application or file that is not already in the Dock.

Finder

Its icon is the left-most icon on the Dock, the one that looks like a two-toned face with a dramatic nose. This is a file browser.

Launchpad

Its icon is usually the next-to-left-most icon on the Dock. It looks like a circle with a rocket ship on it. Click on it to bring up the Launchpad. It has a search box at the top of the screen where you can type the name (or part of the name) of the application you want to run. When you see the application you want to run, double click on its icon.

Terminal

The Terminal is an application that lets you type commands directly to the operating system. To start it the first time, use Spotlight or Launchpad and search for “terminal”, then double click on the Terminal icon. While it is running, add it to the Dock as described above.

downloading files

Download a file by using a web browser, such as Firefox or Safari. On Windows, it is often convenient to download a file by right clicking on the file and then choosing “Save Link As…” (in Firefox) to save the file to your Downloads directory or to specify a different directory in which to save it. In Safari, the equivalent would be to right click on the file’s link then choose “Download Linked File”, to download the file to your Downloads directory, or “Download Linked File As…” to specify the destination name and directory. On the Mac, there is no particular need to right click. A simple (left) click will do the correct thing.

Downloads

Near the right side of the Dock is an icon for Downloads. Click on it to bring up a list of downloaded files. If you don’t see the file you want, click on the icon that says something like “8 More in Finder” to open the Finder (a file browser) on your Downloads folder.

Disk Image Files

A common method of installing programs on a Mac is to download a DMG file. This is a disk image file, a file whose name ends in .dmg. If the image file does not mount automatically, find it in the Downloads (as discussed in the previous item), then click on it to mount it, then, if a folder doesn’t open automatically, double click on its desktop icon to open it in the Finder. Typically, you will then run an installation program by double clicking on it, or you will drag a file or folder to the Applications folder.

Mac OS X version

To find the version of your Mac operating system, click on the Apple icon at the top left of your screen, then choose “About This Mac”.

If any of the above is unfamiliar or seems confusing, don’t worry, it will be easy to get used to. Go to YouTube and search for something like “Mac OS X”, or “Mac OS X how to use the Finder”, or whatever you want help with. Watch the ones that “speak” to you and ignore the rest.

The Mac user interface has changed from version to version, so no one video will apply 100% to all versions of Mac OS X.

Search for anything that still isn’t clear or if things work slightly differently on the version of Mac OS X that you are using. In some cases, it might help to include your operating system version when searching. Sample YouTube or Google search phrases:

- Mac OS X 10.8 how to use the Dock

- Mac OS X 10.6 how to use the Finder

- Macbook Air how to use the trackpad

- Mac OS X how to install an application

- Mac OS X how to install Firefox

Linux Basics

These instructions are written specifically for the Ubuntu 12.04 distribution of Linux, running the Unity desktop environment (GUI). They apply generally to any distribution of Linux, including the newest Ubuntu as of this writing (14.04), although there may be minor differences.

You can find a ton of information about Linux on the web, including YouTube videos. So, if anything about these instructions isn’t clear, or if you use a different Linux distribution, please consult Google and YouTube for additional information.

Although “Linux” refers to the kernel (the heart) of the operating system, it is bundled with a GUI and lots of applications, including “package managers” (which make it easy to install additional applications). This bundle is called a “Linux distribution”. Many individuals and organizations create Linux distributions. The distributions vary slightly as to which programs are installed by default, but they are usually fairly similar.

Ubuntu is one of the more popular Linux distributions. It is free (as are all Linux distributions) and can be downloaded and installed from the web. Ubuntu can be installed on the computer’s hard disk, or it can be run as a live CD (or live USB stick) on a computer without disturbing your main operating system.

You could even install Ubuntu (or other Linux distribution) on a USB stick to carry around as a portable operating system. Search on Google and YouTube for details, if you are interested in this.

If you are running a different distribution of Linux or a different desktop environment, remember that Google and YouTube are your friends.

Here is a quick summary of the Ubuntu 12.04 Unity interface:

Launcher

This is the strip of icons on the left side of the display (if it is not visible, move or slam the mouse pointer over to the left side of the display). To start a program, click on its icon in the Launcher.

the home button

This is the button in the upper left corner of the display, at the top of the Launcher. Click on it to bring up the Dash. If the home button is not visible, slam the mouse pointer over to the left side of the display or press the “Windows” key on the keyboard. (Depending on the keyboard, the “Windows” key might be labeled “Windows” or “Start” or “Command”, or it might just have a Windows logo or some other symbol on it. This is usually the key just to the left of the Alt key.)

Dash

The Dash is basically a search box where you can search for a program to run (or for various other things such as music files). Type the name (or part of the name) of whatever you are looking for. See the next item for an example.

Terminal

A terminal is a program that lets you type commands to the operating system. By default, on Ubuntu, you can start a terminal by pressing C-M-t (sometimes written Ctr-Alt-t, that is, press the “t” key while holding down both the control key and the alt key). If that doesn’t work on your Linux distribution, then use its menu system to find the terminal. On Ubuntu, bring up the Dash, as described in the previous item, then start typing “terminal” in the search box until a terminal icon appears. Click on the terminal icon.

add an application to the Launcher

Some applications are already on the Launcher. To start one of these, just click on its icon in the Launcher. For applications that you use rarely, bring up the Dash and type enough of the application’s name to locate it, then click on its icon in the Dash. For an application that you will run often that is not on the Launcher, after starting it from the Dash, find its icon in the Launcher and right click on it then choose “Lock to Launcher”.

Nautilus

Nautilus is the default file browser (also called a file manager). Start it by clicking on the icon in the Launcher that looks like a manila folder. To learn how to use Nautilus, start it running then click on its Help menu.

file browser

See Nautilus above.

file manager

See file browser above.

package manager

A package manager is a program that makes it easy to install (or uninstall) software applications. If you already have a favorite package manager, use it. Otherwise, use Synaptic.

Synaptic

Synaptic is one of the package managers available for Ubuntu. If you aren’t familiar with how to use it, start it up (search for “synaptic” in the Dash, etc.), then read its manual (click on its Help menu then click on Contents).

References

Liz Castro

HTML, XHTML, and CSS, Sixth Edition by Liz Castro http://www.elizabethcastro.com/html

CSS Tutorial

http://www.w3schools.com/css/

About the Author

Frank Sergeant

Frank Sergeant is really a lot friendlier than he looks in that photo!

He provides computer programming and technical support services to Nepo Press (http://nepotism.net), where he has been intimately involved with authors and the process of turning manuscripts into eBooks.

Please send a note to frank@nepotism.net if you would like to be notified of any updates or corrections to this book and news of additional books published by Nepo Press. Your email address will never be lent or sold to others.

Formatting Services

For further information about the web-based formatting service, please see the Nepo Press website:

- http://nepotism.net/formatting

If you’ve just been reading these manuals but not formatting your manuscript, now’s the time to get a free trial account and try it out for yourself. Send the exact title and author (or authors) name to frank@nepotism.net. We will set up your account and email you the login information, usually within 24 hours.

Other Books and Videos

eBook Formatting

Hopefully you have read at least one the following manuals (since they are prerequisites to this Advanced manual):

- EPUB Machine (Your EPUB Formatting Butler) for creating EPUB 3 eBooks for Apple, Barnes & Noble, Google Books, etc.

- Mobi Machine (Your Kindle Formatting Butler) for creating Mobi eBooks for Amazon and Kindle eReader devices and for reading on the free Kindle Apps for Windows, Mac, tablets, and phones.

Book Covers

Your book needs a cover, and you can make it yourself with the help of the author’s Quick and Dirty eBook Covers.

It steps you through making a very simple book cover using the free GIMP (GNU Image Manipulation Program), available for Windows, Mac, and Linux.

This is a short, focused book designed to teach you as little as possible about GIMP—just enough to create a basic eBook cover. This will not be a $300 cover or even a $150 cover, but it will be a damn good 99 cent cover.

Since you can update your cover image whenever you like on Amazon, Apple, Barnes & Noble, etc., this book lets you create a usable cover immediately, then replace it later as your time, skills, and finances allow.

The screenshots are in full color but are large enough to look good on a grayscale Kindle. You can zoom in to see all the detail.

Fake Novels

Also, there are several fake mystery novels whose only purpose is to show the “before” manuscript and the “after” eBook. Each is very short, perhaps 300 words and includes an appendix with the actual text of the manuscript showing how various effects were achieved, such as drop caps, lists, internal links, external links, table of contents, and images.

Look for the Nepo Press books at your favorite bookseller or see a list at

- http://nepotism.net/

Videos

We have made a number of videos (screencasts) showing, step-by-step, how to perform various formatting tasks:

- http://www.youtube.com/user/nepopress

- http://nepotism.net/videos.

Happy formatting!

The End