Contents | Start | End | Previous: Chapter 8: Creating Your Cover Design | Next: Chapter 10: Working With Pictures

Chapter 9: Understanding Configurations

Ebook publishers often have slightly different requirements, even if the same format is used. You may also wish to tailor Jutoh’s output for your own reasons. Jutoh’s configuration feature lets you change the way that ebooks are generated, so that you can tweak the output for one format or ebook platform without affecting others. You may not need to worry about configurations for a bit but once in a while you may come across the need to change configurations or even add new ones; so it’s worth at least scanning this chapter so you know where to look.

Configuration basics

At first glance, ‘configuration’ seems like a fancy name for ‘format’. In the Build tab of the Control Panel, before compiling, you select the appropriate configuration such as ‘Epub’ or ‘Mobipocket’, each of which is generally named after the format it targets.

However, configurations are much more than that. They contain a whole host of user-editable options that will be used for that configuration; and you can add as many configurations as you like. So, for example, you might like to have two Epub configurations, called ‘iBooks Epub’ and ‘Barnes & Noble Epub’, with slightly different behaviour for each.

A configuration can specify which cover design or style sheet to use – so you can have alternate versions of your book with different cover designs or formatting, without having to maintain different versions of the book.

Or you could have different configurations for generating images with different sizes, tailored for use on different kinds of reader device.

When you create a Jutoh project, Jutoh’s New Project Wizard presents you with the option to create an initial set of configurations, one per format supported. Generally you can leave the defaults as they are unless you know you definitely won’t need some of them. Later, you can add, change and delete configurations.

Important note: although you can enable different formats in the same configuration, don’t be tempted to do this for generating, say, Epub and Mobipocket files from the configuration. Jutoh optimizes these formats differently, so you need to use independent configurations.

Editing configurations

To edit a configuration, you can click on Edit on the toolbar to show the Project Properties, and then click on Configurations. Or, you can click on the Edit button next to the drop-down list of configurations in the Control Panel; this will show you the currently-selected configuration.

The Configurations page in the Project Properties dialog

Configuration properties are presented in a scrolling list, with names on the left and editable values on the right. Click on a property to see its description, displayed under the list. You can double-click on some properties (such as Notes) to show a larger text editor. To make it easier to find properties, you can type all or part of the property name in the search box at the bottom of the window; use the left and right arrows to cycle through the matches, selecting each matching property in turn. You can press the Return key to give the keyboard focus back to the property editor.

You can add a new configuration by clicking on Add – you will be given the option of basing the new configuration on an existing one (the values will be copied to the new configuration) or creating a configuration with defaults appropriate to the selected ebook format. You can delete the selected configuration with Delete , and change its name with Rename . If you want to apply the same configuration settings to a different project, you can Save selected configurations to a file and then Load them in the other project. Use the up and down arrows to reorder configurations in the list.

Using configurations

You can select the current configuration in the control panel to the left of the Jutoh editor. This configuration will be used to determine paths and other settings for Compile, Check and Launch commands.

To compile a book using the current configuration, click on the Compile button on the Control Panel, or click on the Compile button on the toolbar, or use Book | Compile menu command, or use the F7 keyboard shortcut. If you prefer, you can compile using multiple configurations in one go, using the Book | Batch Compile command; a choice of configurations to use is presented, as shown below.

Batch Compile dialog

Note that if you use the File | Export menu command to quickly export your book to a specified format, any formats specified in the currently selected configuration are temporarily overridden. All the other settings in the current configuration will be used for the export, so normally it’s best to select the best configuration for the job and press Compile.

Update Special Book Sections dialog

If any of these special sections are out of date since the last compile (for example, you added headings, index entries or footnotes), you can show this dialog using Book | Update or F9, and click Update to update all checked special sections. Note that you can also elect to automatically update these sections when you compile (via controls in the Project Properties dialog), so you can be sure they are always up-to-date.

Configuration categories

Let’s look at the property categories in detail.

Locations

This category contains location-related properties. Usually you don’t need to edit these.

• Book folder: used to specify the folder in which the ebook for this configuration will be generated. The folder containing the project will be substituted for the keyword %FOLDER%, which is the default value.

• Book file name: this is %FILENAME% by default; you might want to change the name if you have multiple configurations for the same format. Note that an appropriate extension will be appended so you don’t have to include that in your file name value. For example, if your project is called MyBooks, you could use ‘%FILENAME%_ibooks’ to specify ‘MyProject_ibooks.epub’.

• Section file name: the file name to use for each section. Use %SECTIONNAME% to include the document name, %SECTIONNUMBER% to include a generated number, %SECTIONFILENAME% to include a user-defined file name, %PROJECTTITLE% to include the book title, and %PROJECTFILENAME% to include the project file name. Example: %PROJECTFILENAME%-%SECTIONNUMBER%-%SECTIONNAME%

• Preview file name: this is only used for the HTML format where there may be multiple files generated, and indicates which file should be used when previewing (launching) the generated book.

This category contains just one property, Identifier.

• Identifier: the unique identifier for your book. If the Identifier metadata field is left empty, the identifier for the current configuration is used. Note that initially, Jutoh generates a different UUID for each configuration.

Formats

Each configuration should have at least one format checked. You can have multiple formats checked, but this is not usually desirable. The one case where you might like to do that is in your Mobipocket configurations; if you also check Epub you will be able to check and view the source for your Mobipocket books.

