{"id":13761291,"url":"https://github.com/sile-typesetter/casile","last_synced_at":"2025-08-21T10:31:18.573Z","repository":{"id":38186614,"uuid":"79470684","full_name":"sile-typesetter/casile","owner":"sile-typesetter","description":"The CaSILE toolkit, a book publishing workflow employing SILE and other wizardry.","archived":false,"fork":false,"pushed_at":"2024-05-01T13:17:43.000Z","size":5289,"stargazers_count":51,"open_issues_count":34,"forks_count":6,"subscribers_count":5,"default_branch":"master","last_synced_at":"2024-05-01T22:40:59.992Z","etag":null,"topics":["books","casile","ebook-generator","epub-generation","kindlegen","pandoc","pdf","pdf-generation","publishing","sile","typesetting","typesetting-system"],"latest_commit_sha":null,"homepage":"","language":"Lua","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sile-typesetter.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":"citation_audit.vim","codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":["alerque"],"custom":["https://paypal.me/alerque"]}},"created_at":"2017-01-19T16:12:59.000Z","updated_at":"2024-06-29T10:45:30.428Z","dependencies_parsed_at":"2024-01-13T22:03:47.512Z","dependency_job_id":"4987bd4c-175d-4c5c-81a8-457ea3315a85","html_url":"https://github.com/sile-typesetter/casile","commit_stats":{"total_commits":2637,"total_committers":6,"mean_commits":439.5,"dds":"0.0068259385665528916","last_synced_commit":"558d51fc27069dcbb0a965122a9c4516b5676944"},"previous_names":[],"tags_count":72,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sile-typesetter%2Fcasile","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sile-typesetter%2Fcasile/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sile-typesetter%2Fcasile/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sile-typesetter%2Fcasile/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sile-typesetter","download_url":"https://codeload.github.com/sile-typesetter/casile/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":230423553,"owners_count":18223433,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["books","casile","ebook-generator","epub-generation","kindlegen","pandoc","pdf","pdf-generation","publishing","sile","typesetting","typesetting-system"],"created_at":"2024-08-03T13:01:47.624Z","updated_at":"2024-12-19T22:08:13.322Z","avatar_url":"https://github.com/sile-typesetter.png","language":"Lua","funding_links":["https://github.com/sponsors/alerque","https://paypal.me/alerque"],"categories":["Makefile"],"sub_categories":[],"readme":"# CaSILE toolkit\n\n[![Rust Test Status](https://img.shields.io/github/actions/workflow/status/sile-typesetter/casile/rust_test.yml?branch=master\u0026label=Rust+Test\u0026logo=Rust)](https://github.com/sile-typesetter/casile/actions?workflow=Rust+Test)\n[![Docker Build Status](https://img.shields.io/github/actions/workflow/status/sile-typesetter/casile/deploy.yml?branch=master\u0026label=Docker+Build\u0026logo=Docker)](https://github.com/sile-typesetter/casile/pkgs/container/casile)\n[![Rust Lint Status](https://img.shields.io/github/actions/workflow/status/sile-typesetter/casile/rust_lint.yml?branch=master\u0026label=Rust+Lint\u0026logo=Rust)](https://github.com/sile-typesetter/casile/actions?workflow=Rust+Lint)\n[![Lua Lint Status](https://img.shields.io/github/actions/workflow/status/sile-typesetter/casile/luacheck.yml?branch=master\u0026label=Luacheck\u0026logo=Lua)](https://github.com/sile-typesetter/casile/actions?workflow=Luacheck)\n![Reviewdog Lint Status](https://img.shields.io/github/actions/workflow/status/sile-typesetter/casile/shellcheck.yml?branch=master\u0026label=Reviewdog\u0026logo=eslint)\u003cbr /\u003e\n[![Chat on Gitter](https://img.shields.io/gitter/room/sile-typesetter/casile?color=blue\u0026label=Chat\u0026logo=Gitter)](https://gitter.im/sile-typesetter/casile?utm_source=badge\u0026utm_medium=badge\u0026utm_campaign=pr-badge\u0026utm_content=badge)\n[![Conventional Commits](https://img.shields.io/badge/Conventional%20Commits-1.0.0-blue.svg)](https://conventionalcommits.org)\n[![Commitizen Friendly](https://img.shields.io/badge/Commitizen-friendly-blue.svg)](http://commitizen.github.io/cz-cli/)\n\nThe 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.\nThe 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.\nPlain text document formats and a small amount of meta data are transformed automatically into press ready PDFs, E-Books, and rendered promotional materials.\n\nIn traditional publishing workflows the closer a book is to production the harder becomes to work with.\nThe pipeline ‘narrows’ to more and more advanced (complex/expensive) software and more and more restricted access.\nCaSILE completely eschews this limitation completely automating all the ‘later’ production stages.\nBy automating the production workflow from end to end all the normal sequence restrictions are removed.\nBook exterior design can be done at any stage of the process.\nBook interior design can be done at any stage of the process.\nCopy editing can happen simultaneously by different editors on different parts of a book.\nBecause 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.\n\nCaSILE (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).\nAs 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”.\nInitially 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.\n\n## Status\n\nI’ve published dozens of books and other projects this way and have more in progress.\nIt’s now used by at least 3 publishing companies.\nIn other words it *Works for Me™* but your millage may vary.\nThis tool started out as just some scripts baked into one book project.\nThen I worked on another book and copied the scripts over to get started.\nWhen I hit book number 3, it dawned on me I should make my tools more modular and just include them in each project.\nAbout this time I knew I wanted to open source it if it proved useful for more than one _type_ of book.\nThat day came and went.\nOne day I just decided to throw it out there so that it would be easier to explain what I was doing.\nAs 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.\n\nThere are several different ways to use CaSILE, with or without installation.\nOriginally (through v0.2.x) CaSILE focused on use as a submodule to Git projects.\nBeginning with v0.3.0 the primary focus has been on use as CLI tool completely separate from any project.\n\n## Setup\n\nCaSILE can be installed and run locally as a standard CLI program if you’re willing to setup the extensive list of [dependencies](#dependencies).\n\n- Pros: Best (fastest) utilization of system hardware, ability to tinker with the dependencies as their own applications, shell goodies like autocompletion.\n- 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 \u003ctarget\u003e` becomes `casile-vN make \u003ctarget\u003e`).\n\nAs an easier alternative to installing all the dependencies yourself, everything may be run prepackaged together [as a single Docker container](#docker-setup).\n\n- Pros: No dependencies to setup and hence very easy to get started, easy to switch between versions including full matching dependency stack.\n- 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.\n\nIn addition to being run locally, CaSILE can also be run from nearly any remote CI platform.\nIf your book project is on GitHub, you can [add CaSILE to any workflow](#github-action-setup) as a GitHub [Action](https://github.com/marketplace/actions/casile).\nIf your book project is hosted on GitLab, you can easily [configure it to run in GitLab CI](#gitlab-ci-setup).\n\n- Pros: Nothing to download or install locally, easy to share the results of each build.\n- Cons: Long turn around time, must push repository to a supported remote host.\n\nOf course it is also possible to mix and match.\n\n### Local Native Setup\n\nIf you happen to be using Arch Linux the [casile][aur-casile] package on the AUR is all you need.\nAlso 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.\nFor any other platform you’ll either need to be up for an adventure, see [building from source](#building-from-source) (or just use Docker).\nIt is possible to run on macOS if you spend some time pulling in dependencies from Homebrew and elsewhere.\nWindows support will almost certainly require considerable monkey business; [not my circus, not my monkeys][nmcnmm].\n\n### Local Docker Setup\n\nUse 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.\nReady made containers are available from either [Docker Hub][dockerhub] or [GitHub Container Registry][ghcr].\nDownload (or update) an image using  `docker pull docker.io/siletypesetter/casile:latest` or `docker pull ghcr.io/sile-typesetter/casile:latest`.\nNote *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.\n\nOptionally you may build a docker image yourself.\nFrom any CasILE source directory (a Git clone extracted source package), configure using `./configure --disable-dependency-checks`, then build using `make docker`.\nThe resulting image will be available on your system as `sile-typesetter/casile:HEAD`.\n\nIn 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.\nThe full Docker run command can be substituted anywhere you would invoke CaSILE.\nFor convenience you’ll probably want to give yourself an alias:\n\n```bash\nalias casile='docker run -it --volume \"$(pwd):/data\" ghcr.io/sile-typesetter/casile:latest\n```\n\nSave this in your shell’s rc file (e.g. `~/.bashrc`) to persist the alias.\nThis substitution should work anywhere and with any arguments you would have run `casile` for.\n\n### GitHub Action Setup\n\nUse as an Action follows the traditional GitHub Action configuration pattern.\nYou 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.\n\n```yaml\n- name: CaSILE\n  uses: sile-typesetter/casile@latest\n```\n\nIf no arguments are passed, by the Action will default to running `casile make -- default`.\nYou can pass your own arguments using the `args` input parameter.\nThe `DISTDIR` value is output automatically and can be used to post artifacts from your build.\nA complete workflow example `.github/workflows/casile.yml` with customized targets and artifact posting might look like this:\n\n```yaml\nname: CaSILE\non: [push, pull_request]\njobs:\n  casile:\n    runs-on: ubuntu-latest\n    steps:\n      - name: Checkout\n        uses: actions/checkout@v2\n      - id: casile\n        uses: sile-typesetter/casile@latest\n        with:\n          args: make -- pdfs epub renderings\n      - name: Upload artifacts\n        uses: actions/upload-artifact@v2\n        with:\n          name: ${{ steps.casile.outputs.DISTDIR }}\n          path: ${{ steps.casile.outputs.DISTDIR }}\n```\n\nAnother useful paradigm is to run your steps inside the container:\n\n```yaml\nname: CaSILE\non: [push, pull_request]\njobs:\n  casile:\n    runs-on: ubuntu-latest\n    container:\n      image: ghcr.io/sile-typesetter/casile:latest\n      options: --entrypoint=bash\n    steps:\n      - name: Checkout\n        uses: actions/checkout@v2\n      - name: make\n        run: |\n          casile make -- pdfs epub renderings\n      - name: Upload artifacts\n        uses: actions/upload-artifact@v2\n        with:\n          name: pub\n          path: pub\n```\n\nIf you are just starting from scratch, consider using the [casile-template][template] repository to initialize your project.\nFor more ideas and complex examples, check out the [casile-demos][demos] repository.\n\n### GitLab CI Setup\n\nSetup your job to use the CaSILE image and version of your choice, but disable the default entry point:\n\n```yaml\nimage:\n  name: \"siletypesetter/casile:latest\"\n  entrypoint: [\"\"]\nscript:\n  - casile make\n```\n\nUnfortunately GitLab CI can’t name artifacts dynamically (see [upstream report](https://gitlab.com/gitlab-org/gitlab/-/issues/17096)), so you’ll need to define the `DISTDIR` variable yourself.\nA complete pipeline example `.gitlab-ci.yaml` with customized targets and artifact posting might look like this:\n\n```yaml\ndefault:\n  image:\n    name: \"siletypesetter/casile:latest\"\n    entrypoint: [\"\"]\nvariables:\n  DISTDIR: $CI_PROJECT_NAME-$CI_JOB_NAME_SLUG-$CI_COMMIT_SHORT_SHA\ncasile:\n  script:\n    - casile make -- pdfs epub renderings\n  artifacts:\n    name: $DISTDIR\n    paths: [ ./$DISTDIR/* ]\n```\n\n### Dependencies\n\n*Note if you use any of the distro packages, Docker containers, or CI configurations listed in [Setup](#setup) you don't need to worry about these dependencies.*\n\nCaSILE glues together *a lot* of different open source tools to assemble a complete publishing tool chain.\nBehind the scenes this is very messy business.\nIn order to make everything work I’ve had to use an eclectic variety of software.\nAll of these are open source and available across platforms, but I only personally test on Linux.\n\nAll of the following are utilized in one way or another.\nCurrently the toolkit assumes all the following are present, but as not all of them are used to build all resources it could be possible to make this more selective.\nFor example not having the ray tracing engine would just mean no fancy 3D previews of book covers, but you could still build PDFs and other digital formats.\nNot having Node would mean no Bible verse format normalization, but you should still be able to build books.\nNot having ImageMagick would mean no cover images, but you could still process the interior of books.\nOn the other hand not having GNU Make, Pandoc, or SILE would of course be fatal.\n\n* The [SILE][sile] Typesetter is the workhorse behind most of the text layout.\n  Tagged releases of CaSILE should work with latest released version of SILE, git versions may assume the latest Git HEAD versions of SILE.\n* [Pandoc][pandoc] (specifically with [my branch with SILE support][pandocsile]) converts between document types.\n* [ImageMagick][im] handles raster image processing (v7+ required).\n* [POVRay][pov] is used to render 3 dimensional visualizations.\n* [Inkscape][inkscape] is used to layout some cover resources and to convert SVG resources into other formats.\n* [PDFTk][pdftk] is used to manipulate PDFs.\n* [Podofo][podofo] is used to do more stuff with PDFs.\n* [Kindlegen][kindlegen] is needed to generate Amazon’s E-Book formats.\n* [Poppler][poppler] is used to do even more stuff with PDFs.\n* [Zint][zint] generates ISBN barcodes, QR codes, etc.\n* Perl, Python, Lua, Node, Zsh, and a few other language interpreters!\n* Various modules for those languages like `lua-yaml`, `python-ruamel`, `python-isblib`, and `python-pandocfilters`.\n* Up to date versions of assorted shell tools like `jq`, `yq`, `entr`, `bc`, and `sqlite`.\n* The CLI utility variant of [git-warp-time][git-warp-time] (the library variant is also used by Cargo at build time).\n* GNU Make (and assorted other GNU tools) glue everything together.\n* The default book templates assume system installed versions of **Hack**, **Libertinus**, and **TeX Gyre** font sets.\n* Some other stuff (`./configure` will warn you if your system doesn’t have something that’s required).\n\nIn addition to run-time dependencies, compiling the CLI interface (optional) requires a Rust build toolchain.\nOnce built the CLI requires no dependencies to run.\n\nUntil other distros have packages, perhaps the most definitive list of dependencies is the Arch Linux [package meta-dataa](https://aur.archlinux.org/cgit/aur.git/tree/.SRCINFO?h=casile-git).\nYou will need to translate the package names for your platform but everything is listed there.\n\n### Companion tools\n\nYou’ll probably want some other things not provided by CaSILE as well.\nCaSILE takes care of transforming sources to finished outputs, but leaves you to edit the sources and view the outputs yourself.\nFor starters a text editor for working with Markdown \u0026 YAML sources will be a must-have.\nOptions abound here and are mostly out of scope, but think Marktext, Zettlr, Atom, VSCode, Sublime, Vim, etc.\nCaSILE also assumes your book project is tracked in Git, so a client such as the CLI tools or a GUI like GitAhead, Fork, Sourcetree, GitKraken, Tower, or a plugin specific to your editor of choice is a must-have.\nOf course you’ll want a way to view generated PDFs.\nI recommend one that auto updates on file changes; I use [zathura][zathura]), but Okular and quite a few others also support this.\nAn image viewer and an E-Book reader like [Calibre][calibre] are also useful.\n\n### Building from Source\n\n1. Clone the Git repository or download and extract a source archive or source release package.\n\n2. Change to the directory, configure for your system, and build the tools:\n\n    ```console\n    # Only for git clones or source archives...\n    $ ./bootstrap.sh\n\n    # Configure \u0026 build\n    $ ./configure\n    $ make\n    ```\n\n    ```console\n    $ make install\n    ```\n\n    Note if you don't plan to install to your system but would like to compile and run from the source directory (e.g. for development work on CaSILE itself), use `./configure --datarootdir=$(cd ..;pwd); make -B`, then add the CasILE source directory to your `$PATH`.\n\n## Input\n\nCaSILE makes a number of assumptions about the content of your project repository, but how exactly you organize your git repos is still flexible.\nFor example I have some single books in their own repositories, some series of books where the repository holds the whole series, others with different books with the same publisher/copyright status lumped together (and worked on in branches), a set of tracts by assorted authors but published together in another repository, etc.\nCaSILE assumes there is some relation between sources in each repository so granular repositores give more complete control, but each resource in a single repository can also be customized.\nYou’ll have to consider your own workflow and how projects share resources.\nNote that common resources, say defaults for a publisher, can be shared in another submodule(s).\n\nA book project would minimally consist of at least the following:\n\n* casile.mk\n* my_book.md\n* my_book.yml\n\nThere might be more related assets of course, for example a cover background image:\n\n* my_book-background.png\n\nOptionally books may be split into chapters:\n\n* my_book.md\n* my_book-chapters/000-preface.md\n* my_book-chapters/001-chapterone.md\n* my_book-chapters/002-chaptertwo.md\n\n## Output\n\nIn return, CaSILE will output\n\n* Press ready PDFs (high resolution, full bleed w/ crop marks) for the specified press format...\n  * my_book-a5-paperback.pdf\n  * my_book-a5-paperback-cover.pdf\n* User friendly PDFs (normal resolution, indexed, hyperlinked) for any specified size...\n  * my_book-a4-print.pdf\n* Promotional images based on the cover...\n  * my_book-a5-front_cover.jpg\n  * my_book-square-cover.jpg\n* 3D renderings of finished book...\n  * my_book-a5-paperback-3d-front.jpg\n  * my_book-a5-paperback-3d-back.jpg\n  * my_book-a5-paperback-3d-stacks.jpg\n* E-Book formats...\n  * my_book.epub\n  * my_book.mobi\n\n## Usage\n\nBuild whatever resources you need.\nAssuming you have a book source file `my_book.md` and accompanying meta data at `my_book.yml`, the general syntax for generating resources would be:\n\n```console\n$ casile make -- my_book-\u003clayout\u003e-\u003coptions\u003e.\u003cformat\u003e\n```\n\nFor example to build the press ready PDF for an Octavo size version:\n\n```console\n$ casile make -- my_book-octavo-hardback-cover.pdf\n```\n\nOr to build a 3D rendering of the front cover at Halfletter size:\n\n```console\n$ casile make -- my_book-halfletter-paperback-3d-front.jpg\n```\n\nSee also the [CaSILE demos][demos] repository for a sample book project layout.\n\n### Settings\n\nCaSILE has a lot of knobs to fiddle with, and almost anything can be changed.\nThe main trick is understanding where to make changes, because order matters.\n\nAs a broad overview from least specific to most:\n\n* Compile time discovery.\n\n  When CaSILE is configured it runs a bunch of discovery operations (during `./configure`).\n  These detect where dependencies are installed and what versions they are.\n  These can also be manually defined if you wish to substitute some program.\n\n  This stage also generally sets up *where* CasILE will be run from.\n  The configure stage reviews the system for where the package will be installed so it knows where to find itself.\n\n* Baked in run time defaults.\n\n  All settings have some default value baked in that will be used if nothing later overrides them.\n\n* Project rules file.\n\n  Each project may have one or more rules files that are injected intact into the GNU Make runtime. The filename `casile.mk` is suggested, but `rules.mk`, `Makefile`, `makefile`, and `GNUMakeFile` are also considered.\n\n  Your project rules file is easily the most technical way to tie in, and Make’s syntax is often confusing.\n  Many projects will not need this at all –or use it only for simple variable assignments– but almost anything goes.\n\n* Publisher rules file.\n\n  *to be implemented*\n\n* Publisher meta data.\n\n  *to be implemented*\n\n* Project meta data.\n\n  Each project is expected to have a main meta data file in YAML format.\n  The file name should match the project name, which is usually the same name as the git repository directory.\n\n* Book meta data.\n\n  Each book in a project is expected to have a meta data file with book specific information.\n  \n  Note for projects with a single book, this may be the same as the project meta data file.\n\n* Project CaSILE settings file.\n\n  Each project may have a YAML file defining settings that override the defaults and save having to pass them manually on each invocation.\n\n* Run time environment variables.\n\n  Many settings can be set an environment variables and will be considered for each invocation of the CLI.\n\n* Run time flags.\n\n  Some settings have CLI flags that will override any other settings.\n\n#### Project parameters\n\nMost settings apply to a whole project (repository).\nTo override the defaults set them in your project’s `casile.mk`\n\n\n* `LANGUAGE` sets the language for localized file names.\n\n    The default is English, so you might run `casile make -- book-halfletter-3d-front.png`.\n    Changing this to Turkish:\n\n    ```make\n    LANGUAGE = tr\n    ```\n\n    will mean the command you run should be `casile make -- kitap-a5-3b-on.png` to generate the same resource for a similar project with localized filenames.\n    At this time localizations are only included for Turkish, but they are easy enough to add to your project.\n    Submitting them upstream would also me much appreciated.\n\n* `TARGETS` is a list of all the books in a project.\n\n    By default this is set by scanning the project directory and finding all the Markdown files that have matching YAML meta data files of the same name.\n    This helps dodge things like `README.md` files that are not the focus of the meat of a project.\n    You can manually set this with a list:\n\n    ```make\n    TARGETS = book_1 book_2\n    ```\n\n    Or perhaps populate it with a list of _all_ markdown files.\n    You don’t want the extensions here, just the basenames of books to be built:\n\n    ```make\n    TARGETS = $(basename $(wildcard *.md))\n    ```\n\n* `PROJECT` is the name of the overall project (which might contain several books or other works).\n\n    This defaults to the name of the repository directory.\n\n    ```make\n    PROJECT = series_name\n    ```\n\n* `CASILEDIR` is where CaSILE is located.\n    Path from which shared resource files are loaded from.\n    Typically the value set automatically based on the CaSILE installation will be sufficient.\n    This is mostly useful for doing development work on CaSILE itself.\n\n* `PROJECTDIR` is where your project is located.\n    Sources will be examined here and the build process will run here.\n\n    Defaults to the root of the current Git repository.\n    It is unlikely you would ever want to change this.\n\n* `DISTDIR` determines where published files will be placed.\n\n    Output files are first created in the current project directory alongside sources.\n    Optionally CaSILE can ‘install’ finished resources to some other location.\n\n    ```make\n    DISTDIR = /path/to/pub/$(PROJECT)\n    ```\n\n* `FORMATS` contains a list of output formats to build for from each input.\n\n    By default this is set to `pdf epub`, but you may want to build less or more that this.\n    To built \"the works\":\n\n    ```make\n    FORMATS = pdf epub mobi odt docx app\n    ```\n\n    Note this only affects the formats that get built by default from the `default` or `all` targets, you can still build individual resources in any format manually without them being listed here.\n\n* `BLEED` sets the bleed margin for press resources in mm.\n\n    Defaults to 3.\n\n    ```make\n    BLEED = 5\n    ```\n\n* `TRIM` sets the trim margin for press resources in mm.\n\n    Defaults to 10.\n\n    ```make\n    TRIM = 15\n    ```\n\n* `PAPERWEIGHT` sets the paperweight (in grams) used to calculate book thickness and hence spine width.\n\n    Defaults to 60.\n\n    ```make\n    PAPERWEIGHT = 80\n    ```\n\n* `COVERGRAVITY` tells the cover generator what direction to crop background images when adjusting for different aspect ration.\n\n    Defaults to Center.\n    Possible options are anything that ImageMagick understands, so South, SouthWest, NorthEast, etc.\n\n    ```make\n    COVERGRAVITY = North\n    ```\n\n#### Build time settings\n\nThese settings are usually not changed except at run time.\nYou _may_ set them in your rules file such as `casile.mk` but they would typically be set as environment variables or on the command line to get other-than-default behavior for a specific build.\n\n* `DRAFT` enables draft mode builds for faster testing.\n\n    This defaults to false, but may be set to true when executing make:\n\n    ```console\n    $ casile make -- DRAFT=true book-a4-binding.pdf\n    ```\n\n    What this does will depend on the resource type.\n    Books are only typeset in one pass, so TOC’s may be out of date, cover images are generated at 17th final resolution, 3D renderings are done with partial lighting for faster ray-tracing, etc.\n\n    Note that `casile make -- watch ...` automatically enables this mode.\n\n* `HIGHLIGHT_DIFF` enables highlighting differences between git branches.READ\n\n    Defaults to false.\n\n    Note this works in conjunction with the `PARENT` variable.\n    When pre-processing the source of books, the current commit will be compared to the branch (or commit) defined by PARENT.\n    Any differences (at the character level) will be marked up using CriticMarkup syntax.\n    Some output formats (notably PDF) will syntax highlight any additions/removals.\n\n* `STATSMONTHS` sets the default time frame to report on activity.\n\n    Defaults to 1.\n\n    At the end of each month I run `casile make -- stats` to run a report of all commit activity on the content of books.\n    This computes the current character and word counts and compares them with each previous commit and shows a report crediting the author of that commit.\n    I use this to pay our translators, editors, etc.\n\n    Override with `casile make -- STATSMONTHS=2 stats`.\n\n\n* `DEBUG` enables extra output from various programs showing whats going on during a build.\n\n    Defaults to false, set to true to enable.\n\n    This will be pretty verbose on the console.\n    Shell scripts will run with `set -x`, programs that have them will be run with debug flags turned on, etc.\n\n* `DEBUGTAGS` sets the specific parts of the SILE typesetter to debug.\n    See SILE documentation for details.\n\n    Defaults to casile.\n\n    ```make\n    DEBUGTAGS = casile insertions frames\n    ```\n\n    Usage from the command line might be `casile make -- DEBUG=true DEBUGTAGS=frames book-a4.pdf`.\n\n* `COVERS` can be used to disable generating cover images.\n    Raster image generation can take time, this skips those steps and just assumes no graphical covers are present.\n\n    Defaults to true, set to false to disable.\n\n* `HEAD` sets how many lines of input books to process.\n\n    Default is unset.\n\n    If setting this to an integer, only that many lines of an input book will be processed.\n    This is useful when styling a book.\n    You can work on the first chapter worth of lines and rebuild the book quickly, then turn it off to regenerate the whole book.\n\n    ```console\n    $ casile make -- HEAD=50 book-octavo.pdf\n    ```\n\n* `SCALE` sets the factor by which to downsample resources while in draft mode.\n\n    Defaults to 17. This brings 1200 dpi print resources down to 70 dpi.\n\n* `HIDPI` sets the output resolution for press resources.\n\n    Defaults to 1200 with scaling for draft mode enabled.\n\n    This may be set to an another value with or without scaling.\n    For example for a one off command you might run:\n\n    ```console\n    $ casile make -- HIDPI=600 book-octavo-binding.pdf\n    ```\n\n    But to change the project default you might set this in your rules file:\n\n    ```make\n    HIDPI = $(call scale,600)\n    ```\n\n* `LODPI` is much the same as `HIDPI` but used for regular discribution resources.\n\n    Defaults to 300 with scaling for draft mode enabled.\n\n#### Hooks\n\nThese are functions that can be defined in your project’s `Makefile` to add additionally functionality at various points in the process.\nYou make use either single or multiline syntax as desired, but note the input, output, and variables passed will be the same either way.\nOn the other hand each hook has its own usage so note the context it runs in.\n\n[arch-alerque]: https://wiki.archlinux.org/index.php/Unofficial_user_repositories#alerque\n[aur-casile-git]: https://aur.archlinux.org/packages/casile-git/\n[aur-casile]: https://aur.archlinux.org/packages/casile/\n[calibre]: http://calibre-ebook.com/\n[demos]: https://github.com/sile-typesetter/casile-demos\n[dockerhub]: https://hub.docker.com/repository/docker/siletypesetter/casile/\n[ghcr]: https://github.com/orgs/sile-typesetter/packages/container/package/casile\n[git-warp-time]: https://crates.io/crates/git-warp-time\n[im]: http://imagemagick.org/\n[inkscape]: https://inkscape.org/\n[kindlegen]: https://www.amazon.com/gp/feature.html?docId=1000234621\n[nmcnmm]: https://duckduckgo.com/?q=%22Not+My+Circus%2C+Not+My+Monkeys%22\u0026ia=images\n[pandoc]: http://pandoc.org/\n[pandocsile]: https://github.com/jgm/pandoc/pull/6088\n[pdftk]: https://www.pdflabs.com/tools/pdftk-the-pdf-toolkit/\n[podofo]: http://podofo.sourceforge.net/\n[poppler]: https://poppler.freedesktop.org/\n[pov]: http://www.povray.org/\n[sile]: https://sile-typesetter.org\n[template]: https://github.com/sile-typesetter/casile-template\n[zathura]: https://pwmt.org/projects/zathura/\n[zint]: https://zint.github.io/\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsile-typesetter%2Fcasile","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsile-typesetter%2Fcasile","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsile-typesetter%2Fcasile/lists"}