2 个不稳定版本
0.13.1 | 2024 年 3 月 25 日 |
---|---|
0.11.2 | 2023 年 9 月 22 日 |
664 在 文本处理
每月 64 次下载
1MB
7.5K SLoC
包含 (晦涩的 autoconf 代码,5KB) configure.ac
CaSILE 工具箱
CaSILE 工具箱是一个构建系统,它将大量工具粘合在一起,形成一个从开始到结束自动化的书籍出版系统。其概念是使用非常简单、易于编辑的内容和配置文件作为输入,尽可能少地人工干预,将它们转换为最终产品的所有工件。纯文本文档格式和一小部分元数据自动转换为印刷就绪的 PDF、电子书和渲染的促销材料。
在传统的出版工作流程中,书籍越接近生产,就越难与之合作。管道“变窄”到更多和更多先进的(复杂/昂贵)软件,以及更多的访问限制。CaSILE 完全规避了这种限制,完全自动化了所有“后期”生产阶段。通过从端到端自动化生产工作流程,所有正常的顺序限制都被移除。书籍的外观设计可以在流程的任何阶段进行。书籍的内部设计可以在流程的任何阶段进行。复制编辑可以由不同的编辑在不同部分的书籍上同时进行。因为随着项目的进展,管道不会变窄,内容始终是最重要的,所以工作流程的限制只是由 你 为项目规定的,而不是由使用的工具规定。
CaSILE(发音为 /ˈkɑːs(ə)l/,就像“城堡”)最初是一个名为 avadanlik
的子模块,包含在我的书籍项目仓库中(avadanlık 是土耳其语中类似“工具箱”的词)。由于大部分组件都围绕 SILE 展开,至少在我的头脑中,CaSILE 成为了 Caleb’in Avadanlığı birlikte SILE,大致翻译为“带有 Caleb 工具箱的 SILE”。最初所有内容都硬编码为土耳其语,但最终我添加了英语本地化,并将大多数工具通用化,以便可用于几乎任何语言的书籍。
状态
我以此方式出版了数十本书和其他项目,并且还有更多正在进行中。目前至少有3家出版社在使用它。换句话说,它对我是有效的™,但你的效果可能不同。这个工具最初只是嵌入到一个书项目中的一些脚本。然后我写了一本新书,并将脚本复制过去开始使用。当我完成第三本书时,我突然意识到我应该使我的工具更加模块化,并将它们包含在每个项目中。大约在这个时候,我知道如果它对多种类型的书都很有用,我就想开源它。那一天来了又去了。有一天我决定把它放出去,这样更容易解释我在做什么。因此,在许多方面,它被硬编码到我的出版需求中,要使其更加灵活,只有在人们请求或贡献更改时才会发生。
使用CaSILE的方法有几种,安装或不安装都可以。最初(通过v0.2.x),CaSILE专注于作为Git项目的子模块使用。从v0.3.0版本开始,主要关注的是作为完全独立于任何项目的CLI工具使用。
设置
如果你愿意设置大量的依赖项,CaSILE可以安装和作为标准CLI程序本地运行。
- 优点:最佳(最快)的系统硬件利用,可以像自己的应用程序一样修改依赖项,shell小工具,如自动完成。
- 缺点:系统包通常只支持一个版本,手动安装支持并行版本,但必须使用适当的后缀实例化(例如,如果使用
./configure --program-suffix=-vN
安装,然后casile make <target>
变为casile-vN make <target>
)。
作为安装所有依赖项的更简单替代方案,所有内容都可以打包在一起,作为一个单一的Docker容器运行。
- 优点:无需设置依赖项,因此非常容易开始,易于切换版本,包括完整的匹配依赖栈。
- 缺点:设置访问项目源外部的字体或其他资源比较麻烦,启动时间较长,CPU和内存资源有所减少。
除了本地运行外,CaSILE还可以在几乎任何远程CI平台上运行。如果你的书项目在GitHub上,你可以将CaSILE添加到任何工作流程中,作为GitHub 操作。如果你的书项目托管在GitLab上,你可以轻松配置它以在GitLab CI中运行。
- 优点:无需下载或本地安装,易于共享每次构建的结果。
- 缺点:周转时间较长,必须将仓库推送到受支持的远程主机。
当然,也可以混合使用。
本地原生设置
如果您正在使用Arch Linux,AUR上的casile包(casile)就是您需要的所有东西。还有一个casile-git配方可用,并且可以从这个仓库直接安装包(包括所有依赖),以便轻松设置。对于任何其他平台,您可能需要冒险尝试,查看从源代码构建(或只是使用Docker)。如果您花些时间从Homebrew和其他地方拉取依赖项,CasILE可以在macOS上运行。Windows支持几乎肯定会需要相当多的麻烦;不是我的马戏团,也不是我的猴子。
本地Docker设置
使用Docker容器可以使得启动和运行变得更加容易,因为您不需要安装大量的依赖。可以从Docker Hub或GitHub容器注册表获取预制的容器。使用docker pull docker.io/siletypesetter/casile:latest
或docker pull ghcr.io/sile-typesetter/casile:latest
下载(或更新)镜像。请注意,latest将是最近的稳定标记版本,或者您也可以替换为特定的标记(例如vX.Y.Z),master用于更近期的Git提交构建,或者v0
用于该主要系列中最近的标记版本。
您可以可选地自己构建一个Docker镜像。从任何CasILE源目录(Git克隆的提取源包),使用./configure --disable-dependency-checks
进行配置,然后使用make docker
构建。生成的镜像将作为sile-typesetter/casile:HEAD
在您的系统上可用。
要从Docker中调用CasILE,您需要将项目文件放在一个卷上,该卷也将作为可以写入输出文件的地方。完整的Docker运行命令可以替换您调用CaSILE的任何地方。为了方便起见,您可能想要给自己一个别名
alias casile='docker run -it --volume "$(pwd):/data" ghcr.io/sile-typesetter/casile:latest
将此保存到您的shell的rc文件中(例如~/.bashrc
),以持久保存别名。这种替换应该可以在任何地方以及使用您会为casile
运行的任何参数的情况下工作。
GitHub Action设置
作为Action的使用遵循传统的GitHub Action配置模式。您可以指定您想要的精确版本,v0
用于同一主要版本序列中最新的标记版本,latest
用于任何序列的最新标记版本,或master
用于最新的开发构建。
- name: CaSILE
uses: sile-typesetter/casile@latest
如果没有传递参数,Action 将默认运行 casile make -- default
。您可以使用 args
输入参数传递自己的参数。DISTDIR
的值将自动输出,并可用于从您的构建中发布工件。一个完整的流程示例,包括自定义目标和工件发布,可能看起来像这样:.github/workflows/casile.yml
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 }}
另一个有用的范例是在容器内运行您的步骤
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
uses: actions/checkout@v2
- name: make
run: |
casile make -- pdfs epub renderings
- name: Upload artifacts
uses: actions/upload-artifact@v2
with:
name: pub
path: pub
如果您是从零开始,请考虑使用 casile-template 仓库来初始化您的项目。有关更多想法和复杂示例,请查看 casile-demos 仓库。
GitLab CI 设置
设置您的作业以使用您选择的 CaSILE 镜像和版本,但禁用默认的入口点
image:
name: "siletypesetter/casile:latest"
entrypoint: [""]
script:
- casile make
不幸的是,GitLab CI 无法动态命名工件(请参阅 上游报告),因此您需要自己定义 DISTDIR
变量。一个完整的管道示例 .gitlab-ci.yaml
,包括自定义目标和工件发布,可能看起来像这样
default:
image:
name: "siletypesetter/casile:latest"
entrypoint: [""]
variables:
DISTDIR: $CI_PROJECT_NAME-$CI_JOB_NAME_SLUG-$CI_COMMIT_SHORT_SHA
casile:
script:
- casile make -- pdfs epub renderings
artifacts:
name: $DISTDIR
paths: [ ./$DISTDIR/* ]
依赖关系
请注意,如果您使用了 设置 中列出的任何发行版软件包、Docker 容器或 CI 配置,您无需担心这些依赖关系。
CaSILE 将许多不同的开源工具粘合在一起,以构建完整的出版工具链。在幕后,这是一项非常混乱的工作。为了使一切正常工作,我不得不使用各种各样的软件。所有这些都是开源的,可在各个平台上使用,但我只在 Linux 上进行了个人测试。
以下所有内容都以某种方式得到了利用。目前,工具集假定以下所有内容都存在,但并非所有这些内容都用于构建所有资源,因此可能可以使其更加选择性强。例如,如果没有光线追踪引擎,那就意味着没有复杂的 3D 封面预览,但您仍然可以构建 PDF 和其他数字格式。如果没有 Node,那就意味着没有圣经章节格式规范化,但您仍然可以构建书籍。如果没有 ImageMagick,那就意味着没有封面图像,但您仍然可以处理书籍的内页。另一方面,如果没有 GNU Make、Pandoc 或 SILE,当然将是致命的。
- SILE 排版器是大多数文本布局背后的主要工作马。CaSILE 的标记版本应该与 SILE 的最新发布版本兼容,Git 版本可能假定 SILE 的最新 Git HEAD 版本。
- Pandoc(特别是与 我带有 SILE 支持的分支)用于在文档类型之间进行转换。
- ImageMagick 处理位图图像处理(需要 v7+)。
- POVRay 用于渲染三维可视化。
- Inkscape 用于布局一些封面资源和将 SVG 资源转换为其他格式。
- PDFTk 用于操作 PDF。
- Podofo 用于对 PDF 进行更多操作。
- 需要 Kindlegen 来生成亚马逊的电子书格式。Kindlegen。
- Poppler 用于对 PDF 进行更多操作。Poppler。
- Zint 生成 ISBN 条形码、QR 码等。Zint。
- Perl、Python、Lua、Node、Zsh 以及其他几种语言解释器!
- 这些语言的模块,如
lua-yaml
、python-ruamel
、python-isblib
和python-pandocfilters
。 - 最新版本的 shell 工具,如
jq
、yq
、entr
、bc
和sqlite
。 - git-warp-time 的 CLI 工具版本(库版本也用于 Cargo 的构建时间)的 CLI 工具版本。git-warp-time。
- GNU Make(以及各种其他 GNU 工具)将所有东西粘合在一起。
- 默认的书籍模板假定系统已安装的 Hack、Libertinus 和 TeX Gyre 字体集。
- 一些其他东西(如果系统没有所需的东西,
./configure
将会警告您)。
除了运行时依赖项之外,编译 CLI 界面(可选)还需要 Rust 构建工具链。构建后,CLI 运行时不需要任何依赖。
在其他发行版有软件包之前,最确定的依赖项列表可能是 Arch Linux 的 软件包元数据。您需要将软件包名称翻译成您的平台,但所有内容都列在那里。
辅助工具
您可能还需要其他一些 CaSILE 不提供的东西。CaSILE 负责将源代码转换为最终输出,但您需要自己编辑源代码和查看输出。首先,一个用于处理 Markdown & YAML 源代码的文本编辑器是必不可少的。这里有很多选择,但大多数都不在范围之内,但可以考虑 Marktext、Zettlr、Atom、VSCode、Sublime、Vim 等。CaSILE 还假设您的书籍项目由 Git 跟踪,因此需要客户端,如 CLI 工具或类似于 GitAhead、Fork、Sourcetree、GitKraken、Tower 的 GUI,或者您选择编辑器的特定插件,这是必不可少的。当然,您还需要一种查看生成的 PDF 的方式。我推荐一种在文件更改时自动更新的工具;我使用的是 zathura),但 Okular 和许多其他工具也支持这一功能。图像查看器和电子书阅读器(如 Calibre)也非常有用。
从源代码构建
-
克隆 Git 仓库或下载并解压源代码存档或源代码发行版包。
-
切换到目录,为您的系统配置,并构建工具
# Only for git clones or source archives... $ ./bootstrap.sh # Configure & build $ ./configure $ make
$ make install
注意,如果您不打算安装到系统中,但想从源代码目录编译和运行(例如,为 CaSILE 本身的开发工作),请使用
./configure --datarootdir=$(cd ..;pwd); make -B
,然后将 CasILE 源代码目录添加到您的$PATH
。
输入
CaSILE对项目仓库的内容做出了一些假设,但您如何组织您的git仓库仍然具有灵活性。例如,我有一些独立的书籍在其自己的仓库中,有些系列书籍的仓库包含整个系列,还有些不同出版商/版权状态的书籍放在一起(并在分支中工作),一组不同作者但共同出版的作品在另一个仓库中,等等。CaSILE假设每个仓库中的源之间存在某种关系,因此细粒度仓库提供了更完整的控制,但单个仓库中的每个资源也可以进行定制。您需要考虑自己的工作流程以及项目如何共享资源。请注意,常见的资源,例如出版商的默认值,可以共享在其他子模块中。
一个书籍项目至少应包括以下内容
- casile.mk
- my_book.md
- my_book.yml
当然,可能还有更多相关资产,例如封面背景图片
- my_book-background.png
可选地,书籍可以被分成章节
- my_book.md
- my_book-chapters/000-preface.md
- my_book-chapters/001-chapterone.md
- my_book-chapters/002-chaptertwo.md
输出
作为回报,CaSILE将输出
- 针对指定印刷格式的印刷就绪PDF(高分辨率,全出血带裁剪标记)...
- my_book-a5-paperback.pdf
- my_book-a5-paperback-cover.pdf
- 用户友好的PDF(普通分辨率,索引,超链接)...
- my_book-a4-print.pdf
- 基于封面的促销图像...
- my_book-a5-front_cover.jpg
- my_book-square-cover.jpg
- 完成书籍的3D渲染...
- my_book-a5-paperback-3d-front.jpg
- my_book-a5-paperback-3d-back.jpg
- my_book-a5-paperback-3d-stacks.jpg
- E-Book格式...
- my_book.epub
- my_book.mobi
使用方法
构建所需的资源。假设您有一个书籍源文件my_book.md
和位于my_book.yml
的配套元数据,生成资源的通用语法是
$ casile make -- my_book-<layout>-<options>.<format>
例如,构建八开大小的印刷就绪PDF
$ casile make -- my_book-octavo-hardback-cover.pdf
或者构建半信函大小的封面3D渲染
$ casile make -- my_book-halfletter-paperback-3d-front.jpg
请参阅CaSILE演示仓库以获取示例书籍项目布局。
设置
CaSILE有很多可调整的旋钮,几乎可以更改任何事情。主要技巧是了解在哪里进行更改,因为顺序很重要。
从最不具体到最具体的广泛概述
-
编译时发现。
当CaSILE配置时,它会运行一系列发现操作(在
./configure
期间)。这些操作检测依赖项的安装位置和版本。如果您希望替换某些程序,也可以手动定义。此阶段通常设置CasILE将从中运行的位置。配置阶段审查系统以确定软件包将安装的位置,以便它知道如何找到自己。
-
内置于运行时默认值。
所有设置都内置了某些默认值,如果以后没有重写它们,则将使用这些默认值。
-
项目规则文件。
每个项目可能有一个或多个规则文件,这些文件将被完整地注入到GNU Make运行时。建议的文件名是
casile.mk
,但rules.mk
、Makefile
、makefile
和GNUMakeFile
也被认为是。您的项目规则文件是连接到系统的最技术方式,而Make的语法通常很复杂。许多项目根本不需要它——或者只用于简单的变量分配——但几乎可以做到任何事情。
-
出版商规则文件。
待实现
-
出版商元数据。
待实现
-
项目元数据。
每个项目应有一个主元数据文件,格式为YAML。文件名应与项目名称匹配,通常与git仓库目录名称相同。
-
书籍元数据。
项目中的每本书都应有一个包含特定信息的元数据文件。
对于只有一本书的项目,这可能与项目元数据文件相同。
-
项目CaSILE设置文件。
每个项目可能有一个YAML文件,定义了覆盖默认值并避免在每次调用时手动传递的设置。
-
运行时环境变量。
许多设置可以通过环境变量设置,并且将被考虑用于CLI的每次调用。
-
运行时标志。
某些设置具有CLI标志,可以覆盖其他任何设置。
项目参数
大多数设置适用于整个项目(仓库)。要覆盖默认值,请在您的项目casile.mk
-
LANGUAGE
设置本地化文件名的语言。默认为英语,因此您可能需要运行
casile make -- book-halfletter-3d-front.png
。将其更改为土耳其语LANGUAGE = tr
将意味着您运行的命令应该是
casile make -- kitap-a5-3b-on.png
以生成相同的项目资源,但使用本地化文件名。目前仅包括土耳其语本地化,但它们很容易添加到您的项目中。将这些提交到上游也将非常受欢迎。 -
TARGETS
是项目中的所有书籍列表。默认情况下,这是通过扫描项目目录并找到所有具有相同名称的YAML元数据文件的Markdown文件来设置的。这有助于避免像
README.md
这样的文件,这些文件不是项目的重点。您可以使用列表手动设置TARGETS = book_1 book_2
或者可能用所有Markdown文件的列表填充。您不需要这里的扩展名,只需要要构建的书籍的基础名称
TARGETS = $(basename $(wildcard *.md))
-
PROJECT
是整体项目的名称(可能包含几本书或其他作品)。默认情况下,这是仓库目录的名称。
PROJECT = series_name
-
CASILEDIR
是CaSILE的位置。从该路径加载共享资源文件。通常,基于CaSILE安装自动设置的值将足够。这对于在CaSILE本身上进行开发工作非常有用。 -
PROJECTDIR
是您的项目位置。在此处检查源文件,并在此处运行构建过程。默认为当前Git仓库的根目录。您不太可能想更改此值。
-
DISTDIR
确定发布文件将放置的位置。输出文件首先在源文件旁边的当前项目目录中创建。可选地,CaSILE可以将完成的资源“安装”到其他位置。
DISTDIR = /path/to/pub/$(PROJECT)
-
FORMATS
包含从每个输入构建的输出格式列表。默认情况下,这设置为
pdf epub
,但您可能想要构建比这更少或更多的内容。要构建“作品集”FORMATS = pdf epub mobi odt docx app
请注意,这仅影响从
default
或all
目标默认构建的格式,您仍然可以手动以任何格式构建单个资源,而无需在此处列出。 -
BLEED
设置毫米单位下的印刷资源出血边距。默认值为3。
BLEED = 5
-
TRIM
设置毫米单位下的印刷资源裁剪边距。默认值为10。
TRIM = 15
-
PAPERWEIGHT
设置用于计算书籍厚度和因此书脊宽度的纸张克重。默认值为60。
PAPERWEIGHT = 80
-
COVERGRAVITY
告诉封面生成器在调整不同宽高比时裁剪背景图像的方向。默认值为居中。可能的选项是ImageMagick能理解的任何选项,例如南、西南、东北等。
COVERGRAVITY = North
构建时间设置
这些设置通常在运行时不会更改。您可以在规则文件中设置它们,例如 casile.mk
,但它们通常作为环境变量或在命令行中设置,以获得特定构建的非默认行为。
-
DRAFT
启用草稿模式构建以进行更快测试。默认为false,但在执行make时可以将其设置为true。
$ casile make -- DRAFT=true book-a4-binding.pdf
这具体做什么将取决于资源类型。书籍仅进行一次排版,因此目录可能已过时,封面图像以17级最终分辨率生成,3D渲染使用部分照明以加快光线追踪等。
请注意,
casile make -- watch ...
会自动启用此模式。 -
HIGHLIGHT_DIFF
启用git分支之间的差异高亮。默认为false。
请注意,这需要与
PARENT
变量一起使用。在预处理书籍源时,当前提交将与由PARENT定义的分支(或提交)进行比较。任何差异(在字符级别)将使用CriticMarkup语法进行标记。一些输出格式(特别是PDF)将突出显示任何添加/删除。 -
STATSMONTHS
设置报告活动的默认时间范围。默认值为1。
在每个月底,我运行
casile make -- stats
来生成所有关于书籍内容的提交活动的报告。这计算当前的字符和单词计数,并与每个以前的提交进行比较,并显示一个报告,以表彰该提交的作者。我使用它来支付我们的翻译人员、编辑人员等。使用
casile make -- STATSMONTHS=2 stats
覆盖。 -
DEBUG
启用各种程序在构建期间显示额外输出的功能。默认为false,设置为true以启用。
这将在控制台上非常详细。Shell脚本将以
set -x
运行,具有它们的程序将以调试标志开启运行,等等。 -
DEBUGTAGS
设置要调试的SILE排版器的特定部分。有关详细信息,请参阅SILE文档。默认为casile。
DEBUGTAGS = casile insertions frames
从命令行使用可能是
casile make -- DEBUG=true DEBUGTAGS=frames book-a4.pdf
。 -
COVERS
可以用来禁用封面图像的生成。光栅图像生成可能需要时间,这会跳过这些步骤,并假设没有图形封面。默认为true,设置为false以禁用。
-
HEAD
设置要处理的输入书籍的行数。默认未设置。
如果将其设置为整数,则只处理输入书籍的这么多行。这在设置书籍样式时很有用。您可以处理第一章节的行数,并快速重建书籍,然后关闭以重新生成整本书。
$ casile make -- HEAD=50 book-octavo.pdf
-
SCALE
设置在草稿模式下资源下采样的因子。默认为17。这会将1200 dpi打印资源降至70 dpi。
-
HIDPI
设置印刷资源的输出分辨率。默认为1200,并且启用草稿模式下的缩放。
此值可以设置为另一个值,无论是否启用缩放。例如,对于一次性的命令,您可能运行
$ casile make -- HIDPI=600 book-octavo-binding.pdf
但为了更改项目默认值,您可以在您的规则文件中设置此值
HIDPI = $(call scale,600)
-
LODPI
与HIDPI
相似,但用于常规发行资源。默认为300,并且启用草稿模式下的缩放。
钩子
这些函数可以在项目的 Makefile
中定义,以在过程中的不同点添加额外的功能。您可以根据需要使用单行或多行语法,但请注意,无论哪种方式,输入、输出和传递的变量都将相同。另一方面,每个钩子都有自己的用法,请注意其运行的环境。
依赖关系
~22–35MB
~612K SLoC