These are the supported formats:

• Generate Epub: generates Epub 2 output, or Epub 3 if Epub version is set to 3.

• Generate Mobipocket: generates Mobipocket output, suitable for Amazon Kindle devices and software.

• Generate ODT: generates OpenDocument Text, a word processor format that can be converted to many other formats such as Word, using for example the free LibreOffice or OpenOffice.org suite. Note that Word itself tends to create more compact .doc files than does LibreOffice or OpenOffice.org, so you might want to re-save the file using Word if file size is an issue.

• Generate text: generates a single plain text file with no graphics.

• Generate HTB: generates a wxWidgets Help file, a simple zipped, HTML-based format (Jutoh Plus only).

• Generate CHM: generates a Windows Help file (Jutoh Plus only).

• Generate MP3: generates MP3 files if you select a suitable voice engine and install the LAME MP3 encoder in Preferences (MP3).

• Generate HTML: generates a series of XHTML files. Book navigation controls can be enabled via properties in the “Navigation” category below.

• Generate CBZ: generates a CBZ comic zip archive containing images. It is supported by fixed layout projects only.

Cover Design

This category gives you control over the way Jutoh generates the cover design and cover page for your book.

• Cover design: specifies the cover design to be used in this configuration.

• Cover page background colour: specifies an optional background colour for the XHTML page that contains the cover (Epub only). This RGB value should contain six hexadecimal digits, two digits per colour. To edit the colour, double click on the property name or click on the ‘...’ button. You might like to provide a background colour chosen from the cover image for filling in the area around the image.

• Generate cover page: check to generate an XHTML cover page for the book. Not recommended for Mobipocket.

• Expand cover to fit page: check to have the cover expand to the page height (the default).

• Include cover in NavMap: check to include the cover in the navigation map – not recommended.

• Exclude cover from reading order: check to hide the cover from the linear reading order (linear=no in the spine) – recommended. If this option is checked, the cover page may not be shown as part of the book – for example, in iBooks, the cover will only appear on the bookshelf. If you want the reader to be presented with the cover page first instead of the title page, clear this option. Don’t clear this for Mobipocket files, however. Note that Calibre has an unusual interpretation of exclusion from reading order and shows such sections at the end of the book.

• Cover image format: specifies the image format for the cover design. If ‘Original’ is specified, and the cover design has only one image object (for example, it was created from an existing cover image file), then the original file is used without change.

• Cover image width: specifies the cover image width in pixels, or -1 to use the default cover design width.

Options

This category contains miscellaneous options controlling how Jutoh generates ebook output.

• Generate title page: check to generate a title page for the book. It’s usually better to create your own by hand.

• Generate table of contents: check to generate a table of contents page for the book, either automatically (it will not be visible in the project) or manually whenever you run the TOC wizard (it will be visible in the project).

• Generate NCX: check to generate a logical table of contents, or NavMap (NCX). This should only be disabled for Epub 3 files, where it is optional.

• Force simple NavMap: check to force Jutoh to generate a simple NavMap based on section titles, regardless of other settings. Any custom HTML table of contents page will not be affected. This option is useful for Lulu, which has trouble with NavMaps that contain bookmarks.

• Generate page list: check to generate an NCX page list for Epub 2 or nav page list for Epub 3, using page objects embedded in the book. This will work with iBooks.

• Generate Adobe page map: check to generate an Adobe page map file for Epub 2 books, using page objects embedded in the book. Note that EpubCheck will not pass an Epub 2 file with the Adobe page map extension.

• Generate cross-reference page numbers: check to output page numbers in cross-references, instead of ‘here’.

• Generate guide: check to generate a guide section in the OPF file – recommended.

• Generate title tag: check to generate a title tag for each HTML file.

• Optimize for iBooks: various optimizations are applied. In particular, dummy spans are added to centred paragraphs in order to fix centering in full justification mode. Use Generate font names to determine whether the specified-fonts option will be switched on in the iBooks XML file, or whether font names will be suppressed. This option will cause a file called com.apple.ibooks.display-options.xml to be added to the Epub file, under the folder META-INF. If you submit the Epub to Lulu, this may cause an “unmanifested file” error, so clear this option for Lulu submissions.

• Generate iBooks XML: if this option and Optimize for iBooks are both checked, generates the file com.apple.ibooks.display-options.xml when necessary.

• Optimize for Mobipocket: anchors are inserted before paragraphs to prevent style loss on navigation (as recommended by Amazon guidelines), and no paragraph tags are used within a list item.

• KF7 compatibility: compatibility with KF7, the less-capable predecessor to the Kindle KF8 format. Specify comma-delimited options from: all, none, table, tablespacing, tableborder, tablesize, tablealignment, tablecolour, list, paragraph, image. By default, this is set to all, meaning that the maximum amount of KF7 compatibility will be kept. This can potentially interfere with optimal KF8 output (for example, guessing table borders which are specified differently in KF7) so you can switch all or some of this compatibility off. Very few KF7 devices remain in use, and even old devices such as the Kindle Keyboard have been updated to use KF8.

• Mobipocket anchor optimization: if cleared, and Optimize for Mobipocket is checked, anchors are no longer inserted before paragraphs. You might want to clear this if you have long paragraphs containing footnotes, for example, and want to achieve accurate navigation regardless of any styling side-effects that can be caused by bookmarks within paragraphs on the Kindle platform.

