<!DOCTYPE html>
<html>
<head>
<meta http-equiv='content-type' value='text/html;charset=utf8'>
<meta name='generator' value='Ronn/v0.7.3 (http://github.com/rtomayko/ronn/tree/0.7.3)'>
<title>gen-epub-book.rs(1) - Generate an ePub book from a simple plaintext descriptor</title>
<style type='text/css' media='all'>
/* style: man */
body#manpage {margin:0}
.mp {max-width:100ex;padding:0 9ex 1ex 4ex}
.mp p,.mp pre,.mp ul,.mp ol,.mp dl {margin:0 0 20px 0}
.mp h2 {margin:10px 0 0 0}
.mp > p,.mp > pre,.mp > ul,.mp > ol,.mp > dl {margin-left:8ex}
.mp h3 {margin:0 0 0 4ex}
.mp dt {margin:0;clear:left}
.mp dt.flush {float:left;width:8ex}
.mp dd {margin:0 0 0 9ex}
.mp h1,.mp h2,.mp h3,.mp h4 {clear:left}
.mp pre {margin-bottom:20px}
.mp pre+h2,.mp pre+h3 {margin-top:22px}
.mp h2+pre,.mp h3+pre {margin-top:5px}
.mp img {display:block;margin:auto}
.mp h1.man-title {display:none}
.mp,.mp code,.mp pre,.mp tt,.mp kbd,.mp samp,.mp h3,.mp h4 {font-family:monospace;font-size:14px;line-height:1.42857142857143}
.mp h2 {font-size:16px;line-height:1.25}
.mp h1 {font-size:20px;line-height:2}
.mp {text-align:justify;background:#fff}
.mp,.mp code,.mp pre,.mp pre code,.mp tt,.mp kbd,.mp samp {color:#131211}
.mp h1,.mp h2,.mp h3,.mp h4 {color:#030201}
.mp u {text-decoration:underline}
.mp code,.mp strong,.mp b {font-weight:bold;color:#131211}
.mp em,.mp var {font-style:italic;color:#232221;text-decoration:none}
.mp a,.mp a:link,.mp a:hover,.mp a code,.mp a pre,.mp a tt,.mp a kbd,.mp a samp {color:#0000ff}
.mp b.man-ref {font-weight:normal;color:#434241}
.mp pre {padding:0 4ex}
.mp pre code {font-weight:normal;color:#434241}
.mp h2+pre,h3+pre {padding-left:0}
ol.man-decor,ol.man-decor li {margin:3px 0 10px 0;padding:0;float:left;width:33%;list-style-type:none;text-transform:uppercase;color:#999;letter-spacing:1px}
ol.man-decor {width:100%}
ol.man-decor li.tl {text-align:left}
ol.man-decor li.tc {text-align:center;letter-spacing:4px}
ol.man-decor li.tr {text-align:right;float:right}
</style>
</head>
<!--
The following styles are deprecated and will be removed at some point:
div#man, div#man ol.man, div#man ol.head, div#man ol.man.
The .man-page, .man-decor, .man-head, .man-foot, .man-title, and
.man-navigation should be used instead.
-->
<body id='manpage'>
<div class='mp' id='man'>
<div class='man-navigation' style='display:none'>
<a href="#NAME">NAME</a>
<a href="#SYNOPSIS">SYNOPSIS</a>
<a href="#DESCRIPTION">DESCRIPTION</a>
<a href="#OPTIONS">OPTIONS</a>
<a href="#DESCRIPTOR-FORMAT">DESCRIPTOR FORMAT</a>
<a href="#ADDITIONAL-CONTENT-PROCESSING">ADDITIONAL CONTENT PROCESSING</a>
<a href="#FREE-DATE-FORMAT-FEATURE">FREE DATE FORMAT FEATURE</a>
<a href="#AUTHOR">AUTHOR</a>
<a href="#REPORTING-BUGS">REPORTING BUGS</a>
<a href="#SEE-ALSO">SEE ALSO</a>
</div>
<ol class='man-decor man-head man head'>
<li class='tl'>gen-epub-book.rs(1)</li>
<li class='tc'></li>
<li class='tr'>gen-epub-book.rs(1)</li>
</ol>
<h2 id="NAME">NAME</h2>
<p class="man-name">
<code>gen-epub-book.rs</code> - <span class="man-whatis">Generate an ePub book from a simple plaintext descriptor</span>
</p>
<h2 id="SYNOPSIS">SYNOPSIS</h2>
<p><code>gen-epub-book</code> IN_FILE OUT_FILE <a href="#OPTIONS" title="OPTIONS" data-bare-link="true">OPTIONS</a></p>
<h2 id="DESCRIPTION">DESCRIPTION</h2>
<p>Generate an ePub book from a simple plaintext descriptor.</p>
<p>Exit values and possible errors:</p>
<pre><code>1 - I/O error
2 - parsing error
3 - file not found
4 - file in wrong state
5 - incorrect amount of elements
6 - required element missing
</code></pre>
<h2 id="OPTIONS">OPTIONS</h2>
<p> -v --verbose</p>
<pre><code>Print out more data.
Default: false.
</code></pre>
<p> IN_FILE</p>
<pre><code>File to parse, must exist, must comply with the DESCRIPTOR FORMAT.
Special case: '-' to read from stdin.
</code></pre>
<p> OUT_FILE</p>
<pre><code>File to write the book to, parent directory needn't exist.
Special case: '-' to write to stdout.
</code></pre>
<p> -S --separator <var>SEPARATOR</var></p>
<pre><code>Enable custom separator feature and set the separator.
Default: ":".
</code></pre>
<p> -I --include [NAME=]PATH</p>
<pre><code>Add an additional directory in which to search for files. Order-dependent.
NAME is an optional name under which the files will be segregated.
PATH is an existing directory.
</code></pre>
<p> -D --free-date</p>
<pre><code>Parse more datetime formats.
See FREE DATE FORMAT FEATURE for details.
</code></pre>
<h2 id="DESCRIPTOR-FORMAT">DESCRIPTOR FORMAT</h2>
<p>The descriptor consists of multiple lines in the format <em>"Key: Value"</em>, unknown
keys are ignored, lines that don't match the format are ignored.</p>
<p> Name</p>
<pre><code>Required: yes
Type: plaintext
Value: e-book's title
Amount: 1
</code></pre>
<p> Content</p>
<pre><code>Required: no
Type: file path
Value: relative path to (X)HTML chunk
Amount: any
Remarks: see ADDITIONAL CONTENT PROCESSING
</code></pre>
<p> String-Content</p>
<pre><code>Required: no
Type: (X)HTML
Value: (X)HTML string
Amount: any
</code></pre>
<p> Image-Content</p>
<pre><code>Required: no
Type: file path
Value: relative path to image to include in e-book
Amount: any
</code></pre>
<p> Network-Image-Content</p>
<pre><code>Required: no
Type: file URL
Value: URL of image to include in e-book
Amount: any
</code></pre>
<p> Cover</p>
<pre><code>Required: no
Type: file path
Value: relative path to image to use as e-book cover
Amount: 0-1
Remarks: exclusive with Network-Cover
</code></pre>
<p> Network-Cover</p>
<pre><code>Required: no
Type: file URL
Value: URL to image to use as e-book cover
Amount: 0-1
Remarks: exclusive with Cover
</code></pre>
<p> Include</p>
<pre><code>Required: no
Type: file path
Value: auxilliary file to include in e-book
Amount: any
</code></pre>
<p> Network-Include</p>
<pre><code>Required: no
Type: file URL
Value: URL of auxilliary file to include in e-book
Amount: any
</code></pre>
<p> Description</p>
<pre><code>Required: no
Type: file URL
Value: relative path to book description
Amount: 0-1
Remarks: exclusive with String-Description and Network-Description
</code></pre>
<p> String-Description</p>
<pre><code>Required: no
Type: (X)HTML
Value: book description
Amount: 0-1
Remarks: exclusive with Description and Network-Description
</code></pre>
<p> Network-Description</p>
<pre><code>Required: no
Type: file URL
Value: URL of book description
Amount: 0-1
Remarks: exclusive with Description and String-Description
</code></pre>
<p> Author</p>
<pre><code>Required: yes
Type: plaintext string
Value: e-book's author
Amount: 1
</code></pre>
<p> Date</p>
<pre><code>Required: yes
Type: RFC3339-compliant date
Value: e-book's authoring/publishing date
Amount: 1
Remarks: see FREE DATE FORMAT FEATURE
</code></pre>
<p> Language</p>
<pre><code>Required: yes
Type: BCP47-compliant language code
Value: language used in e-book
Amount: 1
</code></pre>
<h2 id="ADDITIONAL-CONTENT-PROCESSING">ADDITIONAL CONTENT PROCESSING</h2>
<p>When adding content using the <code>Content</code> entry, the file will additinally be
searched for a comment specifying the its name in the TOC in this format:</p>
<pre><code><!-- ePub title: "TOC_NAME" -->
</code></pre>
<p>Where <code>TOC_NAME</code> is a string not containing the <em>"</em> character.</p>
<p>This will, on e-book readers, allow users to jump directly to the content
represented by the document containing this entry.</p>
<p>Optional.</p>
<h2 id="FREE-DATE-FORMAT-FEATURE">FREE DATE FORMAT FEATURE</h2>
<p>With the -D/--free-date flag, you can enable the free date format feature:
<<a href="https://nabijaczleweli.xyz/content/gen-epub-book/programmer.html#features-free-date-format" data-bare-link="true">https://nabijaczleweli.xyz/content/gen-epub-book/programmer.html#features-free-date-format</a>>.</p>
<p>The supported formats therewith are therefore:</p>
<ul>
<li>RFC3339 (e.g. "2017-02-08T15:30:18+01:00"),</li>
<li>RFC2822 (e.g. "Wed, 08 Feb 2017 15:30:18 +0100"),</li>
<li>Unix timestamp w/timezone (e.g. "1486564218+01:00").</li>
</ul>
<h2 id="AUTHOR">AUTHOR</h2>
<p>Written by nabijaczleweli <<a href="mailto:nabijaczleweli@gmail.com" data-bare-link="true">nabijaczleweli@gmail.com</a>>
and nicohman <<a href="mailto:nicohman@demenses.net" data-bare-link="true">nicohman@demenses.net</a>></p>
<h2 id="REPORTING-BUGS">REPORTING BUGS</h2>
<p><<a href="https://github.com/nabijaczleweli/gen-epub-book.rs/issues" data-bare-link="true">https://github.com/nabijaczleweli/gen-epub-book.rs/issues</a>></p>
<h2 id="SEE-ALSO">SEE ALSO</h2>
<p><<a href="https://github.com/nabijaczleweli/gen-epub-book.rs" data-bare-link="true">https://github.com/nabijaczleweli/gen-epub-book.rs</a>><br />
<<a href="https://nabijaczleweli.xyz/content/gen-epub-book" data-bare-link="true">https://nabijaczleweli.xyz/content/gen-epub-book</a>></p>
<ol class='man-decor man-foot man foot'>
<li class='tl'>gen-epub-book.rs developers</li>
<li class='tc'>March 2019</li>
<li class='tr'>gen-epub-book.rs(1)</li>
</ol>
</div>
</body>
</html>