Documentation

E-book Standards

It is important to establish standards early on in the production process. These will ensure consistency throughout the project, reduce errors, and provide guidelines for future projects. Publishers may choose to establish the standards they follow for their publications based on their preferences and the type of material being presented. For any publisher who does not currently have in-house standards or would like to refer to Scribe’s standards, the following standards can be used.

Print Relics

In ScML files, it is standard practice to “comment out” print specific data found on the copyright page that does not pertain to the e-book. Opening and closing comment tags are <!-​- and -​-> respectively in ScML files. It is preferable to comment out unneeded data rather than delete the information in case it is needed at a later time. Below are several examples of print relics that can be commented out in the ScML.

  • Print ISBN: <!-​-<crtf>ISBN 978-1-23456-789-0</crtf>-​->
  • Manufacturer information: <!-​-<crtf>Printed in the United States</crtf>-​->
  • Printing numbers: <!-​-<crtf>10 9 8 7 6 5 4 3 2 1</crtf>-​->
  • Paper information: <!-​-<crtf>This Book is Printed on Recycled Paper</crtf>-​->
  • Typeset information: <!-​-<crtf>This book was typeset using the Arial font.</crtf>-​->

Print Page References

Avoid referencing print page numbers when possible. If they must remain, they should be linked to the corresponding internal print page ID.

ISBNs

Adding e-ISBNs

Scribe’s standard is to keep the print ISBN live and to add the e-ISBN to CIP page.

If available, ISBNs for the e-book editions should be added to the copyright page below the print ISBN in the ScML.

When there is no print ISBN listed on the copyright page, e-ISBNs are commonly added before the Library of Congress data.

If there are ISBNs for both the ePub and Kindle versions of the e-book, both should be listed on the copyright page.

<crtf>ISBN: 978-1-23456-789-0 (Print)</crtf> <crt>ISBN: 978-1-23456-789-0 (ePub)</crt> <crt>ISBN: 978-1-23456-789-0 (Kindle)</crt> <cipf>Library-in-Congress Publication Data</cipf>

Print ISBNs

The print ISBN should be included in the metadata and is essential for accessibility and establishing the relationship between the print pagination and ePub page IDs.

Half-Title Pages

If there are two half-title pages, Scribe recommends commenting out the second half-title page.

When commenting out a half-title page, the opening and closing <chapter> tags must also be commented out.

Multiline comments can be handled in one of two ways:

  • Comment out each line.

<!-​-<chapter id=”bkht”>-​-> <!-​-<bkht>Half-Title</bkht>-​-> <!-​-</chapter>-​->

  • Comment out multiple lines in one set of comment tags.

<!-​-<chapter id=”bkht”> <bkht>Half-Title</bkht> </chapter>-​->

Fonts

In e-book files, fonts should only be used for character support (that is, to display characters that the e-reader cannot display using its built-in fonts).

Fonts should not be used to match the rendering/display of the print book.

Because e-readers have their own built-in fonts, any print-specific fonts that are used in the e-book will generally not be displayed. While some e-readers do have an option to display the e-book as intended, including fonts, by the publisher, this is not the default option and will not be seen by most readers.

Fonts must be licensed for use in e-book files (with the exception of open source fonts). Because fonts must be specifically licensed for the e-book and because most e-readers will not display those fonts unless specifically told to do so by the reader, it is standard practice not to include print-specific fonts.

Directional Language

It is common practice to replace directional language in the ScML for images when the directional language no longer corresponds to the layout of the e-book.

Example: If, in the print edition of the book, two images were displayed side-by-side and the figure’s caption read “See Figure A [right] and Figure B [left],” this directional language might change.

In the e-book, those same images would most likely be stacked on top of each other and the “right” and “left” part of the caption would no longer apply. In this case, the “right” and “left” text would be commented out and replaced:

  • Original: <figcap>See Figure A (right) and Figure B (left)</figcap>
  • Replacement: <figcap>See Figure A (top<!-​-right-​->) and Figure B (bottom<!-​-left-​->)</figcap>

If a caption refers to side-by-side images that are no longer displayed that way in the e-book, it is best if a unique caption can be used for each image.

Right-to-Left Languages

For a book containing Hebrew or other right-to-left reading characters, the text may need to be replaced with images in order to display properly on all e-readers.

In the ScML file, comment out (do not delete) the Hebrew text when including the images.

See Hebrew Images for more information on how to create images for use in e-books.

Accessibility Metadata

Scribe recommends adding basic accessibility metadata to every epub. That is available within the extended metadata section in Digital Hub records.

A typical, basic set of accessibility metadata would look like this: <meta property="schema:accessMode">textual</meta> <meta property="schema:accessMode">visual</meta> <meta property="schema:accessModeSufficient">textual,visual</meta> <meta property="schema:accessibilityFeature">tableOfContents</meta> <meta property="schema:accessibilityFeature">readingOrder</meta> <meta property="schema:accessibilityFeature">printPageNumbers</meta> <meta property="schema:accessibilityFeature">index</meta> <meta property="schema:accessibilityFeature">structuralNavigation</meta> <meta property="schema:accessibilityFeature">displayTransformability</meta> <meta property="schema:accessibilityHazard">none</meta> <meta property="schema:accessibilitySummary">This publication conforms to the EPUB Accessibility specification at WCAG Level A.</meta>

Note: The accessibility feature "captions" refers to text content associated with embedded audio/video, not traditional figure captions that use figh and figcap styles in ScML.

Small Caps and Italic toc.xhtml and ncx Text

Small caps/italics do not work in toc.xhtml or ncx.

Consider adding punctuation.

Note: Small caps are not universally supported in toc.xhtml files (device side navigation). Using title case is the recommended approach to work around this issue.