Contents | Start | End | Previous: Chapter 14: Working With String Tables | Next: Chapter 16: Understanding Ebook Formats and Platforms


Chapter 15: Advanced Topics

This chapter describes a variety of advanced topics that the newcomer to Jutoh can most likely ignore.

Embedding fonts

Jutoh lets you embed fonts into Epub books. You might wish to do this to ensure that non-Western characters are rendered correctly, especially for viewing in Adobe Digital Editions, which fails to render non-European languages without embedding; or you may just wish to give your ebook a different look. However embedded fonts are not supported by all ebook readers, and there may be copyright issues; so you should only embed fonts if absolutely necessary.

An example of a Unicode font that you can freely embed in your ebook is DejaVu, available from:

dejavu-fonts.org/wiki/Main_Page

If you wish to create a Greek Epub, you can use the free Gentium font, available from:

scripts.sil.org/cms/scripts/page.php?site_id=nrsi&id=gentium

To embed a font, follow these three steps.

  1. Add a font. Use the Documents toolbar button or Document | Add Embedded Font Document menu command. Select a font file when prompted. A copy of this font will be added to the project and you can change the font family name and other parameters. Change the font family name to match the font name used in your ebook styles, if applicable.

  2. Enable embedding in your configuration. In your Epub configuration(s), available from the Configurations tab on the Project Properties dialog, scroll down to the Fonts group and check Embed fonts if not already checked. Note that if Embed fonts is enabled, as well as Optimize for iBooks, Jutoh will generate a file called com.apple.ibooks.display-options.xml with specified-fonts set to true. This enables font embedding for iBooks.

  3. Specify font substitutions. If the font is installed on the computer and is therefore available from Jutoh’s dialogs, and is specified in your book, then you’re done. But if the font you want to use is not specified in your document, you must specify a font substitution in the Font substitutions property in your configuration. For example, “Times New Roman: DejaVu Sans, Times New Roman”. This will use DejaVu Sans, Times New Roman for the font family wherever Times New Roman is found in style definitions and content. The ebook reader will fall back on Times New Roman if it can’t find the embedded font DejaVu Sans. You can specify multiple font substitutions by separating them with semicolons.

If you have multiple font files for a single font family, for example regular, bold and bold italic variants, you can use the same font family name in all of these font documents (for example, DejaVu Serif) and specify the italic style and weight properties in each font document, as in the following:

Font document

Jutoh will generate the appropriate CSS so that the viewer can use the correct font file for each combination of italic style and weight.

If font embedding isn’t working at first, check that the font family specified in the font document is identical to the font name you use within styles, or within your font substitutions. Otherwise the ereader will not be able to find the correct font to use.

Embedding media

Jutoh lets you embed audio and video into Epub and Mobipocket books. This is only supported in some readers (for example, iBooks), and Amazon may not accept Mobipocket containing multimedia (and media in locally-transferred Mobipocket files may be blocked).

For video in iBooks, Apple recommends that you use H.264 compression at VGA resolution. The poster image should be 150x300 pixels. Audio should be stereo, AAC/MP4, 256kps, encoded using iTunes.

Amazon's guidelines for formatting Kindle books, with information about audio and video formats, is available at:

kindlegen.s3.amazonaws.com/AmazonKindlePublishingGuidelines.pdf

To embed a media object, follow these three steps.

  1. Add a media document. Use the Documents toolbar button or Document | Add Media Document menu command. Select a media file when prompted. A copy of this file will be added to the project (it may take a long time if the file is large) and you can change the file name to be used and other parameters.

  2. Insert a media object into your content. Use the Insert | Media Object command on the Format menu or the context menu, and when prompted, choose the file name from the list of media objects currently in this project. Enter other parameters if you wish, such as a title, and fallback text to show if the reader does not support the audio or video tags. You can preview your file in Kindle Previewer, setting the device to (for example) iPhone or iPad, to see the effect of adding media.

  3. Ensure media objects are switched on in your configuration. Under the Images and Media group in your configuration, check that Generate media objects is enabled. If you switch this off, no media files will be included in the book and the media tags will not be included in the XHTML.

You can also use media documents and objects to insert images. The image won’t show up in the editor when you insert a media object that references the media document, but there is an advantage – you could add several media documents with the same name, at different resolutions, and use configurations to selectively include and omit media documents from the generated ebook. You do this by specifying tags in your media document, (for example, “hires”, “lores”) and then specifying tags in the configuration options Include media documents matching tags and Exclude media documents matching tags. This technique is also useful for very large images that take a long time to load into the editor when inserted directly.

