Difference between revisions of "ePub"

From Wiki
Jump to navigation Jump to search
(Work in progress)
 
(documenting exported dir/file structure)
Line 1: Line 1:
{{todo|This page is meant to replace the current pages [[Epub]] and [[Epub_Sample]].}}
+
{{todo|This page is work in progress and an update to the current pages [[Epub]] and [[Epub_Sample]].}}
  
 
< [[XML]] | [[HTML]] | [[Epub|Old ePub docs]] | [[Epub_Sample|Old ePub Sample]] >
 
< [[XML]] | [[HTML]] | [[Epub|Old ePub docs]] | [[Epub_Sample|Old ePub Sample]] >
Line 5: Line 5:
 
Beware, these ePub/HTML facilities of ConTeXt work only with MkIV since some version in December 2014 and require additional work on your source code!
 
Beware, these ePub/HTML facilities of ConTeXt work only with MkIV since some version in December 2014 and require additional work on your source code!
  
= Minimal example =
+
= Minimal example and structure of export files =
  
 
<texcode>
 
<texcode>
 +
% mode=mkiv
 
\setupbackend[export=yes]
 
\setupbackend[export=yes]
  
Line 15: Line 16:
 
</texcode>
 
</texcode>
  
If you compile this, you get ...
+
If you compile this as {{code|1=minimal.tex}}, you get a directory structure like this:
 +
 
 +
<pre>
 +
minimal.tex
 +
minimal.log
 +
minimal.pdf
 +
minimal.tuc
 +
minimal-export
 +
├── cover.xhtml
 +
├── images
 +
├── minimal-div.xhtml
 +
├── minimal-pub.lua
 +
├── minimal-raw.xml
 +
├── minimal-tag.xhtml
 +
└── styles
 +
    ├── minimal-defaults.css
 +
    ├── minimal-images.css
 +
    ├── minimal-styles.css
 +
    └── minimal-templates.css
 +
</pre>
 +
 
 +
We will further refer to these files without the prefix ("minimal-"). We reformatted the code copies a bit to make them smaller and better readable.
 +
 
 +
== div.xhtml ==
 +
 
 +
<xmlcode>
 +
<?xml version="1.0" encoding="UTF-8" standalone="no" ?>
 +
<!--
 +
    input filename  : minimal
 +
    processing date  : Sat Jan 17 17:43:58 2015
 +
    context version  : 2014.12.29 10:01
 +
    exporter version : 0.33
 +
-->
 +
<html xmlns="http://www.w3.org/1999/xhtml" xmlns:math="http://www.w3.org/1998/Math/MathML">
 +
    <head>
 +
        <meta charset="utf-8"/>
 +
        <title></title>
 +
<link type="text/css" rel="stylesheet" href="styles/minimal-defaults.css" />
 +
<link type="text/css" rel="stylesheet" href="styles/minimal-images.css" />
 +
<link type="text/css" rel="stylesheet" href="styles/minimal-styles.css" />
 +
    </head>
 +
    <body>
 +
        <div class="warning">Rendering can be suboptimal because there is no default/fallback css loaded.</div>
 +
<div>
 +
We thrive in information--thick worlds because of our marvelous and everyday capacity to select, edit, single out, structure, highlight, group, pair, merge, harmonize, synthesize, focus, organize, condense, reduce, boil down, choose, categorize, catalog, classify, list, abstract, scan, look into, idealize, isolate, discriminate, distinguish, screen, pigeonhole, pick over, sort, integrate, blend, inspect, filter, lump, skip, smooth, chunk, average, approximate, cluster, aggregate, outline, summarize, itemize, review, dip into, flip through, browse, glance into, leaf through, skim, refine, enumerate, glean, synopsize, winnow the wheat from the chaff and separate the sheep from the goats.
 +
</div>
 +
    </body>
 +
</html>
 +
</xmlcode>
 +
 
 +
== tag.xhtml ==
 +
 
 +
<xmlcode>
 +
<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
 +
<!--
 +
    input filename  : minimal
 +
    processing date  : Sat Jan 17 17:43:58 2015
 +
    context version  : 2014.12.29 10:01
 +
    exporter version : 0.33
 +
-->
 +
<?xml-stylesheet type="text/css" href="styles/minimal-defaults.css" ?>
 +
<?xml-stylesheet type="text/css" href="styles/minimal-images.css" ?>
 +
<?xml-stylesheet type="text/css" href="styles/minimal-styles.css" ?>
 +
