CaSILE toolkit

<br />

The CaSILE toolkit is a build system that glues together a large collection of tools into a cohesive system that automates book publishing from start to finish. The concept is to take very simple, easily edited content and configuration files as input and turn them into all the artifacts of a finished product with as little manual intervention as possible. Plain text document formats and a small amount of meta data are transformed automatically into press ready PDFs, E-Books, and rendered promotional materials.

In traditional publishing workflows the closer a book is to production the harder becomes to work with. The pipeline ‘narrows’ to more and more advanced (complex/expensive) software and more and more restricted access. CaSILE completely eschews this limitation completely automating all the ‘later’ production stages. By automating the production workflow from end to end all the normal sequence restrictions are removed. Book exterior design can be done at any stage of the process. Book interior design can be done at any stage of the process. Copy editing can happen simultaneously by different editors on different parts of a book. Because the pipeline doesn’t narrow as projects progress and the content is always front and center the only restrictions on the workflow are those dictated by you for the project, not by the tooling used.

CaSILE (pronounced /ˈkɑːs(ə)l/ just like ‘castle’) started out life as a submodule called avadanlik included inside my book project repositories (avadanlık being a Turkish word for something like a tackle box). As most of the parts revolved around SILE, in my head at least CaSILE became Caleb’in Avadanlığı birlikte SILE, roughly translating to “SILE with Caleb’s Toolkit”. Initially everything was hard coded in Turkish, but eventually I added localization for English and generalized most of the tooling so it can be used for books in nearly any language.

Status

I’ve published dozens of books and other projects this way and have more in progress. It’s now used by at least 3 publishing companies. In other words it Works for Me™ but your millage may vary. This tool started out as just some scripts baked into one book project. Then I worked on another book and copied the scripts over to get started. When I hit book number 3, it dawned on me I should make my tools more modular and just include them in each project. About this time I knew I wanted to open source it if it proved useful for more than one type of book. That day came and went. One day I just decided to throw it out there so that it would be easier to explain what I was doing. As such in many ways it is hard coded to my publishing needs any adaption to be more flexible only happens as people request or contribute the changes.

There are several different ways to use CaSILE, with or without installation. Originally (through v0.2.x) CaSILE focused on use as a submodule to Git projects. Beginning with v0.3.0 the primary focus has been on use as CLI tool completely separate from any project.

Setup

CaSILE can be installed and run locally as a standard CLI program if you’re willing to setup the extensive list of dependencies.

• Pros: Best (fastest) utilization of system hardware, ability to tinker with the dependencies as their own applications, shell goodies like autocompletion.
• Cons: System packages typically only support one version at a time, manual installation supports parallel versions but must be instantiated with the appropriate affix (.e.g. if installed with ./configure --program-suffix=-vN then casile make <target> becomes casile-vN make <target>).

As an easier alternative to installing all the dependencies yourself, everything may be run prepackaged together as a single Docker container.

• Pros: No dependencies to setup and hence very easy to get started, easy to switch between versions including full matching dependency stack.
• Cons: Tricky to setup access to fonts or other resources available outside your project source, some overhead in startup time and reduced CPU and memory resources.

In addition to being run locally, CaSILE can also be run from nearly any remote CI platform. If your book project is on GitHub, you can add CaSILE to any workflow as a GitHub Action. If your book project is hosted on GitLab, you can easily configure it to run in GitLab CI.

• Pros: Nothing to download or install locally, easy to share the results of each build.
• Cons: Long turn around time, must push repository to a supported remote host.

Of course it is also possible to mix and match.

Local Native Setup

If you happen to be using Arch Linux the [casile][aur-casile] package on the AUR is all you need. Also a [casile-git][aur-casile-git] recipe is available, and packages (including all dependencies) can be installed directly from [this repo][arch-alerque]) for easy setup. For any other platform you’ll either need to be up for an adventure, see building from source (or just use Docker). It is possible to run on macOS if you spend some time pulling in dependencies from Homebrew and elsewhere. Windows support will almost certainly require considerable monkey business; [not my circus, not my monkeys][nmcnmm].

Local Docker Setup

Use of a Docker container can make it a lot easier to get up and running because you won’t need to have a huge collection of dependencies installed. Ready made containers are available from either [Docker Hub][dockerhub] or [GitHub Container Registry][ghcr]. Download (or update) an image using docker pull docker.io/siletypesetter/casile:latest or docker pull ghcr.io/sile-typesetter/casile:latest. Note latest will be the most recent stable tagged release, or you may substitute a specific tag (e.g. vX.Y.Z), master for the more recent Git commit build, or v0 for the more recent tagged release in that major series.

Optionally you may build a docker image yourself. From any CasILE source directory (a Git clone extracted source package), configure using ./configure --disable-dependency-checks, then build using make docker. The resulting image will be available on your system as sile-typesetter/casile:HEAD.

In order to invoke CasILE from Docker you need to pass in your project files on a volume that will also serve as a place it can write it’s output. The full Docker run command can be substituted anywhere you would invoke CaSILE. For convenience you’ll probably want to give yourself an alias:

alias casile='docker run -it --volume "$(pwd):/data" ghcr.io/sile-typesetter/casile:latest

Save this in your shell’s rc file (e.g. ~/.bashrc) to persist the alias. This substitution should work anywhere and with any arguments you would have run casile for.

GitHub Action Setup

Use as an Action follows the traditional GitHub Action configuration pattern. You can specify the exact version you want, v0 for the most recent tagged release in the same major version sequence, latest far the very latest tagged release of any sequence, or master for the latest development build.

- name: CaSILE
  uses: sile-typesetter/casile@latest

If no arguments are passed, by the Action will default to running casile make -- default. You can pass your own arguments using the args input parameter. The DISTDIR value is output automatically and can be used to post artifacts from your build. A complete workflow example .github/workflows/casile.yml with customized targets and artifact posting might look like this:

name: CaSILE
on: [push, pull_request]
jobs:
  casile:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v2
      - id: casile
        uses: sile-typesetter/casile@latest
        with:
          args: make -- pdfs epub renderings
      - name: Upload artifacts
        uses: actions/upload-artifact@v2
        with:
          name: ${{ steps.casile.outputs.DISTDIR }}
          path: ${{ steps.casile.outputs.DISTDIR }}

Another useful paradigm is to run your steps inside the container:

name: CaSILE
on: [push, pull_request]
jobs:
  casile:
    runs-on: ubuntu-latest
    container:
      image: ghcr.io/sile-typesetter/casile:latest
      options: --entrypoint=bash
    steps:
      - name: Checkout