Embedding a PDF

Currently embedding a PDF into your book works in iBooks only.

  1. Add the PDF and PNG files to the project as media objects (Document | Add Media Document).

  2. Add this to your content, in its own paragraph:
    <p><a href="media/subwaymap.pdf"><img src="media/map.png" alt="img"/></a></p>
    substituting your own file names.

  3. Apply the ‘HTML’ style to the above paragraph.

EpubCheck will complain about the syntax, which you can ignore.

Setting a background image

The following method works for some Epub viewers, including Adobe Digital Editions.

  1. Insert a new image into the Resources section of your Jutoh project using Document | Add Media Document and selecting an image.

  2. Ensure that Generate media objects is enabled in your configuration.

  3. Right-click on the section(s) you want to have a background image, select Properties, and insert the following into the Extra CSS field:
    body {
    background-image: url(media/image.png);
    background-repeat: repeat;
    margin: 0 0 0 0;
    }
    where media/image.png is the path specified in the media object. Alternatively, if you want it on all pages, you could add this once to the the style sheet (click on the Edit button at the top of the Styles page in Project Properties, check Custom CSS and paste the code).

Adding tables

Tables are not officially supported by Jutoh, but if you really need them, there are workarounds:

  1. Prepare an image containing the table, perhaps by taking a screen shot of an existing document and saving it as a JPEG or PNG. Insert that image in Jutoh as usual.

  2. Enter the table as HTML code and format it with the HTML style. This tells Jutoh to pass the text directly to the HTML file, and only works for Epub and Kindle formats.

An example of an HTML table that will work with Epub and Mobipocket is provided at the Mobipocket developer’s site, at:

www.mobipocket.com/dev/article.asp?BaseFolder=prcgen&File=tables.htm

Understanding encodings

When importing text files, Jutoh needs to know what the encoding of your files is, since otherwise the files are just streams of bits that could represent anything. A ‘standard’ ASCII file only represent the basic symbols, whereas files encoded in Unicode can represent most symbols in use on the planet. Jutoh’s favoured Unicode encoding is UTF-8, in which plain text is encoded with one character per symbol (and so is readable in any text editor) and more complex symbols are represented by two or more characters.

When you save text from a word processor, you need to make sure it’s going to write using the encoding that you’ve specified in the New Project Wizard or Project Properties. For example, when saving a document as plain text from Microsoft Word, Word will show you a further dialog. Click on Other encoding and select “Unicode (UTF-8)”. Don’t check Insert line breaks, since you want each paragraph to be one line.

If you forget to save in the right encoding, you may be able to fix it, as follows. When you get an Jutoh error indicating an encoding problem (or the file doesn’t show properly in the finished book or the editor), open the file in an encoding-savvy application such as Programmer’s Notepad. It should auto-detect the encoding, which you can check by typing Alt+Enter to see the document’s properties. Now select the whole document and copy it to the clipboard. Create a new file, change the encoding to UTF-8 in the document’s properties, and paste the text into it. Save this over the original file – it’s now in the correct encoding.

If you can’t change the encoding of the original file, you can specify it in the Import Options section of the New Project Wizard, or the Options page of Project Properties if you’re importing a file after initial project creation. Also, if you are importing HTML or Epub and the encoding is missing from one or more HTML files, Jutoh will use this setting – it will also warn you about the missing encoding so you can go back and specify it. For example, if the file was created on Windows without specifying UTF-8, you could try the value ‘Windows Western European’.

Guide types

Each document in a book can have a “guide type” which is written to the guide section of the Epub or Mobipocket file, and indicates the role of the document. You can set the guide type by right-clicking on the document in the outline, selecting Properties to show the Document Properties dialog, and then changing the Guide type selection.

These are the possible guide types:

When Jutoh generates a section without it being present in the project outline (for example, the cover page and simple table of contents page), it will set the appropriate guide type.

If you use the keyword %STARTPAGE% for the guide type, it will be replaced by the appropriate type for Mobipocket or Epub, as specified by the current value of the configuration option Start page guide type. However, this has become unnecessary since all ereaders now recognise (or quietly ignore) the “text” guide type.

How to format drop caps

