Lib.rs

什么是SILE？

SILE是一个排版系统；其任务是为打印文档生成美丽的效果。从概念上讲，SILE与TeX类似——它从中借用了一些概念和语法以及算法，但相似之处到此为止。SILE不是一个TeX家族的衍生品，而是一个从头开始使用现代技术编写，并从图形系统如InDesign借用了一些想法的新排版和布局引擎。

在哪里运行？

SILE可以下载并安装到您的系统中，或者作为CI作业远程运行。

我可以用SILE做什么（而我不能用TeX做）？

首先，看看用法示例画廊。SILE允许您

• 使用框架生成复杂的文档布局。

• 使用高级编程语言（Lua）轻松扩展排版系统。

• 直接将XML处理为PDF，不使用XSL样式表。

• 在网格上排版文本。

下载和安装

对于macOS

Homebrew提供安装稳定版或最新预构建版的公式。对于最新预构建的稳定版

$ brew install sile

或者从最新的git提交构建和安装

$ brew install sile --HEAD

注意，Homebrew包不会自动安装默认字体。通过Homebrew字体caskroom安装Gentium Plus是最简单的方法

$ brew tap homebrew/cask-fonts
$ brew install --cask font-gentium-plus

对于Linux

Arch Linux

Arch Linux官方软件仓库中有一个预构建的SILE软件包

$ pacman -S sile

官方包使用LuaJIT。如果您想通过pacman安装LuaRocks并与SILE一起使用，请使用lua51-*变体以匹配LuaJIT。

Fedora

为Fedora用户提供了COPR仓库，其中包含SILE及其所有必需的依赖项的软件包。支持Fedora 38及更高版本。目前正在努力将软件包添加到官方Fedora仓库中。

$ dnf copr enable jonny/SILE
$ dnf install sile

OpenSUSE

OpenSUSE已准备好官方软件包，可以通过常规方式安装。

$ zypper install sile

NixOS

在稳定和不稳定频道中都可以找到Nix sile 软件包；不稳定频道拥有最新的稳定版SILE发布，而稳定频道则冻结在NixOS发布上。您可以像使用所有常规Nix技巧一样使用SILE，包括将其添加到nix shell环境或直接使用nix run执行。

请参阅Nix部分中的其他使用说明。

Ubuntu

为Ubuntu用户提供了包含SILE及其所有必需依赖项的PPA。我们从Bionic（18.04）开始引入了对支持。只要Canonical提供支持，我们就会维护所有Ubuntu版本系列的相关软件包。

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

Void Linux

Void Linux的软件包可在默认的软件包管理器中找到。

其他

其他Linux发行版可以通过源、通过Linux Brew或通过Nix进行安装。

对于BSD

可以从OpenBSD ports、通过源或通过Nix安装。

对于Windows

目前还没有安装程序（请在问题#410中跟踪状态）。目前没有人维护SILE的Windows兼容性，我们预计状态可能有些损坏。使用WSL（Windows Subsystem for Linux）的用户可以根据系统安装选择他们偏好的软件包管理器，包括相应的Arch Linux或Ubuntu软件包、Linux Brew、源或通过[Nix][#nixos]。

在仓库中存在一些早期工作，应该可以启用通过CMake和Visual Studio构建，请参阅问题#567中的讨论，但它需要针对当前依赖项进行刷新。预构建的Windows可执行文件应由Azure 构建管道生成，并且可以通过选择一个构建、打开Windows作业、选择最终阶段的工件链接以及使用sile文件夹旁边的下载按钮进行下载。

多平台与容器

Docker

Docker镜像作为siletypesetter/sile可用。发布版本作为标记容器提供，与发布匹配（例如，v0.10.0）。此外，最新版本将标记为latest，还有一个带有最新开发构建的master标记。

为了使其有用，您需要告诉Docker运行命令一种到达源文档的方式。这可以通过在容器内挂载您的项目目录来实现。这也为SILE提供了一个写入输出的地方。Docker用户的用户和组ID将自动调整为与挂载的目录匹配。

您可能会发现使用这样的别名来做所有这些事情最简单。

$ alias sile='docker run -it --volume "$(pwd):/data" siletypesetter/sile:latest'
$ sile input.sil