• Credit Jutoh: adds Jutoh as a book producer in the Epub/Mobipocket metadata.

• Start page guide type: specifies the guide type that will be substituted for %STARTPAGE% in a section’s guide type to indicate the first reading page. For iBooks, it is ‘other.reader-start-page’, and for Mobipocket, it is ‘text’. Note that the start page may not always be respected on Kindle.

• Visible URLs: specifies whether the URL will be added to the text, for printable documents. If ‘None’, no URLs will be added. If ‘Always’, the URL will always be added. If ‘Intelligent’, Jutoh will check whether the URL is already in the linked text.

• Generate URLs: Clear to remove all URLs from the content. This is useful when generating for print.

• Epub version: specifies the Epub version to generate.

• Suppress section breaks: suppress section breaks using one or more method, merging documents and avoiding mandatory page breaks. Works for Epub, Mobipocket and OpenDocument. Values can be: ‘(none)’, ‘styles: <style spec>’, ‘avoid-page-break: true’, ‘document-depth: <depth>’. You can use multiple values separated by a semicolon. Please see KB0224 for more information.

Styles

This category controls style-related options. More about styles can be found in Chapter 12: Working With Style Sheets.

• Style sheet: specifies the style sheet to be used in this configuration.

• Paragraphs to exclude: the comma-separated paragraph styles whose paragraphs should be excluded from the book. You can use * to mean all characters, for example ‘Only*’ will cause all paragraphs with a style name beginning ‘Only’ to be excluded, except for those specified in Paragraphs to include. For examples, see Chapter 12: Working With Style Sheets.

• Paragraphs to include: the comma-separated paragraph styles whose paragraphs will be exempt from exclusions. You can use * to mean all characters. For example, if this property has the value of ‘Only Epub’, paragraphs styles with ‘Only Epub’ will be retained, but (assuming ‘Only*’ in Paragraphs to exclude), all other paragraphs whose style name begins with ‘Only’ will be removed. Thus you can include or exclude paragraphs in your document depending on the configuration. For examples, see Chapter 12: Working With Style Sheets.

• First paragraph style: the style to use for first paragraphs after a heading when importing into an existing project from plain text, HTML or Epub.

• Normal paragraph style: the style to use for normal paragraphs when importing into an existing project from plain text, HTML or Epub.

• Chapter heading paragraph style: the style to use for chapter headings when importing into an existing project from plain text. Only relevant if you have Take title from first line of text files switched on in Project Properties/Options.

• Character style substitutions: semicolon-separated character style substitutions, for example ‘Drop Caps: Drop Caps Epub; Emphasis: Red Emphasis’. This allows you to adjust styles per configuration without needing to use a different sheet.

• Paragraph style substitutions: semicolon-separated paragraph style substitutions, for example ‘Normal: Normal Justified; Centred: Centred Bold’. This allows you to adjust styles per configuration without needing to use a different sheet.

• Box style substitutions: semicolon-separated box style substitutions, for example ‘Box Style: Scaled Box Size’. This allows you to adjust styles per configuration without needing to use a different sheet.

• Heading style prefix: a prefix for determining whether a style is a heading for the purposes of HTML generation. The default is ‘Heading’. Clearing this field will prevent Jutoh from generating <h> tags. Multiple patterns containing wildcards (‘*’ and ‘?’) can be separated by the pipe character (‘|’). The heading level is determined from the outline level in the matching style. Or, the heading level is determined by a number following the prefix.

• Styles suppressing hyphenation: a pattern matching all styles that should suppress hyphenation. Multiple patterns containing wildcards (‘*’ and ‘?’) can be separated by the pipe character (‘|’). For example, ‘Heading*|Book Title’. This works for Epub only, and generates the extra CSS adobe-hyphenate: none; hyphens: none;.

• Styles suppressing page break before: a pattern matching all styles that should suppress a preceding page break. Multiple patterns containing wildcards (‘*’ and ‘?’) can be separated by the pipe character (‘|’).

• Styles suppressing page break after: a pattern matching all styles that should suppress a following page break. Multiple patterns containing wildcards (‘*’ and ‘?’) can be separated by the pipe character (‘|’).

• Preformatted paragraph styles: a pattern matching all paragraph styles that mark text as preformatted. Multiple patterns containing wildcards (‘*’ and ‘?’) can be separated by the pipe character (‘|’).

• Code character styles: a pattern matching all character styles that mark text as inline code. Multiple patterns containing wildcards (‘*’ and ‘?’) can be separated by the pipe character (‘|’).

• Verbatim paragraph styles: a pattern matching all paragraph styles that mark text to be output verbatim, for example raw HTML. Multiple patterns containing wildcards (‘*’ and ‘?’) can be separated by the pipe character (‘|’).

• Verbatim character styles: a pattern matching all character styles that mark text to be output verbatim, for example raw HTML. Multiple patterns containing wildcards (‘*’ and ‘?’) can be separated by the pipe character (‘|’).

• Blockquote paragraph styles: A pattern matching all paragraph styles that indicate a blockquote. Multiple patterns containing wildcards (‘*’ and ‘?’) can be separated by the pipe character (‘|’).

String Tables

Jutoh’s string tables feature allows customisation of metadata, cover design text and book content per-configuration, by substituting one string for another. This category controls how the configuration uses existing string tables. For more information, see Chapter 13: Working With String Tables.

