Skip to content

Commit

Permalink
docs(readme): Freshed info and copy edit a bunch of sections
Browse files Browse the repository at this point in the history
  • Loading branch information
@alerque
alerque committed Dec 22, 2023
1 parent 3e3134e commit c44e74c
Showing 1 changed file with 75 additions and 47 deletions.
122 changes: 75 additions & 47 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -70,8 +70,7 @@ If you install LuaRocks for use with SILE via `pacman`, use the `lua51-*` varian

#### Fedora

A [COPR][copr] repository is available for Fedora users with packages of SILE
and all the necessary dependencies.
A [COPR][copr] repository is available for Fedora users with packages of SILE and all the necessary dependencies.
Fedora 38 and later are supported.
There is work in progress to get the packages added to the official Fedora repository.

Expand All @@ -90,7 +89,8 @@ $ zypper install sile

#### NixOS

A [Nix `sile` package][nix] is available in both the stable and unstable channels; the unstable channel having the latest stable SILE releases and the stable channel being frozen on NixOS releases.
A [Nix `sile` package][nix] is available in both the stable and unstable channels;
the unstable channel having the latest stable SILE releases and the stable channel being frozen on NixOS releases.
You can use all the usual Nix tricks including adding SILE into a `nix shell` environment or executing it directly with `nix run`.

