#book #metadata #pdf #workflow #publishing #command-line-interface #resources

bin+lib casile

CaSILE 工具箱的命令行接口,这是一个采用 SILE 和其他技巧进行书籍出版工作流程的工具

2 个不稳定版本

0.13.1 2024 年 3 月 25 日
0.11.2 2023 年 9 月 22 日

664文本处理

Download history 37/week @ 2024-04-02

每月 64 次下载

AGPL-3.0

1MB
7.5K SLoC

Lua 5K SLoC // 0.1% comments Rust 1.5K SLoC // 0.0% comments M4 557 SLoC // 0.3% comments Automake 159 SLoC Python 30 SLoC // 0.2% comments Shell 26 SLoC // 0.3% comments Bazel 24 SLoC JavaScript 20 SLoC Vim Script 14 SLoC Zsh 6 SLoC Bitbake 5 SLoC INI 4 SLoC

包含 (晦涩的 autoconf 代码,5KB) configure.ac

CaSILE 工具箱

Rust Test Status Docker Build Status Rust Lint Status Lua Lint Status Reviewdog Lint Status
Chat on Gitter Conventional Commits Commitizen Friendly

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 HubGitHub容器注册表获取预制的容器。使用docker pull docker.io/siletypesetter/casile:latestdocker 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-yamlpython-ruamelpython-isblibpython-pandocfilters
  • 最新版本的 shell 工具,如 jqyqentrbcsqlite
  • git-warp-time 的 CLI 工具版本(库版本也用于 Cargo 的构建时间)的 CLI 工具版本。git-warp-time
  • GNU Make(以及各种其他 GNU 工具)将所有东西粘合在一起。
  • 默认的书籍模板假定系统已安装的 HackLibertinusTeX 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)也非常有用。

从源代码构建

  1. 克隆 Git 仓库或下载并解压源代码存档或源代码发行版包。

  2. 切换到目录,为您的系统配置,并构建工具

    # 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.mkMakefilemakefileGNUMakeFile也被认为是。

    您的项目规则文件是连接到系统的最技术方式,而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
    

    请注意,这仅影响从defaultall目标默认构建的格式,您仍然可以手动以任何格式构建单个资源,而无需在此处列出。

  • 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)
    
  • LODPIHIDPI 相似,但用于常规发行资源。

    默认为300,并且启用草稿模式下的缩放。

钩子

这些函数可以在项目的 Makefile 中定义,以在过程中的不同点添加额外的功能。您可以根据需要使用单行或多行语法,但请注意,无论哪种方式,输入、输出和传递的变量都将相同。另一方面,每个钩子都有自己的用法,请注意其运行的环境。

依赖关系

~22–35MB
~612K SLoC