• Project string table: specifies the project string table to be used in this configuration, if any. Project strings override global strings.

• Global string table: specifies the global string table to be used in this configuration. Project strings override global strings.

• Replace strings in content: check to replace strings in book content as well as metadata and cover designs.

HTML Formatting

This category contains various options used for HTML-based formats.

• HTML version: specifies how HTML code will be generated. If this value is ‘(auto)’, the value will be deduced from other settings.

• Use XHTML: specifies whether XHTML or HTML will be generated. If this value is ‘(auto)’, the value will be deduced from other settings.

• Relaxed HTML: if checked, some HTML 5 (Epub 3) tags will be permitted in HTML 4 (Epub 2), such as wbr. Note that this is likely to cause EpubCheck to fail.

• Single HTML page: check to generate a single HTML page.

• HTML left margin: sets a global left margin for Epub and HTML formats (not Mobipocket). Examples: 3%, 10mm, 0.2in, 20px. To remove the margin, clear the value.

• HTML right margin: sets a global right margin for Epub and HTML formats (not Mobipocket). Examples: 3%, 10mm, 0.2in, 20px. To remove the margin, clear the value.

• HTML top margin: sets a global top margin for Epub and HTML formats (not Mobipocket). Examples: 3%, 10mm, 0.2in, 20px. To remove the margin, clear the value.

• HTML bottom margin: sets a global bottom margin for Epub and HTML formats (not Mobipocket). Examples: 3%, 10mm, 0.2in, 20px. To remove the margin, clear the value.

• Body CSS: Sets the CSS to be written to the global CSS style sheet. It can contain CSS for the body element, or other definitions. You can use this to provide default values for attributes not specified by paragraph styles. Example: ‘body { margin: 0 5pt }’.

• Styles for indent fix: specifies the styles whose left indent should be converted to a first-line indent, to fix the lack of full left indent support on Mobipocket (only). By default this is ‘TOC*’. To stop any such conversion, clear this setting. You can use star (*) to match multiple characters in the style name.

• Dimension units: choose the units to use for non-font dimensions such as margin and size. Some platforms require pixel units for fixed layout books. If you specify ‘Default’, Jutoh will decide what units to use.

• Paragraph dimension units: choose the units to use for paragraph dimensions such as indentation and spacing. Some platforms require pixel units for fixed layout books. If you specify ‘Default’, Jutoh will decide what units to use.

• Font size units: choose the units to use for font sizes. Some platforms require pixel units for fixed layout books. If you specify ‘Default’, Jutoh will decide what units to use.

• Font size adjustment: specify an increment in points to add to all font sizes. You might use this to generate large print books.

• Font pixel scale: when fonts are specified in pixels, the size shown in Jutoh can differ from pixel size as rendered in HTML. This scale factor helps to compensate for this difference.

• RTL direction: sets all paragraph styles to have right-to-left text direction.

• RTL page direction: check to set the page progression direction to right to left, for Epub 3 books.

• URL attribute removal style: specifies the character style containing URL attributes to remove, so that only the default link attributes specified by the book reader software (or in custom CSS) will be used. For example, if you specify ‘URL’ in this property containing blue and underlining attributes, then blue underlined links will have both attributes removed in the final book. However if a link was styled with red, then the red colour will be retained, and just any underlining removed. If this property is set to ‘(none)’ or left empty, then no attribute removal will be done.

• Use heading text size: if enabled, text sizes will be written for styles that match Heading style prefix. Clear this to use the ebook viewer’s default heading sizes.

• Preserve spacing after page break: if enabled, an invisible separator will be generated to preserve spacing after a page break that is usually lost. See also KB0173.

• Generate line spacing: if enabled, line spacing will be written where specified. Removing line spacing can improve ebook formatting.

• Abbreviate style names: if enabled, style names in the HTML and CSS files will be abbreviated instead of being derived from the original style names.

• Optimize style sheet: if enabled, Jutoh will remove unused styles from the generated style sheet. This works for Epub, Kindle, HTML and ODT.

• Emulate small caps: if enabled, Jutoh emits actual capitals and a smaller font size, for viewers such as ADE that ignore the font-variant attribute. On by default.

• Superscript CSS: custom CSS for implementing superscript.

• Subscript CSS: custom CSS for implementing subscript.

• Drop caps CSS: custom CSS for implementing drop caps. Replace the variables with specific values if you wish; otherwise, Jutoh will replace them with suitable values for the target format and drop caps size.

• Convert horizontal bar to em dash: converts Unicode 8213 (horizontal bar) to Unicode 8212 (em dash) and adds a non-breaking span. Some Epub viewers, such as Adobe Digital Editions, do not support horizontal bar, and it is essential punctuation for Spanish. For the non-breaking behaviour to work, the bar and non-space character to the left or right of the bar must be formatted in the same (or no) character style.

• Convert non-breaking hyphen to hyphen: converts Unicode 8209 (non-breaking hyphen) to an ordinary hyphen and adds a non-breaking span. Some Epub viewers do not support a non-breaking hyphen. For the non-breaking behaviour to work, the hyphen and non-space character to the left or right of the hyphen must be formatted in the same (or no) character style.

