Frank Sergeant

copyright © 2013-2014 Frank Sergeant

all rights reserved

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.

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.

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.

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:

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

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

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

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.)

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 (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.

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:

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."

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;
  }

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.

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>

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

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

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.)

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.

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.

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:

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

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.

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

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:

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.)

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):

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.

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.

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:

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.

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.

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.

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.

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" ""

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

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.

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.

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.

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.

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.

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.

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.

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).

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.

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.

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

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.

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:

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

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).

Frank Sergeant

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