Create an EPUB or Word file from XML¶
This tutorial shows how to turn an XML document into an e-book (EPUB) for e-readers, or into a Word document you can share with colleagues who do not work with XML. Both are made from the same rules (the ODD) as your web and PDF versions, so a change you make once shows up everywhere. The examples use TEI; the steps are the same for DocBook, JATS or any other XML format.
Before you start¶
You need opm installed on your computer (see the
installation instructions) and a project
folder. If you do not have a project yet, create one:
If you have followed Convert XML to HTML, you can use the project from that tutorial.
Creating an EPUB¶
1. Create the e-book¶
-t epub selects the EPUB format, and -o names the file to write. Open
sample.epub in an e-book reader, for example Apple Books, Calibre or your
e-reader's desktop application. To open it right away in the default
application on your computer, use --preview instead of -o.
2. Decide on the chapters¶
An EPUB is divided into chapters. opm divides it the same way it divides a
website into pages, following the [chunking] section of
opm.toml. In a new project, that means a new chapter for each div, up to
two levels deep.
Sometimes an e-book should be divided differently from a website. In that case,
add a section [transform.epub] to opm.toml with its own setting:
With depth = 1, only top-level divisions become chapters. A higher number
also turns nested divisions into chapters of their own. If your website is
split at page breaks, the e-book is still divided into chapters by div, since
e-readers lay out the pages themselves.
3. Change the look¶
E-readers have their own ideas about fonts and page size, so EPUB styling is
best kept simple. opm uses a plain stylesheet for e-books, combined with the
styling from your ODD. To add your own rules, put them into a CSS file, for
example templates/epub.css, and name it in opm.toml:
Creating a Word document¶
Open sample.docx in Word, LibreOffice or any other word processor.
Headings, paragraphs, lists, tables, notes and emphasis come out as regular Word formatting, so the document can be edited further like any other.
Using your own Word styles¶
If your institution or publisher has a Word template, opm can use its styles.
Save the template as a normal .docx file in the templates folder and name it
in opm.toml:
opm then uses the paragraph and character styles from that file, such as
Heading 1 or Caption, so the result looks like the rest of your documents.
Creating Markdown¶
Markdown is a plain-text format, useful for example for notes, wikis or further processing with other tools:
Next steps¶
- Learn more about each format: see Output formats.
- Create a PDF from the same document.
- For a complete e-book example, create a copy of the Shakespeare edition with
opm init --example shakespeare, or of the DocBook handbook withopm init --example docbook.