• Add thin spaces around punctuation: inserts non-breaking thin spaces around punctuation to conform with typographical convention for French books. If there is white space already in position, it is replaced by the thin space, but existing white space is not necessary.

• Thin space entity: the HTML code to use for a thin space. By default, it is &thinsp;. Not all fonts support this entity; you can sometimes work around it for Epub files by embedding a font that supports it. Some but not all Kindle devices will render it correctly. Or, you can use an image instead, although this can slow down rendering considerably. This code will insert an image (you should also add a media document with a suitable small, white bitmap):
<img width=4 style="width:4px;" src="media/emptybitmap4x1.png" alt=""/>

• Orphan control for single-letter words: inserts non-breaking spaces after single-letter words to avoid orphan words at the end of lines.

• Character substitutions: semicolon-separated pairs of decimal Unicode substitutions. For example the value ‘8239:160;8201:160’ would convert two kinds of thin space to non-breaking spaces.

• Use div tag: determines whether the div tag is used instead of p.

• Extra metadata: extra meta elements for the metadata section of the Epub or Mobipocket OPF file.

• Widow control: a widow is the last line of a paragraph appearing alone at the top of a page. This option specifies the minimum number of lines of a paragraph that appear at the top of a page. Use ‘Default’ to use the ebook defaults, ‘None’ to switch off widow behaviour, or a number for the minimum number of lines.

• Orphan control: an orphan is the first line of a paragraph that appears on its own at the bottom of a page. This option specifies the minimum number of lines of a paragraph that must appear at the bottom of a page. Use ‘Default’ to use the ebook defaults, ‘None’ to switch off orphan behaviour, or a number for the minimum number of lines.

• Namespaces: specifies the XHTML namespaces. Specify ‘auto’ to have Jutoh use the namespaces appropriate to the current Epub version.

• Epub package prefix: specifies the value of the prefix attribute for the OPF package element.

• Table headers and footers: check to emit headers and footers if specified in individual tables. Most readers cannot make use of this option.

• Emulate boxes using tables: check to emulate boxes by using one-cell tables, for platforms such as Kindle for iOS that do not support boxes.

• Avoid breaks in tables: check to avoid page breaks within tables, where possible.

• Use minimum size for cells: check to use min-width and min-height instead of width and height in table cells, for better ADE compatibility. If absolute sizes are used, content can overspill cell boundaries in ADE.

• Maximum table rows for inline-block: the maximum number of table rows before Jutoh no longer uses the ‘display:inline-block’ attribute for the table. While this attribute is useful for centering tables in Adobe Digital Editions, it stops Adobe Digital Editions rendering long tables. Set to zero to never use inline-block.

• Maximum box words for inline-block: the maximum number of words in a text box before Jutoh no longer uses the ‘display:inline-block’ attribute for the box. While this attribute is useful for centering boxes in Adobe Digital Editions, it stops Adobe Digital Editions rendering long boxes. Set to zero to never use inline-block.

• Omit box height: check to omit the height value from text boxes, since specifying the height can cause content overflow.

• Popup footnotes: check to show footnotes in a popup window.

• Hide footnotes: check to hide footnotes by using ‘aside’ tags. The ‘Popup footnotes’ option must be checked.

• Use default list indentation: uses default list indentation to work around bugs in some readers when specifying custom indentation, especially on Kindle. Custom list indentation is ignored. This is enabled for new Mobipocket configurations.

Text Formatting

This category contains options for plain text (including Markdown) and ODT (OpenDocument Text) output.

• Text syntax: specifies what kind of text to output.

• Text packaging: specifies the kind of packaging to use for the text files. ‘Single file’ generates a single text file containing all the content, ‘Multiple files’ generates a file for each section, ‘Zip’ archives multiple files in a zip file, ‘TextPack’ creates a Markdown text pack.

• Text file extension: specifies the text file extension.

• Wrap paragraphs: check to wrap paragraphs at the maximum number of characters per line, for text output only.

• Add blank lines: check to add blank lines between paragraphs, for text output only.

• Characters per line: the maximum character per line if wrapping, for text output only.

• Left margin: the left page margin in mm, for ODT output only.

• Right margin: the right page margin in mm, for ODT output only.

• Top margin: the top page margin in mm, for ODT output only.

• Bottom margin: the bottom page margin in mm, for ODT output only.

• Paper size: the paper size, for ODT output only. The default is A4.

• Custom paper width: the custom paper width, for ODT output only. Specify mm (the default), cm or in. If custom width and height are both specified, the values will override the Paper size selection.

• Custom paper height: the custom paper height, for ODT output only. Specify mm (the default), cm or in. If custom width and height are both specified, the values will override the Paper size selection.

• Mirror margins: check to mirror page margins, for example when creating a gutter for print on demand. For ODT output only.

• Dots per inch: the assumed number of dots per inch for images, used if no absolute dimensions are specified. For ODT output only. The default is 96.

• Add blank paragraphs for Word: if checked, Jutoh will add blank paragraphs before page breaks for Microsoft Word compatibility. Without it, justification is poor before page breaks. For ODT output only.

• Line numbering: if checked, Jutoh will generate line numbers based on settings in Project Properties/Page Layout/Line Numbering. For ODT output only.

Images and Media

This category contains options allowing you to control various aspects of image (picture) output. For more about images, see Chapter 10: Working With Pictures.

