SILE Typesetter Documentation

SILE includes a default set of Citation Style Language (CSL) style files for testing and implementation purposes. These files are sourced from the official Citation Style Language project.

Note that these files are provided for convenience; for the most up-to-date styles, you should refer to the official Citation Style Language project.

To provide support for a new language in SILE, you must implement a combination of the following components:

1. A base module: This is a required component for any language support.
2. Hyphenation patterns module: Provides rules for the Knuth-Liang hyphenation algorithm.
3. Localization strings: Provides translations for strings output in documents via a messages.ftl file for each locale.

SILE provides several layout features that distinguish it from TeX-based systems:

• Complex Layouts: Use frames to produce sophisticated document layouts.
• Extensibility: The system can be extended using the Lua programming language.
• XML Processing: Directly process XML to PDF without requiring XSL stylesheets.
• Grid Layouts: Typeset text on a defined grid.

SILE includes a default set of locale files for Citation Style Language (CSL) styles to facilitate testing and default behavior. These files are sourced from the official Citation Style Language project.

Note that because these are provided for convenience within the SILE repository, they may not always be the most recent versions available from the upstream CSL project.

Docker images are available on Docker Hub as siletypesetter/sile. You can use the latest tag or specific version tags (e.g., v0.10.0).

To use SILE effectively in Docker, you must mount your project directory as a volume so SILE can access source files and write output.

Accessing System Fonts: By default, the container does not have access to your host's fonts. To fix this, mount your host's font directory to /fonts inside the container.

# Create an alias for easier usage (mounts current dir to /data)
$ alias sile='docker run -it --volume "$(pwd):/data" siletypesetter/sile:latest'
$ sile input.sil

# Run with host fonts mounted to /fonts
$ docker run -it --volume "/usr/share/fonts:/fonts" --volume "$(pwd):/data" siletypesetter/sile:latest

You can install SILE on macOS using Homebrew. You can choose between the stable release or the latest development version from the git HEAD.

Note: The Homebrew package does not automatically install the default font (Gentium Plus). It is recommended to install it via the Homebrew Fonts caskroom.

Building from source requires a Rust toolchain and Lua sources. SILE relies on HarfBuzz (min version 2.7.4), fontconfig, and ICU libraries.

Key Steps:

1. Ensure dependencies (HarfBuzz, fontconfig, ICU, OpenSSL development headers) are installed.
2. If using a Git clone, run ./bootstrap.sh first.
3. Run ./configure and make.
4. Use sudo make install to install to the system.

Developer Mode: If you are developing SILE, use the --enable-developer-mode flag during configuration. This sets the 'installed data' directory to your source location, allowing the binary to run directly from the source without installation, and enables testing targets like make regressions.

You can automate document rendering in a CI environment using GitHub Actions. The easiest way is to use the sile-typesetter/sile@v0 action. This action assumes your repository contains a source file (e.g., my-document.sil) and will output a PDF (e.g., my-document.pdf).

name: SILE
on: [ push, pull_request ]
jobs:
  sile:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v3
      - name: Render document with SILE
        uses: sile-typesetter/sile@v0
        with:
          args: my-document.sil

SILE is available in the official repositories for several Linux distributions:

• Arch Linux: Uses the official package. If using LuaRocks via pacman, use lua51-* variants to match LuaJIT.
• Fedora: Available in official repositories. You may need to install fonts separately.
• OpenSUSE: Available via zypper.
• NixOS: Available in both stable and unstable channels.
• Ubuntu: Available via a PPA.
• Void Linux: Available in the default package manager.

# Arch Linux
$ pacman -S sile

# Fedora
$ dnf install sile
# To install default fonts on Fedora:
$ dnf install sil-gentium-plus-fonts alerque-libertinus-fonts hack-fonts

# OpenSUSE
$ zypper install sile

# Ubuntu
$ add-apt-repository ppa:sile-typesetter/sile
$ apt-get update
$ apt-get install sile

Nix is a viable alternative for running SILE on most platforms (Linux, BSD, macOS, and Windows via WSL). The unstable channel is recommended for the latest releases.

You can launch a shell with SILE available or run it directly as a single command. Since the source is a Nix Flake, you can also run specific tagged versions or branches directly.

# Launch a new shell with SILE available
$ nix shell nixpkgs/nixpkgs-unstable#sile
$ sile <arguments>

# Run SILE directly as a single command
$ nix run nixpkgs/nixpkgs-unstable#sile -- <arguments>

# Explicitly run a tagged version
$ nix run github:sile-typesetter/sile/v0.14.13 -- <arguments>

# Run the master branch HEAD
$ nix run github:sile-typesetter/sile -- <sile arguments>

# Run the develop branch HEAD
$ nix run github:sile-typesetter/sile/develop -- <sile arguments>