Mobile Formats

From DPWiki
Jump to: navigation, search
DP Official Documentation - Post-Processing and Post-Processing Verification

How to convert your HTML file to “mobile” formats

Since you cannot submit your own epub or mobi versions, you use PG’s ebookmaker application to create “mobile” versions of your book—which is the tool that is run on our posted books to auto-generate the epub and mobi (Kindle) versions. It was written and is maintained by PG, and it has some features that other converters to the epub or mobi formats might not have. Since it’s the tool that PG will use on your HTML file, however, it is important to know what will happen to your file when ebookmaker is run on it. The online ebookmaker service will run the exact same version of the ebookmaker tool that is currently used on posted files at PG; it will let you download the results, so you can look at them and make sure they look okay—before your book is posted.

For the online ebookmaker conversion to work correctly, you have to upload exactly the files that ebookmaker expects to get. If you are uploading a book that does not (yet, or at all) have any images, just upload the HTML file. If the current HTML file contains images, you will have to upload them as well. In that case, create a zip archive of your HTML file and the corresponding images folder. Make sure you do not put your text version(s) into that zip file. Once you have submitted the web form, it will take a little while to process your file—and you should then see a link to a file list, from where you can download all of the auto-generated files for your book.

Guiguts also includes a recent version of ebookmaker that can be run locally on your computer, creating “mobile” versions of your book in the same folder as your HTML file.

What ebookmaker does …

ebookmaker takes your HTML and “cleans it up” somewhat, converting it to XHTML 1.1 (which is required for epubs) and moving all inline “style” attributes to a style sheet.

It splits your file

It also splits your HTML file into several smaller files, since many e-readers cannot cope with large files. Each of those files will start on a new page, which means that if ebookmaker decides upon a split in an unfortunate place, you might have a page break where you don’t want it.

How does ebookmaker decide where to split the file? It has a size limit and will split somewhere before it reaches that limit. It prefers to split before <h1> or <div> elements, then <h2>, <h3> and <p>.

You cannot prevent ebookmaker from splitting your file, but you can influence the positions of the splits. You can wrap parts that belong together in a <div>. For example, ebookmaker might decide to split your file between a chapter heading and the motto that comes right after it. If you wrap the two items in a <div>, they should be safe from being separated.

You can also force ebookmaker to split a file in a specific place: Just set a class of “chapter” or “section” on a <div> and ebookmaker will always split before that <div>.

It adds some CSS

Also important to note is that ebookmaker adds some CSS to your e-book—which is applied after your own CSS, and therefore might override your choices in some cases. If you notice any unexpected formatting when <a href="#testing">testing your “mobile” versions</a>, make sure you check whether this is due to the CSS that was added by ebookmaker, rather than your own.

The relevant parts of the added CSS—slightly reformatted to make them easier to read—are (as of ebookmaker version 0.9.1, August 2020):

  color: black;
  background-color: white;
  margin: 0.5em;
  width: auto;
  border: 0;
  padding: 0;

div, p, pre, h1, h2, h3, h4, h5, h6
  margin-left: 0;
  margin-right: 0;

  page-break-before: always;
  padding-top: 1em;
div.figcenter span.caption
  display: block

It adds the x-ebookmaker class to the HTML body

The whole of your book is contained within a body element, to which ebookmaker adds the class 'x-ebookmaker', i.e.

<body class='x-ebookmaker'>

This means that in your CSS section, you can make some bits of CSS only apply to elements if they are in a file created by ebookmaker. You do this by using a CSS descendant selector (meaning the element you are styling is a descendant of a <body> with class x-ebookmaker), e.g.

.x-ebookmaker .myclass { CSS which will only apply to ebookmaker output files }

This is explained further, with examples, in the Case Study on Media Types and Mobile Formats.

It converts elements with special CSS classes

Usually, you are free to choose any name for a CSS class. There are a few class names, however, which get special treatment by ebookmaker. Although this is often helpful—when you and ebookmaker agree on the meaning of the name—it can potentially wreak havoc on the resulting epub and mobi files. Therefore, it helps to know the special class names and what ebookmaker does to them—so that you will only use those classes where it is appropriate.