• Maximum image width: the maximum image width to use in your book. Specify -1 for no scaling. Note that this physically scales the image before it is written to the ebook, rather than simply setting the max-width CSS property. In contrast, Limit images to viewer size sets the max-width and max-height properties so scaling is done dynamically.

• Maximum image height: the maximum image height to use in your book. Specify -1 for no scaling. As with Maximum image width, this physically scales the image.

• Maximum image width units: units for the maximum image width and height – pixels or percentage.

• Maximum image optimization width: maximum image width to optimize; -1 for no optimization. Optimization improves quality for smaller images, but takes longer.

• Limit images to viewer size: whether to limit images to the maximum width and height of the viewer (Epub format only). Images smaller than the viewer size will show at their original size. The setting works by adding max-width:100% and max-height:100% styles, unless overridden by individual image settings. Note that some viewers, such as Nook, Aldiko and ADE, erroneously expand images that have their maximum width or height set. The fix is to specify the width (and/or height) in pixels or other units in the image properties. For example, if the image is 300x500, specify 300px in the Width field.

• Replace absolute widths: if enabled, absolute widths in cm are replaced with percentage widths more suited to ebook displays. This applies to images, boxes and tables. The current paper size and left and right margins, or the parent box dimensions, are used to calculate an appropriate percentage. Images within tables or boxes are not affected since the percentage width refers to the parent container and not the display.

• Maximum percentage width: the maximum permissable percentage width relative to the display when using the Replace absolute widths option. Some viewers may not accept 100% without part of the object being off-screen.

• Flatten images: whether to flatten (remove alpha channel from) any images containing alpha transparency. Specify (none) for no flattening, Parent to get the colour from a parent box or table, or a background colour: White, Black or a six-digit hexadecimal number preceded by ‘#’.

• Convert images to JPEG: whether to convert non-JPEG images to JPEG for reduced file size. Specify ‘None’ to leave the images in their original format, ‘All’ to convert all non-JPEG images, and ‘All except GIF’ to leave GIF files alone but convert the others. You can override conversion per image by checking Preserve original format in the Image Properties dialog.

• Image quality: the image quality when converting to JPEG, expressed as a percentage. Higher quality means larger file size; a good value for general use is 80%.

• Generate media objects: if enabled, any video and audio media files, and the tags that reference them, will be written to the book (XHTML formats only).

• Use specified image names: if enabled, names entered in the Image Properties dialog will be used to form image file names. It will be up to the user to specify unique filenames except where the same image is being used. Epub and Mobipocket only.

• Inline images: check to include images inline using base64 encoding instead of writing files. Applies to standalone HTML generation only.

• Use SVG images: check to use SVG vector image alternatives where specified for each image. The SVG image should be added as a media object, and Generate media objects should be enabled. XHTML formats only.

• Drawing object formats: choose which formats will be used for drawing objects in this configuration. You can specify the formats to be used for all drawing objects, or you can specify by object tag; for example ‘math:bitmap,mathml;drawing:svg;default:bitmap’.

• SVG drawing method: choose the SVG code generation method for drawing objects, where not specified for the drawing object. One of ‘inline’, ‘img’, ‘object’ and ‘embed’.

• SVG conversion: When to convert an SVG image to a bitmap during compilation. By default, this is ‘Never’, although you can still convert SVG images interactively using Book | Update.

• SVG conversion scaling: How to scale an SVG image when converting to a bitmap. Specify size thresholds for scaling factors in the form <WIDTH:*SCALE separated by semicolons. For example, if set to ‘<10000:*1;<100:*2;<64:*4;<32:*8’, an SVG that is 32px wide will be scaled to 32*4=128px wide. This only takes place for SVG images that provide a pixel width and height.

• SVG conversion custom options: Custom options that will be passed to the conversion utility. If specifying a custom command in Preferences/Helpers, the %CUSTOMOPTIONS% keyword will be replaced by this value.

• Strip MathML namespace prefixes: check to remove namespace prefixes from MathML since some renderers have trouble with them.

• MathJax script: specify a MathJax script to include if targeting a renderer that does not implement native MathML support.

This category contains options for controlling the way special formatting is output – whether to use special fields for the word processor to use, or by generating the content explicitly.

• Special index formatting: check to output index entries as special items, if supported by the target format. If this option is cleared, links and an index page will be output explicitly. Smashwords ODT requires this to be switched off.

• Special footnote formatting: check to output footnotes and endnotes as special items, if supported by the target format. If this option is cleared, linked footnotes or endnotes will be output explicitly. Smashwords ODT requires this to be switched off.

• Special table of contents formatting: check to replace the document marked with the ‘toc’ guide type with a special ‘tableofcontents’ field in ODT export. This will ensure that the ODT table of contents has page numbers and not just links. Smashwords ODT requires this to be switched off.

• Special bibliography formatting: check to output special citation fields, rather than expanding citations into text. Smashwords ODT requires this to be switched off.

• Special cross-reference formatting: check to output special cross-reference fields, rather than expanding cross-references into text. Smashwords ODT requires this to be switched off.

• Use outline levels: check to output outline levels if specified in your heading styles. Currently applies to ODT output only, where checking this option allows a table of contents to appear in PDF files generated by OpenOffice.org Writer or LibreOffice Writer.

• Use page styles: check to output page styles, if defined. ODT only.

Chapter Separators

This category controls the output of textual separators between sections. By default there are no separators.

