I’ve recently created an ePub for the first time, and published on Lulu, so am putting together some notes on things that tripped me up in the hope that it might help others.

ePub files are one of several formats of eBook. They’re basically a Zip file containing everything needed to show a book. Text contents, fonts, styles, images, table of contents, and metadata. The text in an ePub is in HTML format, so it’s very similar to a web page. This allows the book reader to flow the text depending on the screen size of the device it’s being read on, as well as allowing the user to change font style, size, etc to make it easier for them.

ePub files can be created and edited by hand, but it’s a lot easier to use software to make sure all the files are in the correct places. Sigil is free software for creating and edition ePub files, which is what I ended up using.

Creating an ePub in Sigil for the first time means pages are created as XHTML format, which is more restrictive than HTML. This seems to create some problems for Lulu when it checks that the document is formatted correctly, even though ePub will work fine in readers such as Google Play Books (which, incidentally, is very convenient to upload books to and then view on one’s Android phone for checking).

Notably, the book is all looking good, so you upload to Lulu. After a while it finishes checking and comes back with the error:

“The table of contents contains one or more links without text.”

This is completely misleading, and there is likely nothing wrong with the table of contents (press Ctrl-T in Sigil and regenerate it, which can’t hurt to try the first time anyway). It’s actually because Lulu does a syntax validation, and something else in each XHTML file fails, so as the XHTML is rejected the ToC then points somewhere it doesn’t understand. Picky, yes; arguably correct, maybe.

If you download the error output and read it you see something like the following:

ERROR: IOException: Unresolved external XML entity: 'http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd' in OEBPS/Text/Introduction.xhtml
ERROR: Unable to locate element with id 'sigil_toc_id_1' in OEBPS/toc.ncx
ERROR: Unable to locate element with id 'sigil_toc_id_2' in OEBPS/toc.ncx
ERROR: Unable to locate element with id 'sigil_toc_id_3' in OEBPS/toc.ncx

So the “table of contents” error is related to the “Unable to locate element” problem, which is in reality caused by the “Unresolved external XML entity” issue.

At the top of each XHTML file there is the following header, automatically added by Sigil:

<?xml version="1.0" encoding="utf-8"?>
<!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">

This needs changing on every page to get rid of the <!DOCTYPE…> block, thus:

<?xml version="1.0" encoding="utf-8"?>
<html xmlns="http://www.w3.org/1999/xhtml">

It’s easy to do this with find and replace if you have multiple chapters/files in the book. Copy the whole DOCTYPE section into find and replace it with nothing.

Now you get the problem that when you save the file, Sigil unhelpfully adds them back in again… go into Sigil’s preferences, “Edit; Preferences (F5)” and untick both “Open” and “Save” under “Mend XHTML Source Code On”. This will stop the DOCTYPE being added on Save, though in my version of Sigil (0.9.8) at least still adds them on file open. Solvable easily with find and replace.

This might be enough to persuade Lulu to validate the file, but the next gotcha may be that you used non-breaking spaces with the standard HTML “&nbsp;” entity. This isn’t allowed in XHTML, but unhelpfully included in every new XHTML file added by Sigil. There are reports on the web that you can add it back again with a new DOCTYPE command, but this again won’t work with Lulu’s validity checker, so instead do another find and replace and change all instances of “&nbsp;” to “&#160;”, and that problem is solved. Also go into Sigil’s preferences again, select the “Preserve Entities” page and remove “&nbsp;” from the list, which at least means you’ll get an error if you try and use it.

You may then find that the book metadata is incorrect. Open the metadata editor (Tools; Metadata Editor) and ensure you have set at least the language, title, author, description and publication date. You can also add the ISBN number and other data here if necessary. The author is an unusual field in that you add the entry (“Add Metadata; Author”) and it adds “opf:role” as “aut” (author). You can then add a new Property (“Add Property”) and choose “File as”. The author name should be their usual name, e.g. Joe Bloggs, but the “file as” property is how the name will be indexed, e.g. “Bloggs, Joe”. You can add multiple authors, with different roles, such as “illustrator” or “editor”, but be aware that Lulu may change these – once the book has validated download it again and check that the metadata is still as it should be. Note that Lulu will definitely override the “title” and “author” metadata fields with whatever you enter on their web page when you create the book, so ensure these at least are the same.

The cover will also be changed by Lulu if it is too big. I found that a cover of 1200px wide was resized by them down to 1189px wide, but a cover 1169px wide was left as-is. So go for a cover image around 1150px wide at most and it will probably go untouched. I used a JPEG at 0.5 compression which was perfectly suitable quality for the book cover and kept the file size smaller, something to bear in mind when people will be keeping these on their phones etc.

Watch out for fonts included, too. They tend to be pretty big, so only include ones you really need to keep the file size smaller.

Set the cover by adding the image file and then right-clicking it in the Sigil file browser and ticking “Cover Image”. Note that you will likely also want to add a front page to your book with a simple <p><img …></p> content to add the image into the book as well. The selected cover image isn’t otherwise shown in the contents.

Other than that, most things seem fairly straighforward. Sigil has enough features to be useful and the bugs I came across aren’t too annoying. Use F2 regularly to switch between HTML and text editing mode so that changes can be made in both. Save the file regularly (as with any application) and use something like Google Play Books to review what it looks like in another viewer. Stylesheets and images are included the same as any HTML web pages – though conveniently you can right click any of the XHTML contents files and choose “Link Stylesheets” which will add the correct tags to the <HEAD> section for you.

Lulu needs a “marketing image”, which might be a slightly different aspect ratio from the one used for the book cover, so don’t expect to necessarily use the same image for both. Their cover editor is a bit weird, but basically just upload a “background” image of the appropriate size and untick all the title/author text options and you’ll get what you want.

When all is done upload to Lulu, hopefully everything passes, and it’s easy to get the book into their store. Profit margins are quite respectable with Lulu directly, though once you push to Amazon etc then you realise how the retailers make their money.

Once you’re all done, you can create a copy of your book and edit that and strip out a load of the content, and then upload it to Lulu as a preview. They’ll add it as a free download to the book page. Watch out, though, that they still seem to do a syntax validation on this file, but if the validation fails I just got a blank web page. If you get that then start guessing what might be wrong! But at that point you’re pretty much finished. Set the price, and wait…

Leave a Reply

Your email address will not be published.