I recently passed the Smashwords autovetter and epubcheck with great effort using an epub file, and I thought I'd share what I learned with you so that you might have an easier time of it than I did. This tutorial presumes you have some knowledge of HTML markup and CSS styling or can acquire that knowledge without too steep a learning curve, though I've provided a number of screenshots and code examples along the way to help you get started.
I'm using the excerpt edition of my poetry and short story collection The Ruin of Beltany Ring: A Collection of Pagan Poems and Tales (RBR) in my examples. It contains no images but the cover, and the only unusual formatting it contains is for poetry. So this tutorial is somewhat limited in that it won't help you with complex formatting in the body of your epub file.
Here's what I do know:
Your Toolkit
An Epub Reader of Your Choice: I use Okular in Kubuntu Linux to preview my completed epub files before uploading them, but there's a decent plug-in for Firefox as well. Sigil (see below) has a preview tool, but I don't care for it. Note: Don't skip this step! It's easier and faster to preview your compiled epub file locally than it is to download it from Smashwords afterward.
A Plain Text Editor of Your Choice: Again, I'm a Kubuntu Linux user, so my preferred text editor is Kate, but Notepad for Windows is perfectly fine as well (I'm not certain what's available for Mac). Please note that programs like Microsoft Word and LibreOffice are not recommended for this process, since your goal is to strip text of formatting before manipulating it, and these programs add formatting.
Sigil: I use and recommend the free Sigil epub creator, which is well-supported with both the Sigil User Guide and the Sigil Wiki. Sigil is available for Linux, Windows and Mac OS, and I use it in a Windows virtualization on Linux.
The Smashwords Style Guide: While Smashwords will receive, reformat and list .doc and epub files regardless of their quality, the company will not distribute ebooks to its Premium Catalog (e.g. iTunes, Kobo, etc.) that do not precisely follow the guidlines outlined in the Smashwords Style Guide.
KDE on Windows and Mac & Virtualbox: For those of you who want the functionality of Okular and Kate on Windows or Mac, try the KDE on Windows and KDE on Mac projects. You might also run a full Kubuntu Linux installation on Virtualbox. I run it the other way around; a Windows virtual client OS on a Kubuntu Linux host.
Necessary Inclusions
Your epub file must contain:
A cover page that includes the cover image you've already uploaded to Smashwords. This image should fit on one page of your epub file and not overlap onto successive pages. This means that the image you've uploaded to Smashwords will be much larger than the image you're using in your epub file. You can use an image manipulation program like Gimp or Photoshop to scale it down.
(Right Click on Images to Open in New Window)
 My Cover Page in Sigil
|
 My Cover Page in the Final Epub
|
A title page that meets the requirements stipulated in the Smashwords Style Guide, section 21b. This is what mine looks like, both with HTML markup and as a finished product.
(Right Click on Images to Open in New Window)
 Title Page in Sigil w/ Markup
|
 Title Page in Sigil