• Add chapter separators: check to output an extra paragraph at the end of each chapter, to visually separate one chapter from the next.

• Chapter separator text: the text to add at the end of a chapter.

• Chapter separator style: the paragraph style of the text to add at the end of a chapter.

Fonts and Colour

This category contains options related to font handling.

• Embed fonts: check to embed any fonts listed under Resources.

• Obfuscate fonts: lightly encrypt embedded fonts by mangling them with an algorithm that ties the font to the ebook file. Jutoh uses the IDPF method, which is the most widely used.

• Font substitutions: semicolon-separated font substitutions, for example ‘Times New Roman: Deja Vu Serif, Times New Roman; Arial: Deja Vu Sans’. This allows you to use embedded fonts in place of the font specified in your book, and you can use a list of comma-separated names for fallbacks. This only works for XHTML-based formats, and not on all ebook platforms.

• Generate font names: clear this to use the reader default font name. If checked, enables the specified fonts in iBooks (specified-fonts option in com.apple.ibooks.display-options.xml).

• Generate generic font names: clear this to avoid generating generic font names for HTML-based formats. The generic names are serif, sans-serif, cursive, fantasy, monospace. If you disable both this and Generate font names, no font-family attribute will be written to the CSS.

• Styles with font names: Specify any styles that should have their font names written to CSS regardless of other font options. Multiple patterns containing wildcards (‘*’ and ‘?’) can be separated by the pipe character (‘|’).

• Styles with generic font names: Specify any styles that should have their generic font names (such as ‘sans-serif’) written to CSS regardless of other font options. Multiple patterns containing wildcards (‘*’ and ‘?’) can be separated by the pipe character (‘|’).

• Generate colour: clear this to avoid generating any colour style information.

Mobile

This category contains options for tailoring the way HTML pages are displayed in mobile devices.

• Enable viewport: enables viewport meta tag for mobile browsing (HTML and Epub formats only).

• Viewport content: the content of the viewport meta tag for mobile browsing (HTML and Epub formats only). The default value is ‘initial-scale=1.0, maximum-scale=1.0, user-scalable=no, width=device-width’ which keeps the formatting appropriate to the width of the device.

Fixed Layout

This category contains options relating to fixed layout ebooks. Currently, fixed layout books are supported on iBooks, Kindle and Epub 3. For more information, see Chapter 18: Creating Fixed Layout Books.

• Enable fixed layout: this should always be enabled for fixed layout books.

• Allow reflowable and fixed layout: check this if your book contains reflowable and fixed layout content. The mainstream platforms (iBooks, Kobo, Kindle) don’t allow mixing types of content, but Epub 3 allows it.

• Orientation lock: whether the book will be locked in portrait or landscape mode. This doesn’t refer to the actual aspect ratio of an individual page: this is entirely up to you.

• Pages per spread: how many pages (HTML files) will be created per double-page spread. This may differ from the way you created your pages – Jutoh will split or merge pages accordingly.

• Synthesize spreads: whether left and right pages should be ‘stuck together’ to form a seamless spread, or whether the pages should be shown as being separate (even if next to each other). If not ‘Default’, this setting overrides individual page settings.

• Page width: the overall width of the book. This may be different from your individual page sizes if the Pages per spread setting indicates that Jutoh should split or merge pages.

• Page height: the overall height of the book. Currently Jutoh doesn’t split or merge pages in the vertical direction so this should always be the same as your page heights.

• Book type: this is only used for Kindle and need not be set; if you select ‘comic’, it enables automatic zooming facilities on some Kindles and changes the rendering of double-page spreads. There may be rendering side-effects when specifying a book type, so test the book carefully. Please see the notes below regarding setting KF8 options.

• Open to spread: if checked, the book will open directly to a full-page spread. This is only applicable to iBooks.

• Show binding: if enabled, a binding crease will be shown in the middle of a double-page spread, in iBooks only.

• Write page image as background: if checked, the page background will be written using the background-image CSS property, which for KF8 will disable default zooming but will also prevent the background from being shown independently from the rest of the content when clicking/double-tapping on the background.

• Pre-render objects: if set to ‘Default’, any text or image objects that have Pre-render this object checked in their region properties (or inherited page or project properties) will be rendered to the background image instead of being written to the ebook as a separate object. If this option is ‘Always’, all objects will be pre-rendered, and if ‘Never’, no objects are pre-rendered.

• Font pixel scale: this option is in the HTML Formatting group rather than Fixed Layout, but it is useful for making the text size in ebooks closer to the size as shown in Jutoh. Try a value of 0.85 if the ebook text is too large. It is only used when font sizes are expressed in pixels. If your font sizes are in points, you can scale the text size in ebooks by setting the Custom DPI in Project Preferences/Options.

• Auto region magnification: for KF8 output only, this option enables Jutoh’s automatic generation of magnification regions for backgrounds, text objects and image objects. For more on this, see below. You may wish to switch this off if targeting e-ink Kindle devices since it can cause interruption of normal page navigation.

Speech

This category contains an option for determining which speech profile is used for this configuration. There is always at least one speech profile, which all configurations initially use.

• Speech profile: the speech profile to use, containing further options. Edit speech profiles in the Speech tab on the Formatting Palette.

