Difference between revisions of "Epub Sample"

From Wiki
Jump to navigation Jump to search
(Document my personal ePub workflow, first submit)
 
(fix markup)
Line 6: Line 6:
 
I’m using ConTeXt’s [[Project structure]], separating content in products (for me: single booklets) and components (for me: single songs) with a common stylesheet (environment).
 
I’m using ConTeXt’s [[Project structure]], separating content in products (for me: single booklets) and components (for me: single songs) with a common stylesheet (environment).
 
Unfortunately, ConTeXt has a bug in XML creation in this setup.
 
Unfortunately, ConTeXt has a bug in XML creation in this setup.
 +
 +
--[[User:Hraban|Hraban]] 10:19, 27 August 2014 (CEST)
  
 
== ConTeXt setup ==
 
== ConTeXt setup ==
Line 36: Line 38:
 
</texcode>
 
</texcode>
  
Make sure to tag all your structural elements with <cmd>start...</cmd>-<cmd>stop...</cmd>, e.g. <cmd>startchapter</cmd>, but even <cmd>startparagraph</cmd>!
+
Make sure to tag all your structural elements with {{cmd|start...}}-{{cmd|stop...}}, e.g. {{cmd|startchapter}}, but even {{cmd|startparagraph}}!
  
 
Then you can call ConTeXt and its ePub script:
 
Then you can call ConTeXt and its ePub script:
Line 44: Line 46:
 
</code>
 
</code>
  
The first creates export.xml and a bunch of other files.
+
The first creates {{code|export.xml}} and a bunch of other files.
The second creates a directory "ebook.tree" with the proper structure for ePub. The ePub file in the tree directory is unusable.
+
The second creates a directory {{code|ebook.tree}} with the proper structure for ePub. The ePub file in the tree directory is unusable.
  
 
We’ll mostly work with "export.xml" that contains all your content (check that, you’ll miss everything that was not properly tagged).
 
We’ll mostly work with "export.xml" that contains all your content (check that, you’ll miss everything that was not properly tagged).
Line 51: Line 53:
 
== Fix export.xml ==
 
== Fix export.xml ==
  
If you run the epub script on a single file, you’ll get a well-formed and usable export.xml. If you use a project structure, the root node <code>&lt;document&gt;</code> is missing. Just put it in manually (after the comment lines). You can also move the <code>&lt;metadata&gt;</code> block out of the first structure, but that’s merely a cosmetical error.
+
If you run the epub script on a single file, you’ll get a well-formed and usable export.xml. If you use a project structure, the root node {{code|&lt;document&gt;}} is missing. Just put it in manually (after the comment lines). You can also move the {{code|&lt;metadata&gt;}} block out of the first structure, but that’s merely a cosmetical error.
  
A proper export.xml starts like this:
+
A proper {{code|export.xml}} starts like this:
  
<code>
+
<xmlcode>
 
&lt;?xml version="1.0" encoding="UTF-8" standalone="yes" ?&gt;
 
&lt;?xml version="1.0" encoding="UTF-8" standalone="yes" ?&gt;
 
      
 
      
&lt;!-- input filename  : solo              --&gt;
+
&lt;!-- input filename  : solo              -->
&lt;!-- processing date  : Wed Aug 27 13:47:46 2014 --&gt;
+
&lt;!-- processing date  : Wed Aug 27 13:47:46 2014 -->
&lt;!-- context version  : 2014.08.21 09:56  --&gt;
+
&lt;!-- context version  : 2014.08.21 09:56  -->
&lt;!-- exporter version : 0.31              --&gt;
+
&lt;!-- exporter version : 0.31              -->
 
      
 
      
 
&lt;document language="en" file="solo" date="Wed Aug 27 13:47:46 2014" context="2014.08.21 09:56" version="0.31" xmlns:m="http://www.w3.org/1998/Math/MathML"&gt;
 