Jutoh doesn’t support drop caps directly, but you can use CSS to achieve it (at least in Epub, with slightly less success on Mobipocket). There’s some information about the general principles here (external link).

In recent versions of Jutoh, a “Drop Caps” character style is created automatically in the default style sheet, which you may wish to adjust to your preferences.

If Jutoh has not already added a “Drop Caps” character style, go to Project Properties/Styles, click New Style, choose Character Style. Enter the name “Drop Caps”. Press OK. Still in the Styles panel, in the drop-down under the styles list, choose Character styles. Select “Drop Caps”, click Edit, go to the Font tab and choose a large font, say 20pt, and choose Bold under Font weight. This is just to show a large bold font in the editor; this exact formatting won’t show in the ebook. Press OK to dismiss the “Drop Caps” editor and now click on Properties to show the Drop Caps property dialog. Check Use custom CSS and paste in this text:

.C_Drop_Caps {

overflow: hidden;

line-height: 90%;

height: 0.75em;

font-size: 280%;

margin-right: 0.075em;

float:left;

}

This should replace the existing text – if you used a different name for the Drop Caps style, make sure it’s reflected in the name after the dot in the CSS.

Now press OK, OK again and in the editor, select the first letter of your paragraph and apply “Drop Caps” to it. You can do this with right-click (or control click on Mac), Styles, scroll to the bottom of the menu, click on Character Styles, choose “Drop Caps”.

Now when you compile the Epub and show it in, say, Adobe Digital Editions, you should see something approximating a drop caps. In Kindle it’ll be shown as a large letter, just not dropped. You may need to tweak the CSS to work better with your choice of font sizes.

How to format small caps

Small capitals can be applied to a named style or directly to text via the Font tab of the style editor. For convenience, you could add a character style called “Small Caps” that just has this attribute defined.

When generating Epub and Mobipocket ebooks, Jutoh can generate small caps either by using the official font-variant CSS attribute, or by emulating it by emitting capital letters and shrinking the text. Adobe Digital Editions and some other ereaders do not support font-variant, but all ereaders will do a reasonable job using small caps emulation, so by default emulation is used. To use font-variant instead, clear the Emulate small caps configuration option. For those ereaders that support it (for example, Kindle readers, iBooks, and the Azardi software), font-variant is a superior method since it renders real capitals larger than the lower case letters. However, if you’re targeting multiple ereaders, emulation is safer.

If you wish to add small caps to the first few words of your chapters, there’s a handy option in the Document Cleanup dialog (accessed from the Book menu) to do just that. Before using it, you’ll need to create a “Small Caps” character style.

How to add an ISBN to your books

Some platforms require you to supply an ISBN for your ebooks. For example, to get your books into the premium Smashwords catalogue, you need an ISBN for each ebook. This needs to be separate for each book edition – paperbacks, hardbacks and distinct ebook editions for different platforms all need separate ISBNs. You can buy a set of ISBNs from the relevant agency (in the UK, it’s Nielsen), or you can see if your ebook publisher such as Smashwords can supply ISBNs.

Having got your ISBN, where do you put it? Go to the metadata in Project Properties (just click on the Edit button on the toolbar) and click on the “...” button next to the Identifier field. Click Add to add a new value to this element, and choose Add ISBN. Enter the ISBN (just the number, including dashes) into the Value field. Now delete the original value, “Element 1”.

OK, so you have different ISBNs for different ebook editions – but you want to publish your ebook to different platforms, with different ISBNs, without having to edit separate Jutoh files for each edition. The way to accomplish this is via string tables. String tables allow you to set up substitution tables; since we can specify a different table for each configuration (Mobipocket, Epub and so on), we can put a variable called, say, %ISBN% into the ISBN value field, and substitute a different ISBN value from the different tables, depending on the current configuration.

Let’s assume that you are using two configurations, Mobipocket and Epub. The Mobipocket book is going to the Kindle store, and the Epub book is going to the iTunes store.

  1. Click Edit on the toolbar, then the Strings tab. Click the “+” button to add a new string table, and call it Kindle.

  2. Click Add and enter “ISBN” to add a new string whose name is ISBN.

  3. Click on the value field (second column) and enter the ISBN for the Kindle store.

  4. Repeat the above, adding a new string table called iBooks and adding the second ISBN value.

  5. Click OK to dismiss the Project Properties.

  6. Click Edit on the toolbar again, then the Configurations tab.

  7. Click on the Mobipocket configuration, and scroll down to the String Tables group.

  8. Select “Kindle” in the Project string table property.

  9. Click on the Epub configuration, and scroll down to the String Tables group.

  10. Select iBooks in the Project string table property.

  11. Click on the Metadata tab and enter %ISBN% into the Identifier field.

  12. Press OK.

