浅尝在 Rocky 9 下自助生成 PDF 格式的 TiDB 文档

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

TL;DR

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

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

环境准备

1. 操作系统：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

2. 前置安装：git, podman

[shawnyan@rocky9 ~]$ git --version
git version 2.39.3
[shawnyan@rocky9 ~]$ 
[shawnyan@rocky9 ~]$ podman --version
podman version 4.6.1

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

3. 拉取 pandoc/latex 镜像

使用 podman 拉取 pandoc 镜像：

podman pull pandoc/latex

[shawnyan@rocky9 ~]# podman pull pandoc/latex
✔ docker.io/pandoc/latex:latest
Trying to pull docker.io/pandoc/latex:latest...
Getting image source signatures
Copying blob 13d63ff5f1df done  
...
Copying config 11172c3435 done  
Writing manifest to image destination
11172c3435762783d582093f4eae6cf80548ff4443a26532e35f36dac8b2ec77

查看镜像信息：

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

4. 克隆 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.04 MiB/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 文件中，编辑此文件按需进行调整、删减。

例如，在本例中，为便于演示，只保留部分内容。

<!-- 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 文件中。

cd docs-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

//img

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

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

//img

补充后，效果如图：

//img

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

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

1. 安装一些依赖包。

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

2. 安装 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 for copying conditions. There is no
warranty, not even for merchantability or fitness for a particular purpose.
[root@rocky9 ~]# 

3. 安装 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

4. 安装中文字体，官方使用的是 文泉驛（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

5. 生成 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 调用会报错，需要做些调整，如下图。

小结

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