The class names with special meanings are:

  • x-ebookmaker-drop: Any element with this class will be omitted from the output files created by ebookmaker. This is the recommended way to hide content on e-readers. Take care that any element that will be dropped in this way is not the target of a link from the contents, index, etc., or there will be broken links in your output file.
  • pagenum, pageno, page, pb, folionum, foliono: Any element that uses one of these classes will be treated as a page number by ebookmaker. The entire element will be replaced by an anchor (<a>) that does not contain any text. While this is a reasonable way to treat real page numbers (preserving the ability to link to them while removing the displayed numbers), it will delete content from your book if used for something other than page numbers. (Note that this is not a good approach to hide content on e-readers; use the x-ebookmaker-drop mentioned above, as explained in the relevant example in the Case Study on Media Types and Mobile Formats.)
  • versenum, verseno: These are treated nearly the same as page numbers; their content will be stripped.
  • chapter, section: When used on a <div>, these classes will lead to a page break in the “mobile” formats due to the file being split at these points.

It removes some things

In addition to inserting some CSS and converting special elements, ebookmaker also removes some things.

Firstly, it deletes the following properties from the CSS:

  • “float” (and, on the same images, also “width” and “height”): This un-floats all floated elements, e.g., images with text flowing around them and, in particular, illustrated drop-caps.
  • “position”, “left”, “right”, “top” and “bottom”: ebookmaker removes any absolute or relative positioning. If you have moved elements to the margins (like line numbers in poetry) using “position”, they might end up in unexpected places in the “mobile” versions.
  • “background-image” and all related properties: Background images set using CSS will not be displayed in the “mobile” versions.
  • Finally, any properties whose values end in “px”: This often applies to “width” and “height”, but can also affect other properties, e.g., borders. Note that ebookmaker does not remove width and height attributes from <img/> elements, just sizes specified in the CSS.

Secondly, ebookmaker removes displayed cover images. This means that if you have included your cover image in the HTML, it will be removed from its original place—since it is already used as the cover image, and thus displayed at the very beginning of your book.

Finally, ebookmaker removes links to anything that will not be part of the final e-book, in particular any external links.

It changes media type “handheld” to “all”

Previously the recommended method of tailoring CSS for mobile formats, the “handheld” media type is now deprecated in CSS3, and the x-ebookmaker class should be used instead. However, if you are using the the “handheld” media type, you should be aware that the latest version of ebookmaker still changes all references to media type “handheld” to media type “all”—that is, it makes sure that the “handheld” CSS will be considered by all devices displaying the generated epub file, no matter whether they would ordinarily consider themselves to be “handheld”.

N.B.: It is thus even more important to make sure that your file works on devices that apply both the “screen” and the “handheld” CSS; for more information on this, see the Introduction to @media for DP/PG Use.

… and how to test the result

Once you have downloaded the epub file, there are several things you can do with it to help you assess whether it works as expected.

First of all, if you have an e-reader that can display epub files (or an app on a phone or tablet, e.g., iBooks on an iPad or iPhone), go ahead and copy it to your device and look at it there.

Alternative software that will let you look at epubs on your computer includes Calibre and Adobe Digital Editions.

In order to preview the mobi version of your book, the most useful software is Amazon’s Kindle Previewer, which, according to Amazon’s description, emulates actual Kindle hardware devices—so should be closer to the “real” Kindle experience than displaying the book on one of Amazon’s assorted Kindle Reading Apps.

And finally, if something Just Won’t Work and you want to figure out why—or if you are curious—, you can look at the generated HTML and CSS inside the epub file. Because epubs are just renamed zip files, you should be able to unzip the archive and look at the contents. For this, you might or might not have to change the file extension to .zip, depending on which unzipping software you use. Unzipping will let you examine the automatically-added CSS as well as any other changes ebookmaker might have made to your HTML file.

To comment or request edits to this page, please contact lhamilton or hdmtrad.

Return to DP Official Documentation Menu