使用 Docker 容器中的 SILE 有一个显著的问题，那就是默认情况下，它无法访问您的系统字体。为了解决这个问题，您可以将一个字体文件夹（任何组织可用的字体config）映射到容器中。这可以是你系统的默认字体目录、你的用户字体目录、一个具有特定项目资源的文件夹，或者你选择的任何文件夹。您可以使用 fc-list 查看系统中的字体位置。您从主机系统选择的路径应该以卷的形式挂载到容器中的 /fonts，如下所示

$ docker run -it --volume "/usr/share/fonts:/fonts" --volume "$(pwd):/data" siletypesetter/sile:latest

Nix

nix 包管理器不仅作为 NixOS 的独立包管理器可用，而且在许多平台上也可用，包括大多数 Linux 和 BSD 发行版、macOS，甚至通过 WSL 在 Windows 上可用；因此，它为在大多数系统上运行 SILE 提供了一种可行的替代方法。

Nix 包 在稳定和不稳定频道中都有提供。我们推荐使用不稳定频道，因为所有新包（包括稳定的 SILE 版本）首先出现在那里，然后最终慢慢流入稳定频道。您可以使用所有的常规 Nix 技巧，包括使用具有 sile 命令的新 shell 或在任何 shell 中直接运行它

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

SILE 源代码库也是一个 Nix Flake。这意味着您可以使用单个命令运行任何标记版本、分支或提交。这是在平台上运行 SILE 的简单方法，也可以用来测试其他版本或运行 SILE 的最新开发版本。

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

从源代码

SILE 源代码可以从其 网站 或直接从 GitHub 发布页面 下载。

SILE 可以使用 Lua 编程语言完全编程。截至 v0.15.0，您实际执行的 CLI 是一个嵌入 Lua VM 的 Rust 二进制文件。（出于兼容性和演示目的，纯 Lua 版本的 CLI 仍然作为 \code{sile-lua} 提供。）Rust 二进制文件可以基于您的系统 Lua 源构建，或者使用其自己的 vendored Lua 源。所有 SILE 的 Lua 代码都采用了 Lua 兼容性的最低共同标准方法。Lua 5.1、5.2、5.3、5.4 或 LuaJIT（2.0、2.1 或 OpenResty）都得到完全支持。将其编译与您的系统 Lua 版本匹配可以使它容易访问系统安装的 Lua Rocks，但这不是必需的。

从源代码编译需要 Rust 工具链和 Lua 源。在运行时不需要 Rust 工具，并且实际上不使用系统 Lua 解释器。

它还依赖于外部库来访问字体和写入 PDF 文件。它首选的库组合是 HarfBuzz 和从 TeX 提取的 PDF 创建库 libtexpdf。HarfBuzz（最低版本 2.7.4）应从您的操作系统包管理器中提供。为了使 HarfBuzz 正常工作，您还需要安装 fontconfig。SILE 还需要用于 Unicode 处理的 ICU 库。

在 macOS 上，可以通过 Homebrew 安装 ICU

$ brew install icu4c

之后，您可能需要设置环境变量。如果您尝试 brew link 并收到一系列消息，包括类似以下两行的内容，您将需要运行该 export 行以正确设置您的路径

For pkg-config to find icu4c you may need to set:
  export PKG_CONFIG_PATH="/usr/local/opt/icu4c/lib/pkgconfig"

