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.
To create a project, create a git repository as follows:
git init
git submodule add https://github.com/nuew/ebooktoolThen, create a Makefile in the directory as follows:
# 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.mkThe 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. |
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:
targetname ::= OutputFileBasenameYou'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.
covers ::= foo bar mynewbook
books ::= foo bar baz qux mynewbookFrom here, you need to add files to contain the book's metadata. These go under the metadata
folder, and should be two YAML files: <target>.yaml and <target>.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/<target>.epub.jpg and style/<target>.css. As a matter of
convention, the highest quality cover should be stored at covers/<target>.png (in some cases, only
a JPEG image is available, in which case covers/<target>.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 <target>.png -resize 1600x2560 -quality 80 <target>.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/<target>.ps. The
raster cover image used for the PostScript cover wrap should be located at
covers/<target>.cover.jpg, but this can reasonably be a symlink to covers/<target>.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 <chapter number>-<lowercase chapter name with '-'s instead of spaces>.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!
Before:
**\[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:
::: {.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.
Vim:
dt""='[' . tr(@@, 'ᴀʙᴄᴅᴇꜰғɢʜɪᴊᴋʟᴍɴᴏᴘʀꜱᴛᴜᴠᴡʏᴢ', 'abcdeffghijklmnoprstuvwyz') . ']{.smallcaps}'<CR>pPerl oneliner
perl -Mopen=locale -Mutf8 -pe 'y/ᴀʙᴄᴅᴇꜰɢʜɪᴊᴋʟᴍɴᴏᴘʀꜱᴛᴜᴠᴡʏᴢ/abcdefghijklmnoprstuvwyz/'