如何通过pandoc将reST转man页时填充.TH的所有参数

Pandoc不会从rst的一级标题里提取.TH的额外参数，而是通过读取文档开头的reST元数据字段来填充.TH的五个位置参数。你需要在.rst文件的最开头添加元数据块，对应每个参数的字段如下：

• title：默认从一级标题提取，也可以用:title:字段显式指定（建议和一级标题保持一致）
• section：用:section:字段指定手册章节号（比如1对应用户命令，5对应配置文件）
• date：用:date:字段指定发布日期，推荐格式YYYY-MM-DD
• source：用:source:字段指定项目/来源名称
• manual：用:manual:字段指定手册集的名称

完整示例 #

下面是一个包含所有元数据的.rst文件示例：

:title: mycommand
:section: 1
:date: 2024-05-20
:source: MyTools Project
:manual: MyTools User Manuals

=======
mycommand
=======

这是`mycommand`的man页内容，用于演示如何设置.TH参数...

转换验证 #

用以下命令转换：

pandoc -s source.rst -t man -o mycommand.1

生成的groff文件中，.TH行会被正确填充为：

.TH MYCOMMAND 1 "2024-05-20" "MyTools Project" "MyTools User Manuals"

你可以通过man ./mycommand.1查看最终效果，或者直接打开生成的.1文件确认内容。

参考文档获取 #

• 查看Pandoc关于man格式输出的细节：执行pandoc --help -t man
• 确认.TH参数规范：执行man 7 man-pages
• Pandoc官方文档中关于reStructuredText元数据解析的章节（可通过本地安装的Pandoc文档或官方离线文档查看）

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