A guide for making Epub ebooks/publications, sufficient for most purposes. It requires understanding of XHTML, CSS, XML. (1900 words)
Download an example publication – this document as Epub: http://www.hxa.name/articles/content/EpubGuide-hxa7241.epub
This is a guide for making IDPF Epub ebooks/publications. It is mostly an annotated example: this document itself in Epub form.
Not all details/variations are mentioned, but enough to obviate need of the specifications for normal use. And it is for making entirely conformant publications.
Included also is a description of optional extra styling for a particular reader (but still completely conformant).
You need an understanding of and ability to make XHTML/CSS and XML documents.
‘Epub’ is a standard from the International Digital Publishing Forum. It is an arrangement of several other standards (mainly: XHTML, CSS, XML, NCX, DCMI). There are three parts, addressing: content, package metadata, and archive (OPS, OPF, and OCF). It is powerful, straightforward, and non-proprietary.
‘ADE’ is one of the first readers for Epub publications. It is very conformant with the standard. It can use an optional proprietary publication component: an extra stylesheet to adjust text-column appearance. (That is allowed by the standard.)
This guide was written using ADE version 1.0.467 .
Make the main content with XHTML, CSS, and images.
Relevant specifications: OPS, XHTML, CSS.
Use XHTML 1.1, but without the following modules:
(XHTML 1.1 difference from XHTML 1 strict:
lang
attribute not allowed (use xml:lang
instead)name
attribute on a
and map
elements not allowed (use id
instead)Include XML declaration and XHTML doctype, at the top:
<?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">
and xmlns
attribute in html
:
<html xmlns="http://www.w3.org/1999/xhtml">
Any unicode character, in UTF-8 or UTF-16, is allowed. But readers may have limited rendering capabilities.
(ADE 1.0 doesn't support: ­       ‌ ‍ ‎ ‏ ‾ ⌈ ⌉ ⌊ ⌋)
A subset of CSS 2.1 is supported. A brief summary is awkward to make. For details, see the CSS part of the OPS specification.
Be simple, and use CSS 1 without the following properties:
background-image
background-repeat
background-attachment
background-position
background
word-spacing
letter-spacing
text-transform
list-style-image
(There are also a few other minor details unsupported.) And don't use absolute positioning.
The CSS can be linked from the XHTML head
, or put in style
in head
.
(ADE 1.0 doesn't support:
text-align: justify;
font-variant: small-caps;
display: oeb-page-head;
display: oeb-page-foot;
oeb-column-number: [integer];)
The XHTML can have images of the following types:
image/jpeg
image/png
image/gif
image/svg+xml
Use OpenType fonts. Reference them in the CSS with @font-face
, eg.:
@font-face { font-family: "Minion Pro"; src: url(MinionPro.otf); }
@font-face { font-family: "Minion Pro"; font-style: italic;
src: url(MinionPro-It.otf); }
Other descriptors allowed are: font-variant
, font-weight
, font-size
.
Make these four files, according to the following descriptions:
application/epub+zip
It is ASCII, with no trailing end-of-line.
<?xml version="1.0"?>
<container version="1.0" xmlns="urn:oasis:names:tc:opendocument:xmlns:container">
<rootfiles>
<rootfile full-path="content.opf"
media-type="application/oebps-package+xml"/>
</rootfiles>
</container>
If you rename or put the content.opf
file elsewhere than in this guide, change the full-path
attribute to match.
<?xml version="1.0"?>
<package xmlns="http://www.idpf.org/2007/opf" unique-identifier="dcidid"
version="2.0">
<metadata xmlns:dc="http://purl.org/dc/elements/1.1/"
xmlns:dcterms="http://purl.org/dc/terms/"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:opf="http://www.idpf.org/2007/opf">
<dc:title>Epub Format Construction Guide</dc:title>
<dc:language xsi:type="dcterms:RFC3066">en</dc:language>
<dc:identifier id="dcidid" opf:scheme="URI">
http://www.hxa7241.org/articles/content/epup-guide_hxa7241_2007_2.epub
</dc:identifier>
<dc:subject>Non-fiction, technical article, tutorial, Epub, IDPF, ebook
</dc:subject>
<dc:description>A guide for making Epub ebooks/publications, sufficient
for most purposes. It requires understanding of XHTML, CSS, XML.
</dc:description>
<dc:relation>http://www.hxa.name/</dc:relation>
<dc:creator>Harrison Ainsworth / HXA7241</dc:creator>
<dc:publisher>Harrison Ainsworth / HXA7241</dc:publisher>
<dc:date xsi:type="dcterms:W3CDTF">2007-12-28</dc:date>
<dc:date xsi:type="dcterms:W3CDTF">2010-08-27</dc:date>
<dc:rights>Creative Commons BY-SA 3.0 License.</dc:rights>
</metadata>
<manifest>
<item id="ncx" href="toc.ncx"
media-type="application/x-dtbncx+xml" />
<item id="css" href="EpubGuide.css"
media-type="text/css" />
<item id="logo" href="hxa7241-logo.svg"
media-type="image/svg+xml" />
<item id="title" href="EpubGuide-title.html"
media-type="application/xhtml+xml" />
<item id="contents" href="EpubGuide-contents.html"
media-type="application/xhtml+xml" />
<item id="intro" href="EpubGuide-intro.html"
media-type="application/xhtml+xml" />
<item id="part1" href="EpubGuide-1.html"
media-type="application/xhtml+xml" />
<item id="part2" href="EpubGuide-2.html"
media-type="application/xhtml+xml" />
<item id="part3" href="EpubGuide-3.html"
media-type="application/xhtml+xml" />
<item id="part4" href="EpubGuide-4.html"
media-type="application/xhtml+xml" />
<item id="specs" href="EpubGuide-specs.html"
media-type="application/xhtml+xml" />
</manifest>
<spine toc="ncx">
<itemref idref="title" />
<itemref idref="contents" />
<itemref idref="intro" />
<itemref idref="part1" />
<itemref idref="part2" />
<itemref idref="part3" />
<itemref idref="part4" />
<itemref idref="specs" />
</spine>
<guide>
<reference type="title-page" title="Title Page"
href="EpubGuide-title.html" />
<reference type="toc" title="Table of Contents"
href="EpubGuide-contents.html" />
<reference type="text" title="Text"
href="EpubGuide-intro.html" />
</guide>
</package>
Add publication information according to DCMI terms. Order is not significant, and duplicates are allowed.
Required terms:
title
language
— use a RFC3066 language codeidentifier
— use a probably unique string: URI or ISBN would be goodOptional terms:
creator
contributor
publisher
subject
description
date
type
format
source
relation
coverage
rights
Some terms have optional attributes:
creator, contributor
opf:role
— see http://www.loc.gov/marc/relators/ for valuesdate
opf:event
— unstandardised: use something reasonableidentifier
opf:scheme
— unstandardised: use something reasonabledate, format, identifier, language, type
xsi:type
— use an appropriate standard term (such as W3CDTF
for date
)contributor, coverage, creator, description, publisher, relation, rights, source, subject, title
xml:lang
— use RFC-3066 formatList every file that is part of the publication. But not: mimetype
, container.xml
, content.opf
. The order is not significant.
Give correct mime-type in media-type
attribute. id
s are required and must be unique in the content.opf
file.
List all XHTML documents in manifest (using the idref
), and not anything else, and with no duplicates. The order is significant. (XHTML documents can be omitted, but then they must not be linked, referenced or reachable from any part of the publication.)
This section is optional.
Each item references a document file, and can have a fragment id. Allowed type
s are:
other.[...]
<?xml version="1.0"?>
<!DOCTYPE ncx PUBLIC "-//NISO//DTD ncx 2005-1//EN"
"http://www.daisy.org/z3986/2005/ncx-2005-1.dtd">
<ncx xmlns="http://www.daisy.org/z3986/2005/ncx/" version="2005-1">
<head>
<meta name="dtb:uid" content="http://www.hxa7241.org/articles/content/epup-guide_hxa7241_2007_2.epub"/>
<meta name="dtb:depth" content="2"/>
<meta name="dtb:totalPageCount" content="0"/>
<meta name="dtb:maxPageNumber" content="0"/>
</head>
<docTitle>
<text>Epub Format Construction Guide</text>
</docTitle>
<navMap>
<navPoint id="navPoint-1" playOrder="1">
<navLabel>
<text>Title Page</text>
</navLabel>
<content src="EpubGuide-title.html"/>
</navPoint>
<navPoint id="navPoint-2" playOrder="2">
<navLabel>
<text>Table of Contents</text>
</navLabel>
<content src="EpubGuide-contents.html"/>
</navPoint>
<navPoint id="navPoint-3" playOrder="3">
<navLabel>
<text>Introduction</text>
</navLabel>
<content src="EpubGuide-intro.html"/>
</navPoint>
<navPoint id="navPoint-4" playOrder="4">
<navLabel>
<text>1: XHTML Documents</text>
</navLabel>
<content src="EpubGuide-1.html"/>
</navPoint>
<navPoint id="navPoint-5" playOrder="5">
<navLabel>
<text>2: Package And Container Files</text>
</navLabel>
<content src="EpubGuide-2.html"/>
<navPoint id="navPoint-6" playOrder="6">
<navLabel>
<text>mimetype</text>
</navLabel>
<content src="EpubGuide-2.html#mimetype"/>
</navPoint>
<navPoint id="navPoint-7" playOrder="7">
<navLabel>
<text>container.xml</text>
</navLabel>
<content src="EpubGuide-2.html#containerxml"/>
</navPoint>
<navPoint id="navPoint-8" playOrder="8">
<navLabel>
<text>content.opf</text>
</navLabel>
<content src="EpubGuide-2.html#contentopf"/>
</navPoint>
<navPoint id="navPoint-9" playOrder="9">
<navLabel>
<text>toc.ncx</text>
</navLabel>
<content src="EpubGuide-2.html#tocncx"/>
</navPoint>
</navPoint>
<navPoint id="navPoint-10" playOrder="10">
<navLabel>
<text>3: ADE stylesheet</text>
</navLabel>
<content src="EpubGuide-3.html"/>
</navPoint>
<navPoint id="navPoint-11" playOrder="11">
<navLabel>
<text>4: Container Structure</text>
</navLabel>
<content src="EpubGuide-4.html"/>
</navPoint>
<navPoint id="navPoint-12" playOrder="12">
<navLabel>
<text>Specifications List</text>
</navLabel>
<content src="EpubGuide-specs.html"/>
</navPoint>
</navMap>
</ncx>
Set the following meta
content
attributes:
uid
— to the unique identifier in content.opf
depth
— to the depth of the contents tree (in navMap
), integer, >= 1
totalPageCount
— to 0
maxPageNumber
— to 0
Make a table of contents, optionally hierarchical. (navMap
doesn't need to include all XHTML files, since the content.opf
spine does.)
Set both attributes:
id
— to be unique in fileplayOrder
— to an integer, ordered in navMap
, starting at 1
Set sub-parts:
text
in navLabel
src
attribute in content
— to a URI of one of the XHTML files (fragment id allowed)navPoint
s nested in navPoint
s are allowed.
(The Sony Reader, and perhaps others, have an extra restriction: fragment ids (in src
attributes of content
s.) are not allowed in top-level (non-nested) navPoint
s.)
Optionally, make this file if you want extra control of column appearance with ADE 1.0:
page-template.xpgt
Add a link in the head of XHTML files to be styled:
<link rel="stylesheet" type="application/vnd.adobe-page-template+xml"
href="page-template.xpgt"/>
Will the publication then be non-conformant? Non-standard files can be included (like fonts), but must have proper fallback handling. The standard implies that all fallback behaviour is explicitly standardised (in IDPF or component standards). For stylesheets, HTML rules say readers should ignore unrecognized types. And that would very likely happen. So it seems conformant, and safe.
<ade:template xmlns="http://www.w3.org/1999/xhtml"
xmlns:ade="http://ns.adobe.com/2006/ade"
xmlns:fo="http://www.w3.org/1999/XSL/Format">
<fo:layout-master-set>
<fo:simple-page-master master-name="single_column" margin-bottom="2em"
margin-top="2em" margin-left="2em" margin-right="2em">
<fo:region-body/>
</fo:simple-page-master>
<fo:simple-page-master master-name="single_column_head" margin-bottom="2em"
margin-top="2em" margin-left="2em" margin-right="2em">
<fo:region-before extent="8em"/>
<fo:region-body margin-top="8em"/>
</fo:simple-page-master>
<fo:simple-page-master master-name="two_column" margin-bottom="2em"
margin-top="2em" margin-left="2em" margin-right="2em">
<fo:region-body column-count="2" column-gap="3em"/>
</fo:simple-page-master>
<fo:simple-page-master master-name="two_column_head" margin-bottom="2em"
margin-top="2em" margin-left="2em" margin-right="2em">
<fo:region-before extent="8em"/>
<fo:region-body column-count="2" margin-top="8em" column-gap="3em"/>
</fo:simple-page-master>
<fo:simple-page-master master-name="three_column" margin-bottom="2em"
margin-top="2em" margin-left="2em" margin-right="2em">
<fo:region-body column-count="3" column-gap="3em"/>
</fo:simple-page-master>
<fo:simple-page-master master-name="three_column_head" margin-bottom="2em"
margin-top="2em" margin-left="2em" margin-right="2em">
<fo:region-before extent="8em"/>
<fo:region-body column-count="3" margin-top="8em" column-gap="3em"/>
</fo:simple-page-master>
<fo:page-sequence-master>
<fo:repeatable-page-master-alternatives>
<fo:conditional-page-master-reference
master-reference="three_column_head" page-position="first"
ade:min-page-width="80em"/>
<fo:conditional-page-master-reference
master-reference="three_column" ade:min-page-width="80em"/>
<fo:conditional-page-master-reference
master-reference="two_column_head" page-position="first"
ade:min-page-width="50em"/>
<fo:conditional-page-master-reference
master-reference="two_column" ade:min-page-width="50em"/>
<fo:conditional-page-master-reference
master-reference="single_column_head" page-position="first"/>
<fo:conditional-page-master-reference
master-reference="single_column"/>
</fo:repeatable-page-master-alternatives>
</fo:page-sequence-master>
</fo:layout-master-set>
<ade:style>
<ade:styling-rule selector="#header" display="adobe-other-region"
adobe-region="xsl-region-before"/>
</ade:style>
</ade:template>
The selector
attribute in ade:style
/ade:styling-rule
refers to a CSS selector. There is more detail at: http://blogs.adobe.com/digitaleditions/template.html
Specification: unknown
Arrange all files in the following directory structure:
EpubGuide
META-INF
container.xml
mimetype
content.opf
toc.ncx
EpubGuide.css
hxa7241-logo.svg
EpubGuide-title.html
EpubGuide-contents.html
EpubGuide-intro.html
EpubGuide-1.html
EpubGuide-2.html
EpubGuide-3.html
EpubGuide-4.html
EpubGuide-specs.html
(META-INF
and its contents are special, but all other files can be arranged into any subdirectory structure. All references to them, in the various files, may have to be adjusted though.)
Then zip them into an archive with Zip. The filename extension should be ‘epub’, and the mimetype
file must be first (and uncompressed), and extra file attributes must be excluded:
zip -X0 EpubGuide-hxa7241.epub mimetype
zip -Xur9D EpubGuide-hxa7241.epub *
(Get Zip from: ftp://ftp.info-zip.org/pub/infozip/ or http://www.info-zip.org/Zip.html .)
Other zip programs can probably be used, if they can do the same things.
(The Sony Reader, and perhaps others, have an extra requirement: each HTML file must be < 300KB and < 100KB when zipped.)
DC:` title:`Epub Format Construction Guide` creator:`Harrison Ainsworth` date:`2007-12-28` date:`2010-08-27` description:`A guide for making Epub ebooks/publications, sufficient for most purposes. It requires understanding of XHTML, CSS, XML.` subject:`Epub, IDPF, ebook` language:`en-GB` type:`technical article` relation:`http://www.hxa.name/` identifier:`http://www.hxa.name/articles/content/epub-guide_hxa7241_2007.html` rights:`Creative Commons BY-SA 3.0 License` `