在 pandoc 中将 .rst 文件转换为 groff 格式时缺少".TH"部分(reStructuredText，manpage)

Question

我应该在源reStructuredText文件中放入什么来填充标题标题"(.TH)行在目标文件时使用pandoc转换为groff格式?

我有一个python项目，它的文档是用sphinx构建的。因此，大多数项目的文档已经在重构文本(.rst文件)中编写。我需要写一个手册，所以我想用reST格式写。

不幸的是，当我使用pandoc将源.rst文件转换为man(groff-format)时，该文件不能正确渲染man，因为它缺少标题标题。

例如，考虑以下源文件source.rst

==========
my-program
==========
----------------------
my-program description
----------------------
:manual section: 1
:manual group: John Doe
Synopsis
========
**my-program**
Description
===========
**my-program** is magical. It does what you need!

我使用pandoc将其转换为groff格式，如下所示:

user@disp117:~$ pandoc source.rst -t man > my-program.1
user@disp117:~$ 
user@disp117:~$ cat my-program.1 
.SH my-program
.SS my-program description
.TP
manual section
1
.TP
manual group
John Doe
.SS Synopsis
.PP
f[B]my-programf[R]
.SS Description
.PP
f[B]my-programf[R] is magical.
It does what you need!
user@disp117:~$ 

现在，如果我尝试渲染groff文件，那么它就无法正确格式化。

user@disp117:~$ groffer --text my-program.1 
manual  section  1 manual group John Doe my‐program my‐program is
magical.  It does what you need!
...

但是，如果我手动将a.TH行添加到文件中，那么它将按预期工作。

user@disp117:~$ echo -e ".TH my_program(1)n$(cat my-program.1)" > my-program.1
user@disp117:~$ 
user@disp117:~$ groffer --text my-program.1 
my_program(1)()                                                my_program(1)()

my-program
my-program description
manual section
1
manual group
John Doe
Synopsis

[B]my-program
[R]
Description

[B]my-program
[R] is magical.  It does what you need!

my_program(1)()
user@disp117:~$ 

我需要向source.rst添加什么，以便pandoc将生成包含.TH行的groff格式文件?

Answer 1

Pandoc生成' snippets ';默认情况下;这些片段旨在集成到一个完整的文档中。使用

命令pandoc生成完整的文档

pandoc --standalone ...

或

pandoc -s ...