155 lines
4.0 KiB
Markdown
155 lines
4.0 KiB
Markdown
# epubmaker
|
|
|
|
## Description
|
|
A tool that assists in the creation of epub files from html marked source.
|
|
|
|
## Installation
|
|
|
|
Requires Python 3.10 or later.
|
|
|
|
```bash
|
|
git clone <repository-url>
|
|
cd epubmaker
|
|
pip install .
|
|
```
|
|
|
|
For development:
|
|
|
|
```bash
|
|
pip install -e .
|
|
pip install pytest
|
|
```
|
|
|
|
## Usage
|
|
|
|
```
|
|
python -m epubmaker <source_file> [-f] [-v]
|
|
```
|
|
|
|
| Argument | Description |
|
|
|---|---|
|
|
| `source_file` | Path to the HTML source file |
|
|
| `-f`, `--force` | Overwrite an existing output directory |
|
|
| `-v`, `--verbose` | Print progress as each step completes |
|
|
|
|
**Examples:**
|
|
|
|
```bash
|
|
# Basic usage
|
|
python -m epubmaker mybook.html
|
|
|
|
# Overwrite a previously generated output
|
|
python -m epubmaker -f mybook.html
|
|
|
|
# Verbose output
|
|
python -m epubmaker -v mybook.html
|
|
```
|
|
|
|
The tool creates an output directory and a `.epub` file in the current working directory, both named after the value of the `Directory:` directive in the source file.
|
|
|
|
### Source file format
|
|
|
|
The source file is an HTML file. Metadata and structure are declared using HTML comment directives. The file must be located in a directory that also contains an `Images/` subdirectory.
|
|
|
|
**Required `Images/` contents:**
|
|
- `cover.jpeg` — cover image
|
|
- `Inconsolata-Regular.otf`, `invisible1.ttf`, `MgOpenModataRegular.ttf` — bundled fonts
|
|
- Any additional images referenced in the file
|
|
|
|
#### Metadata directives
|
|
|
|
These appear before any section directives. All names in `Last, First` format.
|
|
|
|
| Directive | Description |
|
|
|---|---|
|
|
| `<!-- Directory: name -->` | Output directory name (required) |
|
|
| `<!-- Title: Book Title -->` | Book title (required) |
|
|
| `<!-- Author: Last, First -->` | Author; repeat for multiple authors |
|
|
| `<!-- Editor: Last, First -->` | Editor |
|
|
| `<!-- Artist: Last, First -->` | Cover artist |
|
|
| `<!-- Publisher: Name -->` | Publisher |
|
|
| `<!-- Copyright: statement -->` | Copyright statement |
|
|
| `<!-- ISBN: number -->` | ISBN |
|
|
| `<!-- UUID: uuid -->` | UUID; leave blank to auto-generate |
|
|
| `<!-- Source: title -->` | Source work |
|
|
| `<!-- Subjects: subject, subject -->` | Comma-separated subjects |
|
|
| `<!-- Series: number Name -->` | Series index and name |
|
|
| `<!-- Cover: cover.jpeg -->` | Cover image filename |
|
|
|
|
#### Section directives
|
|
|
|
Each section directive opens a new section. All HTML content that follows — until the next directive — becomes that section's body. The `id` field is used as the output filename (e.g., `ch1` → `ch1.xhtml`).
|
|
|
|
```
|
|
<!-- Text: id Section Title -->
|
|
```
|
|
|
|
| Directive | Section type |
|
|
|---|---|
|
|
| `<!-- TitlePage: id Title -->` | Title page |
|
|
| `<!-- CopyrightPage: id Title -->` | Copyright page |
|
|
| `<!-- Dedication: id Title -->` | Dedication |
|
|
| `<!-- TOC: id Title -->` | Table of contents |
|
|
| `<!-- Foreward: id Title -->` | Foreword |
|
|
| `<!-- Text: id Title -->` | Body chapter |
|
|
| `<!-- Notes: id Title -->` | Notes |
|
|
| `<!-- Acknowledgement: id Title -->` | Acknowledgements |
|
|
| `<!-- License: id Title -->` | License |
|
|
|
|
#### Image directive
|
|
|
|
Used within a section to embed an image. Supported formats: `jpg`, `jpeg`, `png`.
|
|
|
|
```
|
|
<!-- Image: filename.jpg Alt text::Caption text -->
|
|
```
|
|
|
|
The caption is optional. To omit it, leave it blank:
|
|
|
|
```
|
|
<!-- Image: filename.jpg Alt text:: -->
|
|
```
|
|
|
|
#### Stylesheet
|
|
|
|
Link a CSS file using a standard `<link>` tag and the tool will extract and bundle it:
|
|
|
|
```html
|
|
<link rel="stylesheet" href="path/to/style.css" type="text/css" />
|
|
```
|
|
|
|
#### Minimal example
|
|
|
|
```html
|
|
<!-- Directory: mybook -->
|
|
<!-- Title: My Book -->
|
|
<!-- Author: Smith, Jane -->
|
|
<!-- Publisher: My Press -->
|
|
<!-- ISBN: 978-0-000-00000-0 -->
|
|
<!-- UUID: -->
|
|
<!-- Cover: cover.jpeg -->
|
|
|
|
<!-- TitlePage: tp My Book -->
|
|
<h1>My Book</h1>
|
|
<h2>Jane Smith</h2>
|
|
|
|
<!-- TOC: toc Table of Contents -->
|
|
<nav>...</nav>
|
|
|
|
<!-- Text: ch1 Chapter One -->
|
|
<h2>Chapter One</h2>
|
|
<p>Body text goes here.</p>
|
|
```
|
|
|
|
## Support
|
|
Tell people where they can go to for help. It can be any combination of an issue tracker, a chat room, an email address, etc.
|
|
|
|
## Roadmap
|
|
Modify this code to use pypub.
|
|
|
|
## Authors and acknowledgment
|
|
Rory Hinnen
|
|
|
|
## License
|
|
GPL 3.0
|