See additional usage notes in the [Nix section](#nix).
Expand Down Expand Up @@ -132,9 +132,15 @@ Prebuilt Windows binaries are supposed to be generated by the Azure [build pipel
#### Docker

Docker images are available as [siletypesetter/sile](https://hub.docker.com/repository/docker/siletypesetter/sile).
Released versions are tagged to match (e.g. `v0.10.0`), the latest release will be tagged `latest`, and a `master` tag is also available with the freshest development build.
In order to be useful you need to tell the Docker run command a way to reach your source documents (and hence also to give it a place to write the output) as well as tell it who you are on the host machine so the output generated inside the container can be created with the expected ownership properties.
You may find it easiest to run with an alias like this:
Released versions are available as tagged containers matching the release (e.g. `v0.10.0`).
Additionally the latest release will be tagged `latest`, and a `master` tag is also available with the freshest development build.

In order to be useful you need to tell the Docker run command a way to reach your source documents.
This is done by mounting your project directory inside the container.
This also gives SILE a place to write the output.
For ownership and permissions of output generated inside the container to match the host, the expected user ids need to be passed as well.

You may find it easiest to do all this with an alias like this:

```console
$ alias sile='docker run -it --volume "$(pwd):/data" --user "$(id -u):$(id -g)" siletypesetter/sile:latest'
Expand All @@ -153,33 +159,47 @@ $ docker run -it --volume "/usr/share/fonts:/fonts" --volume "$(pwd):/data" --us

#### Nix

The `nix` package manager is available as a standalone package manager on many platforms other than NixOS including most Linux and BSD distributions, macOS, and even for Windows via WSL; and thus presents a viable alternative way to run SILE on most systems.
The `nix` package manager is available as a standalone package manager on many platforms other than NixOS including most Linux and BSD distributions, macOS, and even for Windows via WSL;
and thus presents a viable alternative way to run SILE on most systems.

[Nix packages][nix] are available in both the stable and unstable channels.
Because all packages are first made available in the unstable channel and then eventually make their way into the stable channel, to get the latest stable SILE releases we recommend hitting up the unstable channel first.
We recommend the unstable channel because all fresh packages (including stable SILE releases) land there first and eventually trickle down to the stable channel.
You can use all the usual Nix tricks including launching a new shell with the `sile` command available or running it directly from any shell:

```console
# 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>
```

The SILE source repository is also a valid Nix [Flake][nix-flakes] which means you can run any specific version or the latest unreleased development code directly:
The SILE source repository is also a [Nix Flake][nix-flakes].
This means you can run any arbitrary tagged version, branch, or commit with a single command.
This is an easy way to run SILE on other platforms, but also to test other versions or run the latest development version of SILE.

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

# Use the master branch HEAD that will become the next minor release
$ nix run github:sile-typesetter/sile -- <sile arguments>

# Run the develop branch HEAD that will become the next major release
$ nix run github:sile-typesetter/sile/develop -- <sile arguments>
```

### From Source

SILE source code can be downloaded from [its website][sile] or directly from [the GitHub releases page][releases].

SILE is written in the Lua programming language, so you will need a working Lua installation on your system (Lua 5.1, 5.2, 5.3, 5.4, and LuaJIT (2.0, 2.1, or OpenResty) are fully supported).
SILE is written in the Lua programming language, so you will need a working Lua installation on your system.
Lua 5.1, 5.2, 5.3, 5.4, and LuaJIT (2.0, 2.1, or OpenResty) are all fully supported.

It also relies on external libraries to access fonts and write PDF files.
Its preferred combination of libraries is [Harfbuzz][harfbuzz] and [libtexpdf][], a PDF creation library extracted from TeX. Harfbuzz (minimum version 1.1.3) should be available from your operating system's package manager.
Its preferred combination of libraries is [Harfbuzz][harfbuzz] and [libtexpdf][], a PDF creation library extracted from TeX.
Harfbuzz (minimum version 1.1.3) should be available from your operating system’s package manager.
For Harfbuzz to work you will also need fontconfig installed.
SILE also requires the [ICU][icu] libraries for Unicode handling.

Expand All @@ -195,9 +215,10 @@ If you try to `brew link` and you get a series of messages including something l
For pkg-config to find icu4c you may need to set:
export PKG_CONFIG_PATH="/usr/local/opt/icu4c/lib/pkgconfig"

Optionally you may install the Lua libraries listed in the [rockspec][] to your system (using either your system's package manager or [luarocks][] (`luarocks install --only-deps sile-dev-1.rockspec`).
Optionally you may install the Lua libraries listed in the [rockspec][] to your system (using either your system’s package manager or [luarocks][] (`luarocks install --only-deps sile-dev-1.rockspec`).
By default all the required Lua libraries will be downloaded and bundled alongside the SILE the installation.
If you downloaded a source tarball these dependencies are included, if you are using a git clone of the source repository the build system will require `luarocks` to fetch them during build.
If you downloaded a source tarball these dependencies are included.
If you are using a Git clone of the source repository the build system will require `luarocks` to fetch them during build.
Note that OpenSSL development headers will be required for one of the Lua modules to compile¹.
If your system has all the required packages already you may add `--with-system-luarocks` to the `./configure` command to avoid bundling them.

Expand All @@ -212,38 +233,43 @@ $ ./bootstrap.sh
```

If you just plan on installing and using SILE, the default configure options (plus any Lua related options discussed above) should be fine.
If you plan on developing SILE itself (whether just to hack on it for your own use or contribute upstream) there are two particularly useful configuration options.
First you can add `--datarootdir=$(cd ..;pwd)` which will enable the compiled binary to run directly from the source directory without being installed at all.
Second you can add `--enable-developer` to also check for tooling we expect SILE developers to have such as tools used for testing.
Using this options also enables a number of targets that wouldn't normally be needed by end users such as `make regressions`.
If you plan on developing SILE itself (whether to just tinker with it for your own use or contribute upstream) there is one particularly useful configuration option.
You can add `--enable-developer` will set the 'installed data' directory to the source location which will enable the compiled binary to run directly from the source directory without being installed at all.
Additionally it will enable checks for tooling we expect SILE contributors to have such as tools used for testing.
Using this options also enables a number of targets that wouldn’t normally be needed by end users such as `make regressions`.

Once your dependencies are installed and you know what options you want, it is time to configure the sources, then build, then install:
Once your dependencies are installed and you know what options you want, it is time to configure the sources, then build them.

```console
$ ./configure
$ make
$ make install
```

This will place the SILE libraries and executable in a sensible location.
If you just want to mess with SILE locally you can stop here (especially if you used `--enable-developer`).
However to actually install, you will need to run the installation command with system permissions.

```console
$ sudo make install
```

On some systems you may also need to run:
On some systems you may also need to make the system aware of the newly installed libraries before first use:

```console
$ ldconfig
```

… before trying to execute `sile` to make the system aware of the newly installed libraries.

### Default Font

Since SILE v0.9.5, the default font has been Gentium Plus which is freely available from [SIL’s site][gentium].
It is not absolutely required that you install it, but if this font is not installed on your system, you won't be able to use the examples without modification.
(Previously we used Gentium Basic, but that's getting harder to get hold of.)
(Previously we used Gentium Basic, but that’s getting harder to get hold of.)
The math package uses [Libertinus Math][libertinus] by default to render formulas.
Additionally, monospace text by default is set in [Hack][hack].
It is not absolutely required that you install default fonts, but if this font is not installed on your system you won’t be able to use the examples without modification.

### Testing the installation

If all goes well, after installation you should be able to render a sample document. Try creating a file `test.sil` with this content:
If all goes well, after installation you should be able to render a sample document.
Try creating a file `test.sil` with this content:

```sil
\begin{document}
Expand Down Expand Up @@ -305,7 +331,7 @@ First you make add `--tree ./` to install them in the current directory.
In this case (and assuming this is the same directory as your document) SILE will automatically find such plugins.
Additionally you make install them to your user profile by adding `--local` when installing.
In this case you will also need to modify your user environment to check for plugins in that path since Lua does not do so by default.
This can be done by running `eval $(luarocks path)` before running SILE (or from your shell's initialization script).
This can be done by running `eval $(luarocks path)` before running SILE (or from your shell’s initialization script).

### Finding Lua version in use for running SILE

Expand All @@ -322,7 +348,7 @@ $ luarocks install --lua-version $LUA_VERSION ...

Please read the [full SILE manual][doc] for more information about what SILE is and how it can help you.
There are example documents (source and PDF) [on the SILE website][examples].
There's also an [FAQ][faq] available.
There’s also an [FAQ][faq] available.

## Contact

Expand All @@ -333,32 +359,34 @@ For questions and discussion, please join the [mailing list][list-en].

SILE is distributed under the [MIT licence][license].

[sile]: http://www.sile-typesetter.org/
[releases]: https://github.com/sile-typesetter/sile/releases
[alerque-arch]: https://wiki.archlinux.org/index.php/Unofficial_user_repositories#alerque
[arch-sile]: https://archlinux.org/packages/extra/x86_64/sile/
[aur]: https://wiki.archlinux.org/index.php/Arch_User_Repository
[azure]: https://dev.azure.com/sile-typesetter/sile/_build?view=runs
[rockspec]: https://github.com/sile-typesetter/sile/blob/master/sile-dev-1.rockspec
[brew]: http://brew.sh
[brewfonts]: https://github.com/Homebrew/homebrew-cask-fonts
[copr]: https://copr.fedorainfracloud.org/coprs/jonny/SILE/
[doc]: http://sile-typesetter.org/manual/sile-latest.pdf
[examples]: http://www.sile-typesetter.org/examples/
[faq]: https://github.com/sile-typesetter/sile/wiki/faq
[gentium]: http://software.sil.org/gentium/download/
[github]: https://github.com/sile-typesetter/sile
[license]: http://choosealicense.com/licenses/mit/
[faq]: https://github.com/sile-typesetter/sile/wiki/faq
[examples]: http://www.sile-typesetter.org/examples/
[linuxbrew]: https://docs.brew.sh/Homebrew-on-Linux
[luarocks]: http://luarocks.org/en/Download
[hack]: https://sourcefoundry.org/hack/
[harfbuzz]: http://www.freedesktop.org/wiki/Software/HarfBuzz/
[icu]: http://icu-project.org
[libtexpdf]: https://github.com/sile-typesetter/libtexpdf
[arch-sile]: https://archlinux.org/packages/extra/x86_64/sile/
[aur]: https://wiki.archlinux.org/index.php/Arch_User_Repository
[typesetting]: https://en.wikipedia.org/wiki/Typesetting
[tex]: https://en.wikipedia.org/wiki/TeX
[indesign]: https://en.wikipedia.org/wiki/Adobe_InDesign
[brew]: http://brew.sh
[brewfonts]: https://github.com/Homebrew/homebrew-cask-fonts
[libertinus]: https://github.com/alerque/libertinus
[libtexpdf]: https://github.com/sile-typesetter/libtexpdf
[license]: http://choosealicense.com/licenses/mit/
[linuxbrew]: https://docs.brew.sh/Homebrew-on-Linux
[list-en]: https://groups.google.com/d/forum/sile-users
[nix]: https://nixos.org/nix
[luarocks]: http://luarocks.org/en/Download
[nix-flakes]: https://nixos.wiki/wiki/Flakes#Installing_flakes
[nix]: https://nixos.org/nix
[ports]: http://ports.su/print/sile
[ppa]: https://launchpad.net/~sile-typesetter/+archive/ubuntu/sile
[copr]: https://copr.fedorainfracloud.org/coprs/jonny/SILE/
[alerque-arch]: https://wiki.archlinux.org/index.php/Unofficial_user_repositories#alerque
[releases]: https://github.com/sile-typesetter/sile/releases
[rockspec]: https://github.com/sile-typesetter/sile/blob/master/sile-dev-1.rockspec
[sile]: http://www.sile-typesetter.org/
[tex]: https://en.wikipedia.org/wiki/TeX
[typesetting]: https://en.wikipedia.org/wiki/Typesetting

0 comments on commit c44e74c

Please sign in to comment.