https://pandoc.org/MANUAL.html模板/gh>
如何让pandoc正确设置"标题行"中的所有参数?(.TH)当从。rst文件转换为man文件?
根据文档man man-pages，标题行"接受位置参数:
Title line
The first command in a man page should be a TH command:
.TH title section date source manual
The arguments of the command are as follows:
title The title of the man page, written in all caps (e.g., MAN-PAGES).
section
The section number in which the man page should be placed (e.g., 7).
date The date of the last nontrivial change that was made to the man page. (Within the man-pages project, the necessary up‐
dates to these timestamps are handled automatically by scripts, so there is no need to manually update them as part of a
patch.) Dates should be written in the form YYYY-MM-DD.
source The source of the command, function, or system call.
For those few man-pages pages in Sections 1 and 8, probably you just want to write GNU.
For system calls, just write Linux. (An earlier practice was to write the version number of the kernel from which the
manual page was being written/checked. However, this was never done consistently, and so was probably worse than in‐
cluding no version number. Henceforth, avoid including a version number.)
For library calls that are part of glibc or one of the other common GNU libraries, just use GNU C Library, GNU, or an
empty string.
For Section 4 pages, use Linux.
In cases of doubt, just write Linux, or GNU.
manual The title of the manual (e.g., for Section 2 and 3 pages in the man-pages package, use Linux Programmer's Manual).
我没有找到任何关于pandoc如何神奇地将.rst文件转换为groff文件的文档，但我发现我可以让它在文档中吐出带有reStructuredText标题的.TH行，如下所示:
user@buskill:~/tmp/groff$ cat source.rst
==========
my-program
==========
Synopsis
========
**my-program**
Description
===========
**my-program** is magical. It does what you need!
user@buskill:~/tmp/groff$
user@buskill:~/tmp/groff$ pandoc -s source.rst -t man
." Automatically generated by Pandoc 2.9.2.1
."
.TH "my-program" "" "" "" ""
.hy
.SH Synopsis
.PP
f[B]my-programf[R]
.SH Description
.PP
f[B]my-programf[R] is magical.
It does what you need!
user@buskill:~/tmp/groff$
上面的执行显示pandoc从reST标题(my-program)中提取了.TH的第一个参数，但是其余的参数都是空的。如果我尝试在标题中直接指定它们，则不起作用。
user@buskill:~/tmp/groff$ head source.rst
==============================
my-program "one" "two" "three"
==============================
Synopsis
========
**my-program**
Description
user@buskill:~/tmp/groff$ pandoc -s source.rst -t man
." Automatically generated by Pandoc 2.9.2.1
."
.TH "my-program [dq]one[dq] [dq]two[dq] [dq]three[dq]" "" "" "" ""
.hy
.SH Synopsis
.PP
f[B]my-programf[R]
.SH Description
.PP
f[B]my-programf[R] is magical.
It does what you need!
user@buskill:~/tmp/groff$
我需要向source.rst文件添加什么，以便pandoc将填充目标文件的.TH行中的参数?一般来说，我在哪里可以找到描述这一点的参考文档?
您可以通过在标题中包含section，在source.rst中定义date，并设置footer&header作为变量
解决方案按如下方式更新source.rst文件
========
one(two)
========
:date: three
Synopsis
========
**my-program**
Description
===========
**my-program** is magical. It does what you need!
现在用以下命令
重新呈现手册页user@buskill:~/tmp/groff$ pandoc -s source.rst --variable header=five --variable footer=four -t man
." Automatically generated by Pandoc 2.9.2.1
."
.TH "one" "two" "three" "four" "five"
.hy
.SH Synopsis
.PP
f[B]my-programf[R]
.SH Description
.PP
f[B]my-programf[R] is magical.
It does what you need!
user@buskill:~/tmp/groff$
为什么可以工作
我在pandoc中找不到.rst和man之间转换的优秀参考文档，所以我用试错法解决了这个问题。
首先，我在pandoc文档中发现，您可以使用-D参数看到目标格式的默认模板
user@buskill:~$ pandoc -D man
$if(has-tables)$
."t
$endif$
$if(pandoc-version)$
." Automatically generated by Pandoc $pandoc-version$
."
$endif$
$if(adjusting)$
.ad $adjusting$
$endif$
.TH "$title/nowrap$" "$section/nowrap$" "$date/nowrap$" "$footer/nowrap$" "$header/nowrap$"
$if(hyphenate)$
.hy
$else$
.nh
$endif$
$for(header-includes)$
$header-includes$
$endfor$
$for(include-before)$
$include-before$
$endfor$
$body$
$for(include-after)$
$include-after$
$endfor$
$if(author)$
.SH AUTHORS
$for(author)$$author$$sep$; $endfor$.
$endif$
user@buskill:~$
我发现可以通过设置文档的主标题为<title>(<section>)来设置title和section。
我发现你可以用source.rst
date由于某些原因，在将header和footer定义为字段名时，它们的格式会变得混乱，因此我在命令行中使用
--variable header=five --variable footer=four