This category contains options for tailoring the way navigation is supported in HTML pages (for the HTML format only). HTML templates specified here will be inserted into the HTML pages. Navigation controls can be placed at either the start or end of the page, or both. For each header or footer, there are three templates, to account for the fact that the presence of Next and Previous links will change according to whether you are currently viewing the first page, the last page, or the pages in-between. The default HTML templates give reasonable navigation between pages using text links; you could provide more fancy navigation, perhaps using images that you copy to the folder of HTML files after generation by Jutoh.

In the HTML templates, you can use these keywords: %TOCFILE%, %TOCTITLE%, %PREVIOUSFILE%, %PREVIOUSTITLE%, %NEXTFILE%, %NEXTTITLE%, %FIRSTFILE%, %FIRSTTITLE%, %LASTFILE%, %LASTTITLE%, %THISFILE%, %THISTITLE%. They will be replaced by the associated HTML file names and section titles.

• Enable HTML header: enables navigation controls at the top of each HTML page.

• Enable HTML footer: enables navigation controls at the bottom of each HTML page.

• HTML header first page template: specifies the HTML to be placed in the header, for the first page in the book.

• HTML header middle pages template: specifies the HTML to be placed in the header, for all but the first and last pages in the book.

• HTML header last page template: specifies the HTML to be placed in the header, for the last page in the book.

• HTML footer first page template: specifies the HTML to be placed in the footer, for the first page in the book.

• HTML footer middle pages template: specifies the HTML to be placed in the footer, for all but the first and last pages in the book.

• HTML footer last page template: specifies the HTML to be placed in the footer, for the last page in the book.

Conditional Sections

This category lets you include or exclude sections from the final ebook. Note that if you use these properties to change the way sections are included in your book, you will need to regenerate the table of contents, alphabetical index, and endnotes for each configuration since these will also change according to configuration.

The last two options act on condition objects that bracket conditional content. Condition objects contain a list of tags that are matched against these options to include or exclude the content.

• Include sections matching tags: enter a comma-delimited set of tags which match against tags specified in the Properties dialog for each section. For a given section, if any of the tags specified here are mentioned in its own tags, or this property is empty, the section will be included in the book.

• Exclude sections matching tags: enter a comma-delimited set of tags which match against tags specified in the Properties dialog for each section. For a given section, if any of the tags specified here are mentioned in its own tags, the section will be excluded from the book.

• Include media documents matching tags: comma-delimited tags matching tags of media documents that should be included. If no tags are specified, all media documents match.

• Exclude media documents matching tags: comma-delimited tags matching tags of media documents that should not be included. If no tags are specified, all media documents match.

• Include content matching tags: comma-delimited tags matching conditional content that should be included. If no tags are specified, all conditional content matches.

• Exclude content matching tags: comma-delimited tags matching conditional content that should not be included. If no tags are specified, all conditional content matches.

• Permit links to absent content: check to silently remove links to absent conditional content, for example if making a book sample. Off by default, in order to warn about missing links.

Commands

Sometimes you may wish to execute an external command before or after the compilation of your book. These properties allow you to specify such commands. Note that if executing a command using an interpreter such as Java or Python, you must specify the interpreter command in addition to the script to be executed.

Here’s an example command that runs the Kindlestrip program:

c:\python27\python.exe c:\apps\kindlestrip1.35\kindlestrip.py "%FOLDER%\%FILENAME%.%EXT%" "%FOLDER%\%FILENAME%_new.%EXT%"

• Pre-compile command: a command to execute before compilation. You can use the keywords %FOLDER%, %FILENAME%, %EXT% and %APPDIR%.

• Pre-compile command: a command to execute after compilation. You can use the keywords %FOLDER%, %FILENAME%, %EXT% and %APPDIR%.

• Upload book: check to upload the file to a device, folder or email account after compilation using applicable device profiles (edited via Preferences/Device Profiles).

• Device profiles: a comma-separated list of profile names to use for uploading the file. You can use star (*) to match multiple characters in the profile name. By default, any applicable device profiles will be used. You can edit device profiles via Preferences/Device Profiles.

• Comments to include: a pattern for including comments in the compiled book. Use wildcards to match against text, author and tags. Separate alternate values with commas. Examples: * (include all notes), none (include no notes), author:JS (match author JS), author:JS,AB;tags:todo (match where the author is JS or AB and the todo tag is present).

• Comment style: the character style to be used for comments.

• Comment content style: the character style to be used for marked up content referenced by comments.

• Special comment formatting: check to output comments in the native format where supported (currently ODT only). If this option is cleared, comments will be output as for other formats, interspered with the text and subject to the Comments to include option.

Checking

• Custom compile messages: Specify the names of find and replace preset libraries to be used for emitting messages during compilation. Prefix by ‘Global/’ or ‘Project/’. Multiple patterns containing wildcards (‘*’ and ‘?’) can be separated by the pipe character (‘|’). This is a Jutoh Plus feature.

General

These are the remaining options.

• Notes: a place to write notes about this configuration, which will be displayed when you click on the configuration.

• Use as preview configuration: if checked, this configuration will be used to generate the HTML for Section Preview, regardless of the configuration currently selected.

Summary

We’ve looked at configurations in some depth, and you should now know where to look when you wish to change the way Jutoh generates a particular ebook. Next, we go into the details of inserting, sizing and converting the pictures in your book.

Contents | Start | End | Previous: Chapter 8: Creating Your Cover Design | Next: Chapter 10: Working With Pictures