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

原创
01/08 00:00
阅读数 23

原文来源:https://tidb.net/blog/ec425ac8

no-alt

图片选自: 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
  1. 前置安装:git, podman
[shawnyan@rocky9 ~]$ git --version
git version 2.39.3
[shawnyan@rocky9 ~]$ 
[shawnyan@rocky9 ~]$ podman --version
podman version 4.6.1

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

  1. 拉取 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
  1. 克隆 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 文件中,编辑此文件按需进行调整、删减。

例如,在本例中只保留【关于 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 文件中。

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

no-alt

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

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

no-alt

补充后,效果如图:

no-alt

方法二:直接安装 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
  1. 安装 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 ~]# 
  1. 安装 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
  1. 安装中文字体,官方使用的是 文泉驛(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
  1. 生成 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 调用会报错,需要做些调整,如下图。

no-alt

小结

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

展开阅读全文
加载中
点击引领话题📣 发布并加入讨论🔥
打赏
0 评论
0 收藏
0
分享
返回顶部
顶部