|
Moving Parts
Tables of Contents
Sigil will generate a hyperlinked ToC from every header you use in your epub document. H1 headers provide chapter breaks, while successive headers provide more granular divisions of text. I recommend a new blank HTML file for each chapter, which will be easier to format than a single, long text file. Sigil will also generate a CSS file for the ToC, which I recommend you either combine with the CSS file you create to style the rest of the manuscript or change to meet Smashwords' font size and other formatting restrictions. Because the Sigil User Guide and wiki are so thorough, I'll leave it to you to research this topic further should you need to.
CSS Files
Smashwords is extraordinarily particular about such things as font size (nothing over 18px) and paragraph spacing, so you really need a CSS file linked to every HTML document in your epub. It should stipulate the font family, sizes and other styling for headers and text along with any other basic formatting instructions.
What follows is the entirety of my CSS file for RBR:
h1 {
font-family:"Times New Roman",Georgia,Serif;
font-size: 14px;
font-weight: bold;
margin-top: 15px;
margin-bottom: 15px;
}
body {
font-family:"Times New Roman",Georgia,Serif;
font-size: 12px;
text-align: justify;
}
I handled paragraph spacing in the body of each HTML file, which I'll cover next. Again, the Sigil User Guide contains clear instructions for linking HTML documents to CSS files in an epub, so I'll leave you to research this should you need to.
Formatting Text
You must copy and past the entire body of your manuscript into a plain text file before attempting to format it in Sigil. I recommend you do this in chapter-sized chunks.
Using a new HTML document for each chapter, paste your raw text into Sigil's Book View window (View-Book View). Highlight the chapter name and click the H1 button on the upper left side of the program window. That will format your chapter heading for inclusion in your ToC.
Now go to Code View (View-Code View). You'll see the HTML document header information at the top of the window, which should be left alone and will look something like this:
<?xml version="1.0" encoding="utf-8" standalone="no"?> <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd"> <html xmlns="http://www.w3.org/1999/xhtml"> <head> <title></title> <link href="../Styles/styles.css" rel="stylesheet" type="text/css" /> </head>
Beneath that, you'll see the opening Body tag <body>. This is where your text will begin, and it will end with a closing Body tag </body>. Sigil will have endeavored to format your text for HTML, but don't trust it. For simple headers and text, your manuscript should only contain header tags and paragraph tags, like the RBR example below:
<h1>Ink for the Dead</h1> <p>Her hands tremble as she hands me the picture. The paper is crumpled as though it has been wadded up and smoothed a hundred times. I take it from her and try not to gaze too long at the crow’s feet around her eyes and the gaunt prominence of her cheekbones. She looks as if she herself might crumple if I refuse her. Folding her hands in her lap, she stares out the window and down the street as if waiting for her long overdue strength to return from some vital errand. There are deep needle tracks in the flesh of her arms, and I wonder what else fled down those tracks with that strength.</p> <p>“I don’t even know why I love it so much,” she says. “But you know how it is...” Her voice trails off hopefully. I nod and fix my gaze on the object of her desire. The lines of the piece are chunky and awkward, and the colors are gaudy and harsh. But in the way of my profession, my eyes smooth the fat lines into feathers and sweep the garish colors into fire. I wait for a moment while the wyrd, the holy purpose of it settles over me like a warm cloak. I see what she wants. She wants to be reborn while she still has the time.</p>
Text formatted for poetry and the like requires a slightly different approach. Here's how I handled lines of poetry in RBR:
<h1>Fetters</h1> <p>We dive into the abyssal waters<br /> of that otherness, trancing,<br /> Archaic symbols twining<br /> about our throats, silvery nooses,<br /> Old soul memory a provenance<br /> of oxygen, nourishing our cells,<br /> And the world is transformed - </p>
As you can see, a paragraph tag opens and closes the verse, while each line ends with a break.
If your formatting is any more complicated than this inline (excluding lists, images and such), you run the risk of failing the autovetter, which likes either a non-tabbed indentation at the beginning of each line (which should be defined in your CSS file) or a block style with space between each paragraph, but not both and most certainly not a host of hard returns in place of HTML markup and CSS styling.
Once you've formatted the text cleanly and correctly, you can compare your original document to your Sigil HTML document and re-implement any text effects like bold, italic, and underline.
Smashwords Errors
There are two kinds of errors you might receive after uploading an epub file; autovetter errors and epubcheck failure. An autovetter error indicates your manuscript has failed to meet the Smashwords Style Guide requirements in some way; a missing title page, a font size error, etc. An epubCheck failure means there is a structural problem in the HTML and/or CSS of your epub file, such as a missing page referenced by a hyperlink. As previously mentioned, autovetter errors will prevent your manuscript's inclusion in the Premium Catalog, while epubcheck errors will prevent its inclusion in the iTunes book store.
Smashwords will provide a detailed explanation of any autovetter errors and point you toward the appropriate section of the style guide for help correcting them. Sigil has a feature that will check for and return epub errors. These are sometimes cryptic, but you can use the Sigil search tool along with the user's manual and wiki for help ferreting them out of the HTML and CSS.
Caveats
I had awful luck with Smashwords and the .mobi format, which is the one Amazon likes. In fact, the .mobi file was so ugly I refused to make it available from Smashwords. Instead, I used the Ultimate Ebook Creator (via my Windows virtualization) for my .mobi file and released a separate edition through Amazon for Kindle. This means that my Kindle edition doesn't have an ISBN number, since that number was issued by Smashwords for its own editions of my ebook.
Which brings me to ISBN numbers. My ISBN for the print edition of RBR lists Createspace as the publisher, while my ISBN for all but the .mobi editions of the ebook lists Smashwords as the publisher. Next time, I'll be buying ISBNs through Bowker. That way, they'll all list Triskele Media Press (my own imprint) as the publisher, and I can issue them as I see fit.
Final Thoughts
There's no getting around the complexity of formatting ebooks for publication, and I know that what I've provided here is only a tiny window into the overall process. But I hope it helps you a little, and I wish you all the best in your e-publishing endeavors.
I also hope you'll leave insights and course corrections in the comments section of this blog entry so that other people who read it can have the benefit of your knowledge. Comments are moderated (I get a lot of spam), but I promise to clear your posts as quickly as I can.