使用pandoc将rst转groff格式时，如何生成.TH标题行？

要解决这个问题，你需要在rst源文件中添加Pandoc可识别的元数据，用来填充.TH行所需的手册名、章节号、发布日期等核心信息。具体有两种常用方式：

方式1：添加YAML元数据块（推荐） #

在rst文件的最开头，插入一段用---包裹的YAML元数据，Pandoc会自动提取这些信息生成标准的.TH行：

---
title: "my-tool"
section: 1
date: 2024-05-20
source: "My Python Project"
manual: "My Project Manuals"
---

• title：对应.TH里的手册名称（比如目标命令名）
• section：man手册的章节号（1代表用户命令，5代表配置文件，8代表系统命令等）
• date：文档的发布日期
• source：可选，对应.TH里的来源字段
• manual：可选，对应.TH里的手册组名称

添加后执行Pandoc转换命令：

pandoc -s input.rst -t man -o output.1

生成的groff文件会自动包含符合规范的.TH行，无需手动修改。

方式2：使用reStructuredText原生元数据指令 #

如果不想用YAML，也可以在rst文件开头用rst原生的.. meta::指令定义核心元数据：

.. meta::
   :title: my-tool
   :section: 1
   :date: 2024-05-20

不过这种方式支持的字段有限，部分Pandoc的man格式扩展字段（比如source）可能无法识别，优先推荐YAML方式。

结合Sphinx的额外优化提示 #

如果你的项目基于Sphinx构建，还可以直接通过Sphinx配置生成标准man手册，无需依赖Pandoc转换：
在项目的conf.py中添加man_pages配置：

man_pages = [
    ('index', 'my-tool', 'My Tool Manual',
     ['Your Name'], 1)
]

执行以下命令即可直接生成带正确.TH行的man文件：

sphinx-build -b man docs/source docs/build/man

这种方式更适配Sphinx项目的原生工作流。

内容的提问来源于stack exchange，提问作者Michael Altfield