<document href="minimal" language="en" date="Sat Jan 17 17:43:58 2015" context="2014.12.29 10:01" xmlns:m="http://www.w3.org/1998/Math/MathML" file="minimal" version="0.33">
 +
We thrive in information--thick worlds because of our marvelous and everyday capacity to select, edit, single out, structure, highlight, group, pair, merge, harmonize, synthesize, focus, organize, condense, reduce, boil down, choose, categorize, catalog, classify, list, abstract, scan, look into, idealize, isolate, discriminate, distinguish, screen, pigeonhole, pick over, sort, integrate, blend, inspect, filter, lump, skip, smooth, chunk, average, approximate, cluster, aggregate, outline, summarize, itemize, review, dip into, flip through, browse, glance into, leaf through, skim, refine, enumerate, glean, synopsize, winnow the wheat from the chaff and separate the sheep from the goats.
 +
</document>
 +
</xmlcode>
 +
 
 +
== raw.xml ==
 +
 
 +
<xmlcode>
 +
<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
 +
<!--
 +
    input filename  : minimal
 +
    processing date  : Sat Jan 17 17:43:58 2015
 +
    context version  : 2014.12.29 10:01
 +
    exporter version : 0.33
 +
-->
 +
<?xml-stylesheet type="text/css" href="styles/minimal-defaults.css" ?>
 +
<?xml-stylesheet type="text/css" href="styles/minimal-images.css" ?>
 +
<?xml-stylesheet type="text/css" href="styles/minimal-styles.css" ?>
 +
<document language="en" date="Sat Jan 17 17:43:58 2015" context="2014.12.29 10:01" xmlns:m="http://www.w3.org/1998/Math/MathML" file="minimal" version="0.33">
 +
We thrive in information--thick worlds because of our marvelous and everyday capacity to select, edit, single out, structure, highlight, group, pair, merge, harmonize, synthesize, focus, organize, condense, reduce, boil down, choose, categorize, catalog, classify, list, abstract, scan, look into, idealize, isolate, discriminate, distinguish, screen, pigeonhole, pick over, sort, integrate, blend, inspect, filter, lump, skip, smooth, chunk, average, approximate, cluster, aggregate, outline, summarize, itemize, review, dip into, flip through, browse, glance into, leaf through, skim, refine, enumerate, glean, synopsize, winnow the wheat from the chaff and separate the sheep from the goats.
 +
</document>
 +
</xmlcode>
 +
 
 +
== pub.lua ==
 +
 
 +
<texcode>
 +
return {
 +
["htmlfiles"]={ "minimal-div.xhtml" },
 +
["htmlroot"]="minimal-div.xhtml",
 +
["identifier"]="3ce74458-4cdd-829d-ace4-cf535fb00519",
 +
["imagefile"]="styles/minimal-images.css",
 +
["imagepath"]="images",
 +
["images"]={},
 +
["language"]="en",
 +
["name"]="minimal",
 +
["stylepath"]="styles",
 +
["styles"]={ "minimal-defaults.css", "minimal-images.css", "minimal-styles.css" },
 +
["xhtmlfiles"]={ "minimal-tag.xhtml" },
 +
["xmlfiles"]={ "minimal-raw.xml" },
 +
}
 +
</texcode>
 +
 
 +
= Minimal ePub =
 +
 
 +
If you run {{code|1=mtxrun --script epub --make minimal}} on above example, you get a structure like:
 +
 
 +
<pre>
 +
minimal.epub
 +
minimal-epub
 +
├── META-INF
 +
│   └── container.xml
 +
├── OEBPS
 +
│   ├── cover.xhtml
 +
│   ├── images
 +
│   ├── minimal-div.xhtml
 +
│   ├── minimal.opf
 +
│   ├── nav.xhtml
 +
│   ├── styles
 +
│   │   ├── minimal-defaults.css
 +
│   │   ├── minimal-images.css
 +
│   │   └── minimal-styles.css
 +
│   └── toc.ncx
 +
└── mimetype
 +
</pre>
 +
 
 +
* epub: The epub file is just a zipped version of the directory structure.
 +
* mimetype: contains only "{{code|1=application/epub+zip}}"
 +
* container.xml points to the root file "minimal.opf"
 +
* cover.xhtml is the cover image shown by ePub readers
 +