&lt;document language="en" file="solo" date="Wed Aug 27 13:47:46 2014" context="2014.08.21 09:56" version="0.31" xmlns:m="http://www.w3.org/1998/Math/MathML"&gt;
Line 69: Line 71:
 
  <section detail="chapter" location="aut:1">
 
  <section detail="chapter" location="aut:1">
 
...
 
...
</code>
+
</xmlcode>
  
 
You don’t need the attributes of the document node, even if we could use the language setting.
 
You don’t need the attributes of the document node, even if we could use the language setting.
Line 76: Line 78:
  
 
Even if the ePub format is supposed to work with any XML, most readers only accept HTML.
 
Even if the ePub format is supposed to work with any XML, most readers only accept HTML.
I use the free version of [[http://saxon.sourceforge.net Saxon]] and some XSL transformations for the conversion.
+
I use the free version of [http://saxon.sourceforge.net Saxon] and some XSL transformations for the conversion.
  
The incantation goes like <code>saxon -o:content.xhtml -s:export.xml -xsl:export2html.xsl</code>.
+
The incantation goes like {{code|saxon -o:content.xhtml -s:export.xml -xsl:export2html.xsl}}.
I installed Saxon on my Mac with MacPorts, then instead of just "saxon" you must call <code>java -jar /opt/local/share/java/saxon9he.jar</code>.
+
I installed Saxon on my Mac with MacPorts, then instead of just "saxon" you must call {{code|java -jar /opt/local/share/java/saxon9he.jar}}.
  
This is my **export2html.xsl**:
+
This is my {{code|export2html.xsl}}:
  
<code>
+
<xmlcode>
 
<?xml version="1.0" encoding="UTF-8" ?>
 
<?xml version="1.0" encoding="UTF-8" ?>
 
<xsl:stylesheet version= "2.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
 
<xsl:stylesheet version= "2.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
Line 242: Line 244:
 
h5 = subsection
 
h5 = subsection
 
-->
 
-->
</code>
+
</xmlcode>
 +
 
 +
Now you have a (hopefully usable) (X)HTML file, you need a {{code|style.css}} for the styling.
 +
 
 +
A simple example:
 +
 
 +
<pre>
 +
body {
 +
font-family: TeX Gyre Schola, Century Schoolbook, serif;
 +
font-size: 12pt;
 +
margin: 0 auto;
 +
max-width: 40em;
 +
line-height: 1.44;
 +
-webkit-hyphens: auto;
 +
-moz-hyphens: auto;
 +
-ms-hyphens: auto;
 +
hyphens: auto;
 +
}
 +
 
 +
h1, h2, h3, h4, h4, h6 {
 +
font-family: Devroye;
 +
color: #286000;
 +
-webkit-hyphens: manual;
 +
-moz-hyphens: manual;
 +
-ms-hyphens: manual;
 +
hyphens: manual;
 +
}
 +
 
 +
.part {
 +
page-break-before: always;
 +
}
 +
 
 +
.chapter {
 +
margin-top: 1em;
 +
border-top: 1px solid #600a00;
 +
}
 +
 
 +
.lilypond {
 +
margin: 1em 0;
 +
}
 +
 
 +
.lilypond img {
 +
width: 100%;
 +
}
 +
</pre>

Revision as of 08:21, 27 August 2014

< Epub

Creating an ebook with ConTeXt is still tedious and needs a lot of manual work - that will not change, since everyone has other needs, uses different structures etc. Here I’ll show you my workflow for creating ebooks of my songbooklets (that use LilyPond via filter module for the notes).

I’m using ConTeXt’s Project structure, separating content in products (for me: single booklets) and components (for me: single songs) with a common stylesheet (environment). Unfortunately, ConTeXt has a bug in XML creation in this setup.

--Hraban 10:19, 27 August 2014 (CEST)

ConTeXt setup

In your environment or product, you need these settings (perhaps not all of them):

\setupexport[hyphen=yes,
	%firstpage={cover.jpg}, % is ignored
	title={Songbook},
	subtitle={},
	author={Hraban}
]
\setupbackend[export=export.xml]
\settaggedmetadata[
	% here you can set as many metadata entries as you like
	%firstpage={cover.jpg}, % is ignored
	title={Songbook},
	name=ebook, % this becomes the name of the output directory
	author={Hraban},
	subtitle={}
	version={\expand\currentdate}] % doesn’t work
\setupinteraction[state=start,
	color=,contrastcolor=,
	% these settings are for PDF metadata
	title={Songbook},
	subtitle={},
	keywords={},
	author={Hraban}]

Make sure to tag all your structural elements with \start...-\stop..., e.g. \startchapter, but even \startparagraph!

Then you can call ConTeXt and its ePub script: context mysongbook mtxrun --script epub --make mysongbook

The first creates export.xml and a bunch of other files. The second creates a directory ebook.tree with the proper structure for ePub. The ePub file in the tree directory is unusable.

We’ll mostly work with "export.xml" that contains all your content (check that, you’ll miss everything that was not properly tagged).

Fix export.xml

If you run the epub script on a single file, you’ll get a well-formed and usable export.xml. If you use a project structure, the root node <document> is missing. Just put it in manually (after the comment lines). You can also move the <metadata> block out of the first structure, but that’s merely a cosmetical error.

A proper export.xml starts like this:

<?xml version="1.0" encoding="UTF-8" standalone="yes" ?gt;
    
<!-- input filename   : solo              -->
<!-- processing date  : Wed Aug 27 13:47:46 2014 -->
<!-- context version  : 2014.08.21 09:56  -->
<!-- exporter version : 0.31              -->
    
<document language="en" file="solo" date="Wed Aug 27 13:47:46 2014" context="2014.08.21 09:56" version="0.31" xmlns:m="http://www.w3.org/1998/Math/MathML"gt;
 <metadata>
  <metavariable name="author">Hraban</metavariable>
 </metadata>
 <section detail="chapter" location="aut:1">
...

You don’t need the attributes of the document node, even if we could use the language setting.

Transform XML to HTML etc.

Even if the ePub format is supposed to work with any XML, most readers only accept HTML. I use the free version of Saxon and some XSL transformations for the conversion.

The incantation goes like saxon -o:content.xhtml -s:export.xml -xsl:export2html.xsl. I installed Saxon on my Mac with MacPorts, then instead of just "saxon" you must call java -jar /opt/local/share/java/saxon9he.jar.

This is my export2html.xsl:

<?xml version="1.0" encoding="UTF-8" ?>
<xsl:stylesheet version= "2.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform">

<xsl:output 
	method="xml"
	encoding="utf-8"
	indent="yes"
	omit-xml-declaration="yes"
/>

<xsl:variable name="within-paragraph">0</xsl:variable ><!-- status: are we within a paragraph? -->


<xsl:template match="/">
<html>
<head>
	<meta charset="utf-8" />
	<title><xsl:value-of select='//metavariable[@name="title"]'/> </title>
	<xsl:for-each select="//metavariable">
	<meta>
		<xsl:attribute name="name">
			<xsl:value-of select="@name"/>
		</xsl:attribute>
		<xsl:attribute name="content">
			<xsl:apply-templates/>
		</xsl:attribute>
	</meta>
	</xsl:for-each>
	<link rel="stylesheet" href="style.css" type="text/css" ></link><!-- for testing the html outside the ePub tree -->

	<link rel="stylesheet" href="Styles/style.css" type="text/css" ></link>
</head>
<body lang="de">
	<h1 class="booktitle"><xsl:value-of select='//metavariable[@name="title"]'/></h1>
	<h2 class="subtitle"><xsl:value-of select='//metavariable[@name="subtitle"]'/></h2>
	<p class="author"><xsl:value-of select='//metavariable[@name="author"]'/></p>
	
	<xsl:apply-templates/>
</body>
</html>
</xsl:template>

<xsl:template match="metadata">
</xsl:template>

<xsl:template match="section">
	<a name="{translate(@location,':','_')}"/>
	<div class="{@detail}">
	<xsl:apply-templates/>
	</div>
</xsl:template>

<xsl:template match="sectiontitle">
	<xsl:choose>
		<xsl:when test="../@detail='part'">
			<h2><xsl:apply-templates/>
			</h2>
		</xsl:when>
		<xsl:when test="../@detail='chapter'">
			<h3><xsl:apply-templates/>
			</h3>
		</xsl:when>
		<xsl:when test="../@detail='section'">
			<h4><xsl:apply-templates/>
			</h4>
		</xsl:when>
		<xsl:when test="../@detail='subsection'">
			<h5><xsl:apply-templates/>
			</h5>
		</xsl:when>
		<xsl:otherwise>
			<h6 class="../@detail"><xsl:apply-templates/>
			</h6>
		</xsl:otherwise>
	</xsl:choose>
</xsl:template>

<xsl:template match="sectioncontent">
<div class="{../@detail}-content">
	<xsl:apply-templates/>
</div>
</xsl:template>

<xsl:template match="externalfilter">
<div class="{@detail}">
	<xsl:apply-templates/>
</div>
</xsl:template>

<xsl:template match="lines">
<div class="lines">
	<xsl:apply-templates/>
</div>
</xsl:template>

<xsl:template match="line">
	<xsl:apply-templates/> <br />
</xsl:template>

<xsl:template match="list">
<ul>
	<xsl:apply-templates/>
</ul>
</xsl:template>

<xsl:template match="listitem">
<li><xsl:apply-templates/></li>
</xsl:template>

<xsl:template match="listcontent">
<span class="listcontent"><xsl:apply-templates/></span>
</xsl:template>

<xsl:template match="listpage">
<span class="listpage"><xsl:apply-templates/></span>
</xsl:template>

<xsl:template match="break">
<xsl:if test="within-paragraph = 0">
<xsl:text disable-output-escaping="yes"><![CDATA[</p><p>]]></xsl:text>
</xsl:if>
<xsl:if test="within-paragraph > 0">
<br/>
</xsl:if>
</xsl:template>

<xsl:template match="paragraph">
<xsl:variable name="within-paragraph">1</xsl:variable >
<p><xsl:apply-templates/></p>
<xsl:variable name="within-paragraph">0</xsl:variable >
</xsl:template>

<xsl:template match="delimited">
<span class="delim-{@detail}"><xsl:apply-templates/></span>
</xsl:template>

<xsl:template match="highlight">
<xsl:if test="@detail = 'emph'">
<em><xsl:apply-templates/></em>
</xsl:if>
</xsl:template>

<!-- all the images in my songbook are notes generated by LilyPond via t-filter; in ePub I shorten the file names -->

<xsl:template match="image">
<img src="Images/{substring-after(@name,'prd_songbook-temp-lilypond-')}.png" id="{@id}" alt="{@name}" />
</xsl:template>

<xsl:template match="link">
<a href="#{@location}" title="{@destination}"><xsl:apply-templates/></a>
</xsl:template>

</xsl:stylesheet>

<!--
h1 = book title
h2 = part title
h3 = chapter
h4 = section
h5 = subsection
-->

Now you have a (hopefully usable) (X)HTML file, you need a style.css for the styling.

A simple example:

body {
	font-family: TeX Gyre Schola, Century Schoolbook, serif;
	font-size: 12pt;
	margin: 0 auto;
	max-width: 40em;
	line-height: 1.44;
	-webkit-hyphens: auto;
	-moz-hyphens: auto;
	-ms-hyphens: auto;
	hyphens: auto;
}

h1, h2, h3, h4, h4, h6 {
	font-family: Devroye;
	color: #286000;
	-webkit-hyphens: manual;
	-moz-hyphens: manual;
	-ms-hyphens: manual;
	hyphens: manual;
}

.part {
	page-break-before: always;
}

.chapter {
	margin-top: 1em;
	border-top: 1px solid #600a00;
}

.lilypond {
	margin: 1em 0;
}

.lilypond img {
	width: 100%;
}