https://github.com/nuew/ebooktool
Common files for ebook building
https://github.com/nuew/ebooktool
Last synced: 2 months ago
JSON representation
Common files for ebook building
- Host: GitHub
- URL: https://github.com/nuew/ebooktool
- Owner: nuew
- License: isc
- Created: 2025-04-20T06:24:09.000Z (9 months ago)
- Default Branch: main
- Last Pushed: 2025-04-20T22:13:12.000Z (9 months ago)
- Last Synced: 2025-05-05T10:52:38.501Z (8 months ago)
- Language: PostScript
- Homepage:
- Size: 12.7 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# nuew's ebooktool
## Requirements and Building
[GNU Make], [Pandoc] and [TeX Live] must be installed and be located in your `$PATH`. This
repository is intended for, and has only been tested in the context of a Unix and/or [WSL]
environment.
To build everything, simply run `make` in this directory. To build a single book or ebook, run
`make $filename`, where `$filename` is the name of the target file. To build:
- all covers, run `make covers`.
- all EPUBs, run `make epub`
- all PDFs, run `make pdf`
- all DOCXs, run `make docx`
- all ODTs, run `make odt`
To delete all generated files, run `make clean`.
## Creating a Project
To create a project, create a git repository as follows:
```sh
git init
git submodule add https://github.com/nuew/ebooktool
```
Then, create a Makefile in the directory as follows:
```make
# To add a book, add the name of the output files here, with a variable name matching the name of
# the book's directory under chapters/. Then add that variable name to the `books` list below.
covers ::=
books ::=
EBOOKTOOL ::= ebooktool
include $(EBOOKTOOL)/ebooktool.mk
```
## Directory Structure
The book and ebook sources in your project should be arranged into several folders.
| Filename | Description |
|-----------|-----------------------------------------------------------------------------------------------------------------------|
| .github/ | CI configuration. |
| back/ | The backmatter of the (e)book; included in alphanumeric order. |
| chapters/ | Every chapter of each book. Books are in individual subfolders. Inserted in alphanumeric order. |
| covers/ | Cover images for PDF, EPUB, and in original resolution, as well as PostScript source for the PDFs of physical covers. |
| metadata/ | Metadata for each book. Separated into shared, PDF, and EPUB. There is also some global PDF metadata. |
| style/ | CSS files for EPUBs. Each book can have an individual file, but most just use the global style. |
## Adding a new book
To add a new book, first update the Makefile; you'll want to add a line to establish an association
between the target name and the output file basename:
```make
targetname ::= OutputFileBasename
```
You'll also need to add the new book's target name to the end of the `books` variable.
If the book has a PostScript cover wrap, you'll need to add it to the `covers` variable too.
```make
covers ::= foo bar mynewbook
books ::= foo bar baz qux mynewbook
```
From here, you need to add files to contain the book's metadata. These go under the `metadata`
folder, and should be two YAML files: `.yaml` and `.epub.yaml`. EPUBs have a
second metadata file, which is combined with the primary one, as EPUB files have substantially
richer metadata capabilities, in some cases requiring different values for certain fields. It's
probably easiest to copy an existing book's files, but be sure to replace the UUID identifier in the
EPUB metadata file (it's used to identify a specific title) and the `group-position` value (it's
easy to forget).
The EPUB cover and EPUB CSS files are discovered and added to metadata automatically. Their location
must match the patterns of `covers/.epub.jpg` and `style/.css`. As a matter of
convention, the highest quality cover should be stored at `covers/.png` (in some cases, only
a JPEG image is available, in which case `covers/.jpg` is acceptable), and a CSS file common
among all EPUBs is located at `style/style.css`. The EPUB cover should have dimensions of
approximately 2560x1600, with a filesize of about 600 kiB; `magick .png -resize 1600x2560
-quality 80 .epub.jpg` is a good start for the command to produce such an image.
If you're using a PostScript cover wrap, it also goes into covers, as `covers/.ps`. The
raster cover image used for the PostScript cover wrap should be located at
`covers/.cover.jpg`, but this can reasonably be a symlink to `covers/.jpg`. Note
that this is the only external file that the PostScript script will be allowed to read. The
`PDFX_def.ps`, `conf.ps`, and `lib.ps` scripts from `covers/common` are injected into the cover wrap
compilation as libraries. In general, you probably shouldn't use this feature; it exists solely for
legacy reasons.
Now that the book is set up, we can add the content. Create a directory under `chapters` with the
target name (e.g. `chapters/mynewbook`), and create an individual markdown file in that directory
for each chapter. There are two helper scripts for this: `prepareDocx.sh` and `processRR.sh`, which
are a complete script to convert a docx file into a chapter subdirectory without requiring much
further processing, and a vague template to help give an idea of what to do with chapters scraped
from Royal Road, respectively. Chapter files are inserted into the book in alphanumeric order; as a
matter of convention, they should be named matching the format `-.md`.
There are a few things in chapters that can only be manually processed; these include conversion of
chat messages to div blocks for custom styling and postprocessing (implemented in
`filters/chat.lua`), and conversion of baked small-caps to normal text styled by CSS (improving
full-text search/a11y in the ebook, and making things work at all in the PDF). Doing the first of
these automatically has been considered, but determining what is intended to be a chat message
automatically is hard™. Doing the second automatically is substantially easier; the only real
concern is that it isn't directly doable by `sed` (though it is by a Perl oneliner), and that
determining the bounds for the span is *probably* best done manually. This is a feature to look out
for (or implement yourself), though!
### Chat Message Conversion
Before:
```markdown
**\[Alice\]: The quick brown fox jumps over the lazy dog.**
**\[Bob\]: Jackdaws love my big sphinx of quartz.**
**\[Charlie\]: How quickly daft jumping zebras vex!**
```
After:
```markdown
::: {.chat .discord}
[Alice]{.username .alice}
The quick brown fox jumps over the lazy dog.
[Bob]{.username .bob}
Jackdaws love my big sphinx of quartz.
[Charlie]{.username .charlie}
How quickly daft jumping zebras vex!
```
`style/style.css` has both `.discord` and `.twitch` classes, which approximate the appearance of
chat messages on those platforms. In any case, this makes chat messages much more amenable to custom
styling, including individual colors for each user. Styling can also be used to avoid substantially
changing the appearance of chat messages at all, if desired by the author.
### Small Caps Conversion
Vim:
```vimscript
dt""='[' . tr(@@, 'ᴀʙᴄᴅᴇꜰғɢʜɪᴊᴋʟᴍɴᴏᴘʀꜱᴛᴜᴠᴡʏᴢ', 'abcdeffghijklmnoprstuvwyz') . ']{.smallcaps}'p
```
Perl oneliner
```bash
perl -Mopen=locale -Mutf8 -pe 'y/ᴀʙᴄᴅᴇꜰɢʜɪᴊᴋʟᴍɴᴏᴘʀꜱᴛᴜᴠᴡʏᴢ/abcdefghijklmnoprstuvwyz/'
```
[GNU Make]: https://www.gnu.org/software/make/
[Pandoc]: https://pandoc.org/
[WSL]: https://docs.microsoft.com/en-us/windows/wsl/about
[TeX Live]: https://tug.org/texlive/