* opf: list of all resources, this keeps the "book" together. See also [[http://www.idpf.org/epub/20/spec/OPF_2.0.1_draft.htm|OPF specs]].
 +
* ncx: table of contents
 +
 
 +
That’s nice, but the contents make no sense yet. We have to add more structure and metadata.
  
 
= Required structuring =
 
= Required structuring =
  
The export contains usable content only for content that is "well structured" in an XML sense. That means, you need to mark everything, from markup spans over paragraphs and enumeration items to chapters and parts with <tex>start...</tex> <tex>stop...</tex>.
+
The export contains usable content only for content that is "well structured" in an XML sense. That means, you need to mark everything, from markup spans over paragraphs and enumeration items to chapters and parts with {{code|1=\start... … \stop...}}, for example:
  
 
<texcode>
 
<texcode>
Line 26: Line 162:
  
 
\startparagraph
 
\startparagraph
 +
 +
\input tufte
  
 
\startitemize[packed,joinup]
 
\startitemize[packed,joinup]
\startitem \stopitem
+
  \startitem First \stopitem
\startitem \stopitem
+
  \startitem Second \stopitem
\startitem \stopitem
+
  \startitem Third \stopitem
\startitem \stopitem
+
  \startitem Fourth\stopitem
 
\stopitemize
 
\stopitemize
  
Line 37: Line 175:
  
 
\startparagraph
 
\startparagraph
 +
\input knuth
 
\stopparagraph
 
\stopparagraph
  
 
\startparagraph
 
\startparagraph
 +
\input hagen
 
\stopparagraph
 
\stopparagraph
  
Line 49: Line 189:
  
 
<texcode>
 
<texcode>
 +
% mode=mkiv
 
\setupbackend[export=yes]
 
\setupbackend[export=yes]
 
\setupmainlanguage[en]
 
\setupmainlanguage[en]

Revision as of 12:23, 17 January 2015


TODO: This page is work in progress and an update to the current pages Epub and Epub_Sample. (See: To-Do List)


< XML | HTML | Old ePub docs | Old ePub Sample >

Beware, these ePub/HTML facilities of ConTeXt work only with MkIV since some version in December 2014 and require additional work on your source code!

Minimal example and structure of export files

% mode=mkiv
\setupbackend[export=yes]

\starttext
\input tufte
\stoptext

If you compile this as minimal.tex, you get a directory structure like this:

minimal.tex
minimal.log
minimal.pdf
minimal.tuc
minimal-export
├── cover.xhtml
├── images
├── minimal-div.xhtml
├── minimal-pub.lua
├── minimal-raw.xml
├── minimal-tag.xhtml
└── styles
    ├── minimal-defaults.css
    ├── minimal-images.css
    ├── minimal-styles.css
    └── minimal-templates.css

We will further refer to these files without the prefix ("minimal-"). We reformatted the code copies a bit to make them smaller and better readable.

div.xhtml

<?xml version="1.0" encoding="UTF-8" standalone="no" ?>
<!--
    input filename   : minimal
    processing date  : Sat Jan 17 17:43:58 2015
    context version  : 2014.12.29 10:01
    exporter version : 0.33
-->
<html xmlns="http://www.w3.org/1999/xhtml" xmlns:math="http://www.w3.org/1998/Math/MathML">
    <head>
        <meta charset="utf-8"/>
        <title></title>
<link type="text/css" rel="stylesheet" href="styles/minimal-defaults.css" />
<link type="text/css" rel="stylesheet" href="styles/minimal-images.css" />
<link type="text/css" rel="stylesheet" href="styles/minimal-styles.css" />
    </head>
    <body>
        <div class="warning">Rendering can be suboptimal because there is no default/fallback css loaded.</div>
<div>
We thrive in information--thick worlds because of our marvelous and everyday capacity to select, edit, single out, structure, highlight, group, pair, merge, harmonize, synthesize, focus, organize, condense, reduce, boil down, choose, categorize, catalog, classify, list, abstract, scan, look into, idealize, isolate, discriminate, distinguish, screen, pigeonhole, pick over, sort, integrate, blend, inspect, filter, lump, skip, smooth, chunk, average, approximate, cluster, aggregate, outline, summarize, itemize, review, dip into, flip through, browse, glance into, leaf through, skim, refine, enumerate, glean, synopsize, winnow the wheat from the chaff and separate the sheep from the goats.
</div>
    </body>
</html>

tag.xhtml

<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
<!--
    input filename   : minimal
    processing date  : Sat Jan 17 17:43:58 2015
    context version  : 2014.12.29 10:01
    exporter version : 0.33
-->
<?xml-stylesheet type="text/css" href="styles/minimal-defaults.css" ?>
<?xml-stylesheet type="text/css" href="styles/minimal-images.css" ?>
<?xml-stylesheet type="text/css" href="styles/minimal-styles.css" ?>
<document href="minimal" language="en" date="Sat Jan 17 17:43:58 2015" context="2014.12.29 10:01" xmlns:m="http://www.w3.org/1998/Math/MathML" file="minimal" version="0.33">
We thrive in information--thick worlds because of our marvelous and everyday capacity to select, edit, single out, structure, highlight, group, pair, merge, harmonize, synthesize, focus, organize, condense, reduce, boil down, choose, categorize, catalog, classify, list, abstract, scan, look into, idealize, isolate, discriminate, distinguish, screen, pigeonhole, pick over, sort, integrate, blend, inspect, filter, lump, skip, smooth, chunk, average, approximate, cluster, aggregate, outline, summarize, itemize, review, dip into, flip through, browse, glance into, leaf through, skim, refine, enumerate, glean, synopsize, winnow the wheat from the chaff and separate the sheep from the goats.
</document>

raw.xml

<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
<!--
    input filename   : minimal
    processing date  : Sat Jan 17 17:43:58 2015
    context version  : 2014.12.29 10:01
    exporter version : 0.33
-->
<?xml-stylesheet type="text/css" href="styles/minimal-defaults.css" ?>
<?xml-stylesheet type="text/css" href="styles/minimal-images.css" ?>
<?xml-stylesheet type="text/css" href="styles/minimal-styles.css" ?>
<document language="en" date="Sat Jan 17 17:43:58 2015" context="2014.12.29 10:01" xmlns:m="http://www.w3.org/1998/Math/MathML" file="minimal" version="0.33">
We thrive in information--thick worlds because of our marvelous and everyday capacity to select, edit, single out, structure, highlight, group, pair, merge, harmonize, synthesize, focus, organize, condense, reduce, boil down, choose, categorize, catalog, classify, list, abstract, scan, look into, idealize, isolate, discriminate, distinguish, screen, pigeonhole, pick over, sort, integrate, blend, inspect, filter, lump, skip, smooth, chunk, average, approximate, cluster, aggregate, outline, summarize, itemize, review, dip into, flip through, browse, glance into, leaf through, skim, refine, enumerate, glean, synopsize, winnow the wheat from the chaff and separate the sheep from the goats.
</document>

pub.lua

return {
 ["htmlfiles"]={ "minimal-div.xhtml" },
 ["htmlroot"]="minimal-div.xhtml",
 ["identifier"]="3ce74458-4cdd-829d-ace4-cf535fb00519",
 ["imagefile"]="styles/minimal-images.css",
 ["imagepath"]="images",
 ["images"]={},
 ["language"]="en",
 ["name"]="minimal",
 ["stylepath"]="styles",
 ["styles"]={ "minimal-defaults.css", "minimal-images.css", "minimal-styles.css" },
 ["xhtmlfiles"]={ "minimal-tag.xhtml" },
 ["xmlfiles"]={ "minimal-raw.xml" },
}

Minimal ePub

If you run mtxrun --script epub --make minimal on above example, you get a structure like:

minimal.epub
minimal-epub
├── META-INF
│   └── container.xml
├── OEBPS
│   ├── cover.xhtml
│   ├── images
│   ├── minimal-div.xhtml
│   ├── minimal.opf
│   ├── nav.xhtml
│   ├── styles
│   │   ├── minimal-defaults.css
│   │   ├── minimal-images.css
│   │   └── minimal-styles.css
│   └── toc.ncx
└── mimetype
  • epub: The epub file is just a zipped version of the directory structure.
  • mimetype: contains only "application/epub+zip"
  • container.xml points to the root file "minimal.opf"
  • cover.xhtml is the cover image shown by ePub readers
  • opf: list of all resources, this keeps the "book" together. See also [specs].
  • ncx: table of contents

That’s nice, but the contents make no sense yet. We have to add more structure and metadata.

Required structuring

The export contains usable content only for content that is "well structured" in an XML sense. That means, you need to mark everything, from markup spans over paragraphs and enumeration items to chapters and parts with \start... … \stop..., for example:

...
\startsection[title={A section}]

\startparagraph

\input tufte

\startitemize[packed,joinup]
  \startitem First \stopitem
  \startitem Second \stopitem
  \startitem Third \stopitem
  \startitem Fourth\stopitem
\stopitemize

\stopparagraph

\startparagraph
\input knuth
\stopparagraph

\startparagraph
\input hagen
\stopparagraph

\stopsection
...

Minimal useful example

% mode=mkiv
\setupbackend[export=yes]
\setupmainlanguage[en]

\starttext

\startparagraph
\input tufte
\stopparagraph

\stoptext