# 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

gen-epub-book​'s descriptor syntax is line-based – each line in the file specifies one element of the e-book. Here's an example of how a descriptor for a simple book can look:
Name: A Widow's TraceInclude: ../indent.css
Include: effects.css
Content: moments/book.htmlAuthor: Aleksandra Łopacińska
Date: 2017-04-23T03:38:52+02:00
Language: pl
And here's another one, but this time with comments explaining what's what:
# 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.

All local paths are relative to the descriptor file. The comments in the following directory tree show the paths to the files, relative to geb/special/book.epupp:
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
When referenced from HTML, their names must be known. The specified names are processed and packed under the names resulting from this algorithm. Packed names of files from the internet is their URL name.

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

If you have your descriptor and are ready to assemble it into an e-book open the console and run:
$ gen-epub-book first-book.epupp first-book.epub
After which, if you did everything right and gen-epub-book​ didn't throw you an error, you should now have a file called first-book.epub. Congratulations! You can now read, verify and convert it using, e.g., Calibre.

# 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 ?


Creative text licensed under CC-BY-SA 4.0, code licensed under The MIT License.
This page is open-source, you can find it at GitHub, and contribute and/or yell at me there.
Like what you see? Consider giving me a follow over at social medias listed here, or maybe even a donation , if my software helped you in some significant way?
Automatically generated with GCC 4‍.‍6‍.‍3's C preprocessor on 10.12.2018 21:37:25 UTC from src/gen-epub-book/index.html.pp.
See job on TravisCI.
RSS feed