gardener, Interface administrators, Administrators
1,540
edits
Changes
Jump to navigation
Jump to search
Move export docs from ePub
{{todo|This page is work in progress.}}
ConTeXt does not only produce beautiful PDFs, but can also export to [[XML]]/XHTML. This is especially useful for creating eBooks in [[ePub]] format.
< [[XML]] | [[ePub]] >
= Minimal example and structure of export files =
<texcode>
% mode=mkiv
\setupbackend[export=yes]
\starttext
\input tufte
\stoptext
</texcode>
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>
= Required structuring =
The export contains usable content only for content that is "well structured" in an XML sense. In our above example all text ended up in the root tag {{code|document}}.
That means, you need to mark ''everything,'' from markup spans over paragraphs and enumeration items to chapters and parts with {{code|1=\start... … \stop...}}.
Also note that switches like {{cmd|em}} don’t translate into output structure, you need to {{cmd|definehighlight|2=[emph][style=italic]}} and use as {{code|1=\emph{emphasized}.}}
= Useful example =
<texcode>
% mode=mkiv
\mainlanguage[en]
\setupbackend[export=yes]
\setupinteraction[state=start,
color=,contrastcolor=,
% This metadata is used for the PDF
title={My first eBook 1},
subtitle={},
keywords={},
author={Hans 1}
]
\setupexport[
hyphen=yes,
% This metadata is used by ConTeXt’s ePub script
% title, subtitle and author are taken from \setupinteraction, if not set
title={My first eBook 2},
subtitle={},
author={Hans 2}
]
\settaggedmetadata[
% here you can set as many metadata entries as you like, but you need to process them yourself
title={My first eBook 3},
author={Hans 3},
subtitle={},
version={\date} % TODO: doesn’t expand
]
\definehighlight[emph][style=italic] % use \emph{something} instead of {\em something}
\starttext
\startchapter[title=Example]
\startparagraph
\input tufte
\stopparagraph
\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 zapf
\stopparagraph
\stopsection
\stopchapter
\startchapter[title=Quoth\footnote{by Edgar Allan Poe}]
\startlines
\quotation{Prophet!} said I, \quotation{thing of evil!—prophet still, if bird or devil!
By that Heaven that bends above us—by that God we both adore—
Tell this soul with sorrow laden if, within the distant Aidenn,
It shall clasp a sainted maiden whom the angels name Lenore—
Clasp a rare and radiant maiden whom the angels name Lenore.}
\emph{Quoth the Raven \quotation{Nevermore.}}
\stoplines
\stopchapter
\stoptext
</texcode>
Only after such tagging we find significant differences between the three content output files:
TODO: explain differences between export variants
(WORK IN PROGRESS)
There’s an example of an export-friendly ConTeXt file in the sources: {{src|export-example.tex}}.
= Export options =
From {{src|back-exp.mkiv}}, is this still current?
<texcode>
\setupexport[
align=\raggedstatus,
bodyfont=\bodyfontsize,
width=\textwidth,
title={\directinteractionparameter\c!title}, % from interaction
subtitle={\directinteractionparameter\c!subtitle}, % from interaction
author={\directinteractionparameter\c!author}, % from interaction
% firstpage=, % imagename
% lastpage=, % imagename
hyphen=no,
]
</texcode>
* The options align, bodyfont and width end up in the exported CSS.
* firstpage, lastpage: cover image? (how?)
* hyphen: include hyphenation ({{code|1=­}}?)
= More TODO =
* handling of images
* which files get overwritten, which stay
ConTeXt does not only produce beautiful PDFs, but can also export to [[XML]]/XHTML. This is especially useful for creating eBooks in [[ePub]] format.
< [[XML]] | [[ePub]] >
= Minimal example and structure of export files =
<texcode>
% mode=mkiv
\setupbackend[export=yes]
\starttext
\input tufte
\stoptext
</texcode>
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>
= Required structuring =
The export contains usable content only for content that is "well structured" in an XML sense. In our above example all text ended up in the root tag {{code|document}}.
That means, you need to mark ''everything,'' from markup spans over paragraphs and enumeration items to chapters and parts with {{code|1=\start... … \stop...}}.
Also note that switches like {{cmd|em}} don’t translate into output structure, you need to {{cmd|definehighlight|2=[emph][style=italic]}} and use as {{code|1=\emph{emphasized}.}}
= Useful example =
<texcode>
% mode=mkiv
\mainlanguage[en]
\setupbackend[export=yes]
\setupinteraction[state=start,
color=,contrastcolor=,
% This metadata is used for the PDF
title={My first eBook 1},
subtitle={},
keywords={},
author={Hans 1}
]
\setupexport[
hyphen=yes,
% This metadata is used by ConTeXt’s ePub script
% title, subtitle and author are taken from \setupinteraction, if not set
title={My first eBook 2},
subtitle={},
author={Hans 2}
]
\settaggedmetadata[
% here you can set as many metadata entries as you like, but you need to process them yourself
title={My first eBook 3},
author={Hans 3},
subtitle={},
version={\date} % TODO: doesn’t expand
]
\definehighlight[emph][style=italic] % use \emph{something} instead of {\em something}
\starttext
\startchapter[title=Example]
\startparagraph
\input tufte
\stopparagraph
\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 zapf
\stopparagraph
\stopsection
\stopchapter
\startchapter[title=Quoth\footnote{by Edgar Allan Poe}]
\startlines
\quotation{Prophet!} said I, \quotation{thing of evil!—prophet still, if bird or devil!
By that Heaven that bends above us—by that God we both adore—
Tell this soul with sorrow laden if, within the distant Aidenn,
It shall clasp a sainted maiden whom the angels name Lenore—
Clasp a rare and radiant maiden whom the angels name Lenore.}
\emph{Quoth the Raven \quotation{Nevermore.}}
\stoplines
\stopchapter
\stoptext
</texcode>
Only after such tagging we find significant differences between the three content output files:
TODO: explain differences between export variants
(WORK IN PROGRESS)
There’s an example of an export-friendly ConTeXt file in the sources: {{src|export-example.tex}}.
= Export options =
From {{src|back-exp.mkiv}}, is this still current?
<texcode>
\setupexport[
align=\raggedstatus,
bodyfont=\bodyfontsize,
width=\textwidth,
title={\directinteractionparameter\c!title}, % from interaction
subtitle={\directinteractionparameter\c!subtitle}, % from interaction
author={\directinteractionparameter\c!author}, % from interaction
% firstpage=, % imagename
% lastpage=, % imagename
hyphen=no,
]
</texcode>
* The options align, bodyfont and width end up in the exported CSS.
* firstpage, lastpage: cover image? (how?)
* hyphen: include hyphenation ({{code|1=­}}?)
= More TODO =
* handling of images
* which files get overwritten, which stay