您可以选择安装rockspec中列出的Lua库到您的系统中（使用系统包管理器或luarocks (luarocks install --only-deps sile-dev-1.rockspec）。默认情况下，所有所需的Lua库将与SILE一起下载并捆绑安装。如果您下载了源tar包，这些依赖项已包含在内。如果您使用源代码仓库的Git克隆版，构建系统将需要在构建过程中使用luarocks获取它们。请注意，编译其中一个Lua模块需要OpenSSL开发头文件¹。如果您的系统已经安装了所有所需的包，您可以在./configure命令中添加--with-system-luarocks以避免捆绑它们。

¹ _{构建luasec需要OpenSSL开发头文件，请在尝试构建SILE之前确保它们已设置好！如果您使用系统Luarocks包，这将为您完成，否则请确保您能够编译luasec。您可以在构建SILE之前单独尝试这一步，使用luarocks --tree=/tmp install luasec。}

如果您从git克隆构建，首先运行脚本以设置环境（如果您使用源tar包，则无需此步骤）

$ ./bootstrap.sh

如果您只是计划安装和使用SILE，默认的配置选项（以及上面讨论的任何Lua相关选项）应该就足够了。如果您计划开发SILE本身（无论是为了自己使用进行修改还是向上游贡献）有一个特别有用的配置选项。您可以通过添加--enable-developer-mode将“已安装数据”目录设置为源位置，这将使编译的二进制文件可以直接从源目录运行而不需要进行安装。此外，它将启用检查我们期望SILE贡献者拥有的工具，例如用于测试的工具。使用此选项还将启用一些通常不需要由最终用户使用的目标，例如make regressions。

一旦您的依赖项安装完毕并且您知道您想要什么选项，就是时候配置源并构建它们了。

$ ./configure
$ make

如果您只是想在本地上修改SILE，可以在这里停止（特别是如果您使用了--enable-developer-mode）。然而，为了实际安装，您需要以系统权限运行安装命令。

$ sudo make install

在某些系统上，您可能还需要在首次使用之前让系统了解新安装的库

$ ldconfig

默认字体

从SILE v0.9.5开始，默认字体是Gentium Plus，它可以从SIL的网站免费获取。（之前我们使用Gentium Basic，但现在越来越难获取。）数学包默认使用Libertinus Math来渲染公式。此外，默认的等宽文本设置为Hack。您不需要安装默认字体，但如果这个字体没有安装在您的系统上，您将无法在不修改的情况下使用示例。

测试安装

如果一切顺利，安装后您应该能够渲染一个示例文档。尝试创建一个名为 test.sil 的文件，并包含以下内容

\begin{document}
Hello world!
\end{document}

并像这样将其渲染为 PDF

$ sile test.sil
SILE v0.12.5 (Lua 5.4)
<test.sil>
[1]

现在您应该有一个准备审查的 PDF 文件 test.pdf

用作 CI 作业

实际上有很多方法可以在 CI 工作流程中将 SILE 远程运行。由于这些包适用于许多平台，一种方法就是使用您平台的原生包安装系统将它们拉入您已经使用的任何 CI 运行环境。另一种方法是拉入预构建的 Docker 容器并运行它。

作为一个案例研究，以下是如何在 GitHub Actions 中设置工作流程

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

将其添加到您的仓库中，作为 .github/workflows/sile.yaml。此工作流程假定您的项目有一个源文件 my-document.sil，并会留下一个 my-document.pdf。注意有关 Docker 部分的注释，关于版本标签。

安装第三方包

可以使用 luarocks 包管理器安装第三方 SILE 包。包可以托管在任何地方，无论是在默认的 luarocks.org 仓库中，还是在特定的服务器清单中（如下例所示）。例如，要安装 markdown.sile（一个提供读取和处理 Markdown 文档的 SILE 输入器的插件），可以运行

$ luarocks install --server=https://luarocks.org/dev markdown.sile

默认情况下，这将尝试将包安装到您的系统中。这可能不是所希望的（并且通常需要 root 权限），但有另外两种安装插件的方法。首先，您可以将 --tree ./ 添加到安装它们到当前目录。在这种情况下（假设这与您的文档目录相同）SILE 将自动找到这样的插件。此外，您还可以通过在安装时添加 --local 将它们安装到您的用户配置文件中。在这种情况下，您还需要修改您的用户环境，以在该路径中查找插件，因为 Lua 默认不这样做。这可以通过在运行 SILE 之前运行 eval $(luarocks path) 来完成（或从您的 shell 的初始化脚本中）。

查找运行 SILE 所使用的 Lua 版本

第三方包必须安装与 SILE 所使用的相同版本的 Lua。在安装了多个 Lua 版本的系统上，并且 SILE 也没有使用默认版本的情况下，您可能需要手动指定版本。要获取用于执行 sile 的 Lua 版本

$ export LUA_VERSION=$(sile -e 'print(SILE.lua_version);os.exit()' 2> /dev/null)
$ luarocks install --lua-version $LUA_VERSION ...

了解更多信息

请阅读 完整的 SILE 手册 以获取有关 SILE 是什么以及它如何帮助您的更多信息。SILE 网站上有示例文档（源和 PDF）（在 SILE 网站）。还有一个 常见问题解答。

联系方式

请在 github 仓库 上报告错误并发送补丁和拉取请求。有关问题和讨论，请加入 邮件列表。

许可条款

SILE 在 MIT 许可证 下发布。