↩ gen-epub-book​ ↩

# Description

gen-epub-book​ is a loose file to ePub assembly/conversion tool for everyone not afraid of not using Word. gen-epub-book​ allows you to assemble ePub e-books using an easy-to-read, easy-to-write plaintext format.

Thus, "gen-epub-book​" is two things: (1) a plaintext descriptor syntax; and (2) a software tool, that assembles that descriptor and files referenced thereby into an ePub e-book.

The "design goal" of gen-epub-book​’s descriptor syntax is to make it as consistent and obvious at the first sight as possible. The idea is that a gen-epub-book​ descriptor should be writable by any person with minimal technical knowledge.

This guide is designated for non-programmers. If you're a programmer, see the more in-depth programmer's version.

gen-epub-book​ is free software, available under the MIT open source license. See the License heading for more information.

# Discussion

Any topic related to gen-epub-book​ – both the descriptor syntax and the software – is fair game for discussion over at gen-epub-book​'s and this webpage's issue trackers . I've also set up a GitHub issue for simple questions and clarifications. If you don't have a GitHub account, you can shoot me an e-mail .

I hope that these facilities will lead to good ideas for future improvements to gen-epub-book​.

# Installation

If you're running Ubuntu or Windows, you can simply grab a gen-epub-book​.rs executable from the releases page. Those executables should work when ran from anywhere and without any external dependencies.

# Getting started

# Descriptor

Name: A Widow's Trace
​
Include: ../indent.css
Include: effects.css
Content: moments/book.html
​
Author: Aleksandra Łopacińska
Date: 2017-04-23T03:38:52+02:00
Language: pl

# This e-book's title or name
Name: Writing prompt collection
# Relative path to image file used for cover
Cover: writing_prompts/cover.png
​
# Relative path to image file to put in the e-book on its own
Image-Content: writing_prompts/no_the.png
# HTML file to put in the e-book after the previous line
Content: writing_prompts/theless.html
​
# URL to image file on the internet to put in the e-book on its own
Network-Image-Content: https://i.imgur.com/gkevfag.jpg
# URL to HTML file on the internet to put in the e-book
Network-Content: https://nabijaczleweli.xyz/content/writing_prompts/dead_santa.html
​
# Relative path to a file to pack in the e-book (without displaying it)
Include: indent.css
# URL to a file on the internet to pack in the e-book (without displaying it)
Network-Include: https://nabijaczleweli.xyz/content/assets/common.css
​
# e-book's author (that's you!)
Author: nabijaczleweli
# e-book's publication date (in RFC3339 format, see below)
Date: 2017-02-02T13:45:47+01:00
# e-book content's language (in BCP47 format, see below)
Language: en-GB

As you can see, there are four required lines: Name, Author, Date and Language, one or none Cover line, and any number of Content and Image keys. For a complete rundown of all accepted lines, see this table.

first-book
├── rendered
│ ​ ​ ​└── output
│ ​ ​ ​ ​ ​ ​ ​├── intro.html ​ ​ ​ ​ ​ ​# ../../rendered/output/intro.html
│ ​ ​ ​ ​ ​ ​ ​├── main.html ​ ​ ​ ​ ​ ​ ​# ../../rendered/output/main.html
│ ​ ​ ​ ​ ​ ​ ​└── ending.html ​ ​ ​ ​ ​​# ../../rendered/output/ending.html
├── previews
│ ​ ​ ​└── generated
│ ​ ​ ​ ​ ​ ​ ​└── out
│ ​ ​ ​ ​ ​ ​ ​ ​ ​ ​ ├── intro.html ​ ​# ../../previews/generated/out/intro.html
│ ​ ​ ​ ​ ​ ​ ​ ​ ​ ​ └── main.html ​ ​ ​# ../../previews/generated/out/main.html
└── geb
​ ​ ​ ​└── first
​ ​ ​ ​ ​ ​ ​ ​├── intro.html ​ ​ ​ ​ ​ ​ ​# intro.html
​ ​ ​ ​ ​ ​ ​ ​└── book.epupp ​ ​ ​ ​ ​ ​ ​# book.epupp

The Date line must be in the RFC3339 format, which, while sounding scary, can be summarised as YYYY-MM-DDTHH:MM:SS+/-TH:TM. Okay, that still looks scary. You can just use the online epoch time converter to convert any date to RFC3339.

If you specify the --free-date switch as an argument on the command-line, gen-epub-book​ will also accept RFC2822 and Unix timestamp+TH:TM, since these formats might be easier to use,

The Language line must be in the BCP47 format, which effectively means a shorthand for the language in lowercase (en, pl), optionally followed by a hyphen and the language's variant (en-GB).

# Running&assembling

$ gen-epub-book first-book.epupp first-book.epub

# License

The MIT License (MIT)
​
Copyright (c) 2017 nabijaczleweli
​
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
​
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
​
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

# Afterword

Thank you for making it this far. I hope that this document is clear and/or informative, if not, why don't you pop into the issues or slide into the DMs me an e-mail ?