https://github.com/l3nz/dockbooker
Create multi-format Asciidoc books from the command line - using Docker
https://github.com/l3nz/dockbooker
asciidoc docker fop pdf
Last synced: about 1 year ago
JSON representation
Create multi-format Asciidoc books from the command line - using Docker
- Host: GitHub
- URL: https://github.com/l3nz/dockbooker
- Owner: l3nz
- License: mit
- Created: 2015-05-22T05:10:01.000Z (about 11 years ago)
- Default Branch: master
- Last Pushed: 2020-11-11T16:17:00.000Z (over 5 years ago)
- Last Synced: 2023-03-12T08:54:29.703Z (over 3 years ago)
- Topics: asciidoc, docker, fop, pdf
- Language: XSLT
- Homepage:
- Size: 693 KB
- Stars: 11
- Watchers: 3
- Forks: 2
- Open Issues: 4
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# dockbooker
Create multi-format eBooks from the command line - using Docker.
Run a Docker image to transform your AsciiDoc documentation to:
* Multipart HTML
* PDF
* EPUB
It also makes sure that your images fit, and reprocesses them according to your destination media (for
example, images for PDF are to be 150dpi, JPEGs have a defined compression ratio, etc.)
## Getting started
If you have Docker installed, just clone the repo, then go to "sample_book" and run "make".
The sample document will be compiled to all formats - PDF, HTML and EPUB.
## Using
The Docker image expects sources to be mounted as /in and output to be mounted as /out. Though the
contents of /in are read-only, it is perfectly acceptable to map /in and /out to the same folder.
You will run the Docker image as:
docker run -it --rm \
-v $(readlink -m .):/in \
-v $(readlink -m ./out):/out \
lenz/dockbooker \
/make/all
The first line runs the image and removes it when terminated. The second and third line
mount volumes on /in and /out (note that we have to use readlink to make local paths absolute).
The last line runs the correct command "/make/all".
# Creating books
A book is created out of a folder containing an Asciidoc file, its images and a manifest
file dockbooker.json.
The manifest:
* Defines what to compile and how to name the resulting file
* Defines how you want your images processed
The idea is that you keep images in the simplest possibe format - be it text (for dotfiles) or
high-resoution, full-color graphics.
When rendering, dockbooker takes care of rendering the images with a size and a resolution
that looks good, but is usually compressed - for example, PNGs are reduced to 256 colors
and packed. So for each image you can simply add to your repo the image as-is, without processing it,
and dockbooker will process it.
The idea is that images can be either MAXI (full page), MIDI (about 2/3) and MINI (about 1/3 of the page).
## Creating PDFs with covers
It is possible to customize PDFs by adding Docbook customization files. The one supplied lets you add
a picture on the cover page and a small logo on the footer of each page.
In theory, you can customize the appearance of Docbook books quite a lot. In practice, it's so
absurdly complex that any contribution on how to do this in practice is welcome.
The supplied XSLT file includes:
* An image on the cover page, scaled to be 8.0 cm tall
* An image in the footer, scaled to be 1.0 cm tall
Feel free to improve it.
See also:
* Tips on using fonts: http://www.simon-cozens.org/content/docbook-fop-fonts-and-multilingua
* Preprocessing fonts: http://www.incenp.org/notes/2012/fop-ttf-fonts.html
* A (long) list of FOP configuration parameters: http://docbook.sourceforge.net/release/xsl/1.77.0/doc/fo/
* Fonts embedded in FOP: https://xmlgraphics.apache.org/fop/2.0/fonts.html