自动生成 PDF 格式的 TiDB 文档：在 Rocky 9 的实践

图片选自: https://asktug.com/t/topic/1020117

TL;DR

Asktug.com 论坛里偶有小伙伴询问如何自助生成 PDF 格式的 TiDB 文档，或是 PDF 太长，经常查阅的只是其中一部分，如何只生成那一部分的 TiDB 文档。本文将介绍如何在 Rocky Linux 9 上自助生成 PDF 格式的 TiDB 文档。

没听过十年二手玫瑰，是不会轻易做这种尝试的，对于 LaTaX 新手来说，积累本文素材的过程极为痛苦。不建议各位看官实操本文的第二种方法，还是推荐使用第一种方法，基本按照官方推荐的、经过测试的方法来，便捷、有效、易用。

环境准备

操作系统：Rocky Linux 9.3

[shawnyan@rocky9 ~]$ cat /etc/redhat-release Rocky Linux release 9.3 (Blue Onyx) [shawnyan@rocky9 ~]$ uname -rsm Linux 5.14.0-362.13.1.el9_3.x86_64 x86_64

前置安装：git, podman

[shawnyan@rocky9 ~]$ git --version git version 2.39.3 [shawnyan@rocky9 ~]$ [shawnyan@rocky9 ~]$ podman --version podman version4.6.1

注：OS 和相关软件不是本文重点，遂一笔带过。

拉取 pandoc/latex 镜像

使用 podman 拉取 pandoc 镜像：

podman pull pandoc/latex[shawnyan@rocky9 ~]# podman pull pandoc/latex... Getting imagesource signatures Copying blob 13d63ff5f1df done ... Copying config 11172c3435 done Writing manifest to image destination 11172c3435762783d582093f4eae6cf80548ff4443a26532e35f36dac8b2ec77

查看镜像信息：

[shawnyan@rocky9 ~]# podman images | grep pandocdocker.io/pandoc/latex latest 11172c3435769 months ago 550 MB

克隆 TiDB 文档库代码

这里以 TiDB 中文文档为例，克隆文档：

（为加速下载，也避免网路问题，这里选择从 gitee 克隆代码）

git clone https://gitee.com/shawnyan/docs-cn.git --depth=1[shawnyan@rocky9 ~]$ git clone https://gitee.com/shawnyan/docs-cn.git --depth=1 Cloning into docs-cn... remote: Enumerating objects:2472, done. remote: Counting objects: 100% (2472/2472), done. remote: Compressing objects: 100% (2392/2392), done. remote: Total 2472 (delta 122), reused 1622 (delta 80), pack-reused 0 Receiving objects: 100% (2472/2472), 160.93 MiB | 8.04MiB/s, done. Resolving deltas:100% (122/122), done. Updating files: 100% (2440/2440), done.

克隆完成后，查看版本，确认当前文档源码为最新版。

[shawnyan@rocky9 docs-cn]$ git lg * a19b956 - (grafted, HEAD -> master, origin/master, origin/HEAD)upgrade TiDB: check DDL and backup status before checking cluster health(#15936) (2 days ago) <Aolin>

方法一：使用 pandoc/latex 镜像生成 PDF 文档

在 TiDB 中文文档代码库的 README 中有这样一段介绍，并给出了相关教程。

如果你想在本地定制输出符合特定场景需求的 PDF 格式的 TiDB 文档，例如对 TiDB 文档目录进行自由排序和删减，请参考自助生成 TiDB 文档 PDF 教程。

只是教程中介绍的是 Windows 和 macOS 环境，下面将介绍在 Linux 环境下的相关操作流程，推荐有需求的同学使用这种方法。

TiDB 文档目录在 TOC.md 文件中，编辑此文件按需进行调整、删减。

例如，在本例中只保留【关于 TiDB】部分。

<!-- markdownlint-disable MD007 --> <!-- markdownlint-disable MD041 --> - [文档中心](https://docs.pingcap.com/zh) - 关于 TiDB - [TiDB 简介](/overview.md) - [TiDB 7.5 Release Notes](/releases/release-7.5.0.md) ...

将所有 Markdown 文档文件按照 TOC.md 整合到一个 doc.md 文件中。

cddocs-cn python scripts/merge_by_toc.py

运行 andelf/doc-build 容器，在本例中，文档源码目录为 /root/docs-cn 。

podman run -it -v /root/docs-cn:/opt/data:rw --privileged=true andelf/doc-build:0.1.9

在容器中运行生产 PDF 的脚本。

cd /opt/data bash scripts/generate_pdf.sh

预期输出：将在宿主机上的文档源码目录下生成一个 output.pdf 文件。

[root@rocky9 docs-cn]# ls output.pdf output.pdf

到此，演示结束，只是在 PDF 文档属性中还发现一处小问题，PDF 文件文档属性中的标题和作者在生成过程中未填充，需要在generate_pdf.sh 文件中补充两行内容。

-V title-meta="TiDB 中文手册" \ -V author-meta="PingCAP Inc." \

补充后，效果如图：

方法二：直接安装 pandoc,texlive 软件并生成 PDF 文档

这种方法过程极为复杂繁琐，好处是可以使用最新版本的 pandoc 和 texlive。

安装一些依赖包。

dnf install curl wget gitbzr mercurial openssl-client subversion procps dnfinstall autoconf automake bzip2 dpkg-dev file g++ gcc imagemagick dnf install tcl tcl-devel tk tk-devel python3 libbz2-dev libc6-dev

安装 pandoc。

dnf install pandoc[root@rocky9 ~]# pandoc --version pandoc 2.14.0.3 Compiled with pandoc-types 1.22.1, texmath 0.12.3.3, skylighting 0.10.5.2, citeproc 0.4.0.1, ipynb 0.1.0.1 User data directory: /root/.local/share/pandoc Copyright (C) 2006-2021 John MacFarlane. Web: https://pandoc.org This is free software; see the source forcopying conditions. There is no warranty, not evenfor merchantability or fitness for a particular purpose. [root@rocky9 ~]#

安装 texlive。

wget https://mirror.ctan.org/systems/texlive/tlnet/install-tl-unx.tar.gz tar zxf install-tl-unx.tar.gz cd install-tl-20240101/ perl ./install-tl

安装中文字体，官方使用的是 文泉驛（WenQuanYi），或是其他中文字体。

$ fc-list :lang-zh | grep -i wenq /usr/share/fonts/truetype/wqy/wqy-microhei.ttc: WenQuanYi Micro Hei,文泉驛微米黑,文泉驿微米黑:style=Regular /usr/share/fonts/truetype/wqy/wqy-microhei.ttc: WenQuanYi Micro Hei Mono,文泉驛等寬微米黑,文泉驿等宽微米黑:style=Regular

生成 PDF 文档。

由于 pandoc 版本升级更新，原有的参数发生变化，比如--latex-engine 不再支持，需要替换为 --pdf-engine。

MAINFONT="Microsoft YaHei" MONOFONT="Microsoft YaHei" pandoc --pdf-engine=xelatex doc.md -o output2.pdf --toc -s \ -V title="TiDB 文档（节选）" \ -V author="ShawnYan" \ -V title-meta="TiDB 文档（节选）" \ -V author-meta="ShawnYan" \ -V CJKmainfont="${MAINFONT}" \ -V mainfont="${MAINFONT}" \ -V sansfont="${MAINFONT}" \ -V monofont="${MONOFONT}"

对于模板文件，直接用新版 pandoc 调用会报错，需要做些调整，如下图。

小结

方法一足够简单、实用，推荐有需求的同学使用，方法二只是其他途径探索，不做推荐。