Now when you select a configuration, a different string table will be used and the %ISBN% variable will be filled in with the value of “ISBN” in the appropriate string table.

If you have different editions of your book with the same format (for example, a Mobipocket file you put on your web site, and one that you upload to Kindle), you can just add another configuration (taking care to set the format property correctly) and a string table to go with it. So you can have as many configurations as you have sites that you upload to.

You can use the string table to change other things in your metadata and (if you check the Replace strings in content configuration property) your book pages.

For more information on string tables, see Chapter 14: Working with String Tables.

How to specify which sections will be included in the ebook

In Chapter 13: Working With Style Sheets we saw how we could change the content of the book using styles. Another way of changing content is to include or exclude entire sections. There are two ways of doing this: specifying in the Book Section Properties dialog whether this section will be included for a given format, and specifying inclusion or exclusion by tags.

Specifying inclusion by format is inflexible, because you might have different configurations for the same format. To use tags, first enter tag names into the Book Section Properties dialog for each section document. You can show this using the Document | Document Properties command (Shift+Alt+Enter). Let’s say you only want the first three chapters of you book to be shown in your book sample; you have created a new configuration called “Sample Epub”. Now add the tag “sample” to your title page, table of contents (if there is one) and the first three chapter documents.

Next, edit your “Sample Epub” configuration and in the property Include sections matching tags, type the value “sample”. Regenerate your table of contents and compile. You should now have an Epub that contains only the sample content.

If you have a section that should only be included for a particular configuration, then give it a tag and enter that tag in Exclude sections matching tags.

You might also make use of this to have alternate title pages, intended for different distribution channels.

Removing underlining from links in HTML-based formats

There is no provision in Jutoh for specifying this level of detail, so it needs to be done using custom CSS. You can add CSS either globally if you want no underscores throughout, or per section. To add it globally, go to the Styles page on the Project Properties dialog and click on Edit Properties at the top of the dialog. Check Use custom CSS and paste in the CSS code.

Let’s say we want to make the link colour red, and remove underlining. You can use the following code:

a:link { color: red; text-decoration: none; }

a:visited { color: red; text-decoration: none; }

a:hover { color: red; text-decoration: none; }

a:active { color: red; text-decoration: none; }

Alternatively, if you want the colour to be the same as the surrounding text, but keep underlining, you could use:

a:link { color: inherit; text-decoration: underline; }

a:visited { color: inherit; text-decoration: underline; }

a:hover { color: inherit; text-decoration: underline; }

a:active { color: inherit; text-decoration: underline; }

To apply CSS to an individual section only, right-click over a section in the project outline, select Properties, and then check Extra CSS. Paste in the above page and press OK.

You might notice that when you look at the HTML generated by Jutoh for links, the style you applied to the link has been removed. This is because if the configuration property option URL attribute removal style has a style value, the attributes in the style will be removed from the link before it is written to the HTML file. This avoids clashes between the styles specified in the editor and defaults used by the ereader – such clashes can make links look untidy, especially if the Jutoh and ereader URL colours are slightly different. It’s better that the ereader shows links in the default syle than in a mixture. You can reapply the intended attributes using CSS properties, as above.

Creating fixed layout ebooks

Jutoh is primarily a tool for creating reflowable text and picture ebooks. However, you can create fixed layout ebooks for iBooks with the restriction that each page is a single image.

Use the Enable fixed layout configuration option, and specify the width and height of the images that will be used in each section (they should all be the same size). Switch off table of contents and title page generation, since the presence of reflowable content will cause the book to show up as a tiny mess.

In a future edition, Jutoh will have special support for fixed layout books for a variety of readers, with text and images superimposed on the main page image.

Jutoh and Epub 3

There is preliminary support for Epub 3 – you can switch Epub 3 support on by setting the Epub version configuration property to 3. The adaptations to Epub 3 are currently as follows:

Jutoh is distributed with EpubCheck 3, which means it can check both Epub 2 and Epub 3 files if you have Java installed.


Contents | Start | End | Previous: Chapter 14: Working With String Tables | Next: Chapter 16: Understanding Ebook Formats and Platforms