Difference between revisions of "Epub"
m (→Current Issues: - update date) |
m (Text replacement - "</cmd>" to "}}") |
||
(52 intermediate revisions by 6 users not shown) | |||
Line 1: | Line 1: | ||
− | ConTeXt has preliminary [http://en.wikipedia.org/wiki/EPUB epub] support starting from | + | {{todo|Beware, this doesn’t fit the current state of export files as of January 2015!}} |
+ | |||
+ | < [[Export]] | [[ePub|New ePub docs]] > | ||
+ | |||
+ | == Minimal example == | ||
+ | |||
+ | A minimal example file would be: | ||
+ | |||
+ | <texcode> | ||
+ | \setupbackend[export=yes,xhtml=yes] | ||
+ | |||
+ | \mainlanguage[de] | ||
+ | \language[de] | ||
+ | |||
+ | \setupexport | ||
+ | [title={A nice book}, | ||
+ | author={John Doe}, | ||
+ | firstpage={huhn.jpg}, | ||
+ | ] | ||
+ | |||
+ | \starttext | ||
+ | Hello world! | ||
+ | \stoptext | ||
+ | </texcode> | ||
+ | |||
+ | Please note, that a cover image is part of a valid epub file, therefore you should provide one even in the most minimal case. It is called huhn.jpg in this case. Make sure it is in the same directory as you tex file. Now you have to call the script to produce the epub | ||
+ | |||
+ | <texcode> | ||
+ | mtxrun --script epub --make test_00.specification | ||
+ | </texcode> | ||
+ | |||
+ | assuming that the minimal example tex file is called test_00.tex | ||
+ | |||
+ | == More information == | ||
+ | |||
+ | ConTeXt has preliminary [http://en.wikipedia.org/wiki/EPUB epub] support starting from [[Context 2011.05.18 | current 2011.05.18]]. Some problems were fixed end of August 2014, don’t use an older version! | ||
Line 9: | Line 44: | ||
'''Note:''' There is no support for graphics yet, that will be included in a later version. | '''Note:''' There is no support for graphics yet, that will be included in a later version. | ||
+ | |||
+ | '''There’s also a more extensive [[Epub Sample|example]].''' | ||
== Export == | == Export == | ||
− | To enable the export backend, depending on your needs, one of the following lines has to be included at the beginning of the document (before | + | To enable the export backend, depending on your needs, one of the following lines has to be included at the beginning of the document (before {{cmd|starttext}}). |
<texcode> | <texcode> | ||
− | |||
\setupbackend[export=yes,xhtml=yes] | \setupbackend[export=yes,xhtml=yes] | ||
\setupbackend[export=yes,xhtml=whatever.xhtml] | \setupbackend[export=yes,xhtml=whatever.xhtml] | ||
Line 27: | Line 63: | ||
* xhtml+css | * xhtml+css | ||
+ | ''For making an epub, you need an xhtml export.'' | ||
− | + | If you are unsure, which one of the three backend options you should use, use the minimal one: | |
+ | |||
+ | <texcode> | ||
+ | \setupbackend[export=yes,xhtml=yes] | ||
+ | </texcode> | ||
− | + | When using a css file, images are supported using an extra css file <code>*-images.css</code>. Images with suffix <code>pdf</code> are remapped to <code>svg</code> but <code>png</code> and <code>jpg</code> are passed on. | |
− | + | You can add metadata using the following command: | |
− | + | <texcode> | |
+ | \setupexport | ||
+ | [title={A nice book}, | ||
+ | author={John Doe}, | ||
+ | firstpage={huhn.jpg}, | ||
+ | ] | ||
+ | </texcode> | ||
+ | |||
+ | == The example file == | ||
+ | |||
+ | You can also hook css into the output, see thread: [http://www.ntg.nl/pipermail/ntg-context/2011/058907.html ntg-context]. The distribution has a test file <code>export-example.tex</code>. This file exports conforming: | ||
<texcode> | <texcode> | ||
\setupbackend | \setupbackend | ||
− | [export= | + | [export=export-example.xml, |
− | xhtml= | + | xhtml=export-example.xhtml, |
− | css= | + | css=export-example.css] |
+ | </texcode> | ||
+ | |||
+ | This file shows some of the possibilities. You will notice that it is a rather normal context file. When the file is processed, you can create an epub file with: | ||
+ | |||
+ | <texcode> | ||
+ | mtxrun --script epub --make export-example | ||
</texcode> | </texcode> | ||
+ | |||
+ | == Additional tagging == | ||
+ | |||
+ | You can mark sections that don't need to be exported: | ||
+ | |||
+ | <texcode> | ||
+ | \startelement[ignore] | ||
+ | |||
+ | titlepage makeup | ||
+ | |||
+ | \stopelement | ||
+ | </texcode> | ||
+ | |||
+ | You can also add data: | ||
+ | |||
+ | <texcode> | ||
+ | \settaggedmetadata[name=Me] | ||
+ | |||
+ | \startchapter[title=...] | ||
+ | .... | ||
+ | \stopchapter | ||
+ | </texcode> | ||
+ | |||
+ | In this case the data will be injected just after the start of the chapter tag. So, if you want to have document level metadata, you need to put the set command before {{cmd|starttext}}. | ||
+ | |||
+ | == Document styling == | ||
+ | |||
+ | Some style elements are exported to an additional css file and a reference to that file is automatically added. You can exercise some control over the general document rendering: | ||
+ | |||
+ | <texcode> | ||
+ | \setupexport | ||
+ | [bodyfont=12pt, | ||
+ | width=600pt, | ||
+ | %align=flushleft, | ||
+ | hyphen=yes] | ||
+ | </texcode> | ||
+ | |||
+ | The last option makes sure that the export has enough information to do a reasonable hyohenation. Future versions of the exported might provide some more control. | ||
== Mtxrun == | == Mtxrun == | ||
The actual generation of the epub can be triggered with the <code>mtxrun</code> command shown in the output. | The actual generation of the epub can be triggered with the <code>mtxrun</code> command shown in the output. | ||
− | |||
Example log entry: | Example log entry: | ||
Line 58: | Line 152: | ||
The "oeps" will be replaced with the appropriate name given to the export backend. | The "oeps" will be replaced with the appropriate name given to the export backend. | ||
− | |||
Therefore, execute: | Therefore, execute: | ||
Line 64: | Line 157: | ||
mtxrun --script epub --make oeps.specification | mtxrun --script epub --make oeps.specification | ||
− | This will create an ''oeps.tree'' folder with an ''oeps.epub'' inside it. | + | This will create an ''oeps.tree'' folder with an ''oeps.epub'' inside it. When pdf images are used and no suitable svg alternative is present inkscape will be used to create the svg file. |
− | |||
More on this on the mailing list, thread starts at: [http://www.ntg.nl/pipermail/ntg-context/2011/058996.html ntg-context]. | More on this on the mailing list, thread starts at: [http://www.ntg.nl/pipermail/ntg-context/2011/058996.html ntg-context]. | ||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
== Tools == | == Tools == | ||
Line 82: | Line 165: | ||
Viewer: | Viewer: | ||
* [http://calibre-ebook.com/ calibre] | * [http://calibre-ebook.com/ calibre] | ||
− | * [http://www.epubread.com/ EPUBReader for Firefox] | + | * [http://www.epubread.com/ EPUBReader for Firefox] (also does mathml) |
* [http://www.fbreader.org/ FBReader] | * [http://www.fbreader.org/ FBReader] | ||
+ | * ''[http://www.adobe.com/products/digitaleditions/ Adobe Digital Editions]'' | ||
+ | |||
+ | Online: | ||
+ | * [http://bookworm.oreilly.com/ bookworm] | ||
Editor: | Editor: | ||
Line 93: | Line 180: | ||
Specification: | Specification: | ||
− | * [http://idpf.org/epub epub] | + | * [http://idpf.org/epub epub 2/3] |
== Current Issues == | == Current Issues == | ||
− | As of | + | As of 08:41, 16 June 2011 (CEST): |
<table> | <table> | ||
Line 106: | Line 193: | ||
</tr> | </tr> | ||
<tr> | <tr> | ||
− | + | <td><code>[https://gist.github.com/1013262 mtx-epub.lua]</code></td> | |
− | <td><code> | + | <td>OPF 2.0.1</td> |
− | <td> | + | <td>amazoncover, bookid, id & ncx fix</td> |
− | |||
− | |||
− | |||
− | <td> | ||
− | |||
</tr> | </tr> | ||
<tr> | <tr> | ||
− | <td>epubcheck-1.2</td> | + | <td style="border-top: 1px solid black">epubcheck-1.2</td> |
− | <td><code>test.xhtml</code>:< | + | <td style="border-top: 1px solid black">OPS 2.0.1</td> |
− | + | <td style="border-top: 1px solid black"><code>test.xhtml</code>: <code><document></code><br />elements from namespace "" are not allowed<br />xhtml DOCTYPE missing, html + body elements</td> | |
</tr> | </tr> | ||
<tr> | <tr> | ||
<td>epubreader</td> | <td>epubreader</td> | ||
− | <td> | + | <td>OPS 2.0.1</td> |
<td>This XML file does not appear to have any style information associated with it.</td> | <td>This XML file does not appear to have any style information associated with it.</td> | ||
</tr> | </tr> | ||
<tr> | <tr> | ||
<td>kindlegen</td> | <td>kindlegen</td> | ||
− | <td> | + | <td>OPS 2.0.1</td> |
<td>No BODY tag found in content file.</td> | <td>No BODY tag found in content file.</td> | ||
</tr> | </tr> | ||
</table> | </table> | ||
+ | |||
+ | |||
+ | <table> | ||
+ | <tr style="background:#cccccc;"> | ||
+ | <td>feature</td> | ||
+ | <td>description</td> | ||
+ | </tr> | ||
+ | <tr> | ||
+ | <td>metadata</td> | ||
+ | <td>add author and title to local:package and local:navigation (mtx-epub.lua)</td> | ||
+ | </tr> | ||
+ | <tr> | ||
+ | <td>cover</td> | ||
+ | <td>add [http://code.google.com/p/epubcheck/issues/detail?id=74 cover element], 600×800 (min. 500) for amazon</td> | ||
+ | </tr> | ||
+ | <tr> | ||
+ | <td>toc</td> | ||
+ | <td>table of contents is missing</td> | ||
+ | </tr> | ||
+ | <tr> | ||
+ | <td>chapter break</td> | ||
+ | <td>new title element → new xhtml</td> | ||
+ | </tr> | ||
+ | </table> | ||
+ | |||
+ | == Latest news == | ||
+ | |||
+ | (This section is to be integrated in the instructions above.) | ||
+ | |||
+ | Now | ||
+ | <texcode> | ||
+ | \setupbackend | ||
+ | [export=yes, | ||
+ | xhtml=yes, | ||
+ | css=export-example.css] | ||
+ | </texcode> | ||
+ | also exports an html file with all tags being 'div' and the default css has been adapted to support both. The default css still need some work because not all browsers handle these div expressions equally well. The idea is to have a decent looking default as template (one can always overload). | ||
+ | |||
+ | --Hans 27 August 2014 | ||
+ | |||
+ | The problem with an invalid export.xml when using project structure is also fixed since 27 August 2014. |
Latest revision as of 13:24, 9 August 2020
TODO: Beware, this doesn’t fit the current state of export files as of January 2015! (See: To-Do List) |
< Export | New ePub docs >
Contents
Minimal example
A minimal example file would be:
\setupbackend[export=yes,xhtml=yes] \mainlanguage[de] \language[de] \setupexport [title={A nice book}, author={John Doe}, firstpage={huhn.jpg}, ] \starttext Hello world! \stoptext
Please note, that a cover image is part of a valid epub file, therefore you should provide one even in the most minimal case. It is called huhn.jpg in this case. Make sure it is in the same directory as you tex file. Now you have to call the script to produce the epub
mtxrun --script epub --make test_00.specification
assuming that the minimal example tex file is called test_00.tex
More information
ConTeXt has preliminary epub support starting from current 2011.05.18. Some problems were fixed end of August 2014, don’t use an older version!
In order to make an epub (archive) from your ConTeXt source files, you need to:
- enable the export backend in your
.tex
file or environment file (see Project structure) - call the appropriate
mtxrun
command (with the epub script) shown in the output of a context run or in the log file
Note: There is no support for graphics yet, that will be included in a later version.
There’s also a more extensive example.
Export
To enable the export backend, depending on your needs, one of the following lines has to be included at the beginning of the document (before \starttext).
\setupbackend[export=yes,xhtml=yes] \setupbackend[export=yes,xhtml=whatever.xhtml] \setupbackend[export=yes,css={whatever.css,somemore.css}]
The backend can export into:
- xml
- xhtml
- xhtml+css
For making an epub, you need an xhtml export.
If you are unsure, which one of the three backend options you should use, use the minimal one:
\setupbackend[export=yes,xhtml=yes]
When using a css file, images are supported using an extra css file *-images.css
. Images with suffix pdf
are remapped to svg
but png
and jpg
are passed on.
You can add metadata using the following command:
\setupexport [title={A nice book}, author={John Doe}, firstpage={huhn.jpg}, ]
The example file
You can also hook css into the output, see thread: ntg-context. The distribution has a test file export-example.tex
. This file exports conforming:
\setupbackend [export=export-example.xml, xhtml=export-example.xhtml, css=export-example.css]
This file shows some of the possibilities. You will notice that it is a rather normal context file. When the file is processed, you can create an epub file with:
mtxrun --script epub --make export-example
Additional tagging
You can mark sections that don't need to be exported:
\startelement[ignore] titlepage makeup \stopelement
You can also add data:
\settaggedmetadata[name=Me] \startchapter[title=...] .... \stopchapter
In this case the data will be injected just after the start of the chapter tag. So, if you want to have document level metadata, you need to put the set command before \starttext.
Document styling
Some style elements are exported to an additional css file and a reference to that file is automatically added. You can exercise some control over the general document rendering:
\setupexport [bodyfont=12pt, width=600pt, %align=flushleft, hyphen=yes]
The last option makes sure that the export has enough information to do a reasonable hyohenation. Future versions of the exported might provide some more control.
Mtxrun
The actual generation of the epub can be triggered with the mtxrun
command shown in the output.
Example log entry:
... backend > export > saving xml data in 'oeps.export backend > export > saving css template in 'oeps.template backend > export > saving xhtml variant in 'oeps.xhtml backend > export > saving specification in 'oeps.specification' (mtxrun --script epub --make oeps.specification) ...
The "oeps" will be replaced with the appropriate name given to the export backend.
Therefore, execute:
mtxrun --script epub --make oeps.specification
This will create an oeps.tree folder with an oeps.epub inside it. When pdf images are used and no suitable svg alternative is present inkscape will be used to create the svg file.
More on this on the mailing list, thread starts at: ntg-context.
Tools
Viewer:
- calibre
- EPUBReader for Firefox (also does mathml)
- FBReader
- Adobe Digital Editions
Online:
Editor:
Validation:
Specification:
Current Issues
As of 08:41, 16 June 2011 (CEST):
tool | description | error |
mtx-epub.lua |
OPF 2.0.1 | amazoncover, bookid, id & ncx fix |
epubcheck-1.2 | OPS 2.0.1 | test.xhtml : <document> elements from namespace "" are not allowed xhtml DOCTYPE missing, html + body elements |
epubreader | OPS 2.0.1 | This XML file does not appear to have any style information associated with it. |
kindlegen | OPS 2.0.1 | No BODY tag found in content file. |
feature | description |
metadata | add author and title to local:package and local:navigation (mtx-epub.lua) |
cover | add cover element, 600×800 (min. 500) for amazon |
toc | table of contents is missing |
chapter break | new title element → new xhtml |
Latest news
(This section is to be integrated in the instructions above.)
Now
\setupbackend [export=yes, xhtml=yes, css=export-example.css]
also exports an html file with all tags being 'div' and the default css has been adapted to support both. The default css still need some work because not all browsers handle these div expressions equally well. The idea is to have a decent looking default as template (one can always overload).
--Hans 27 August 2014
The problem with an invalid export.xml when using project structure is also fixed since 27 August 2014.