documentation - 如何设置以 reStructuredText 编写的联机帮助页中标题行的所有参数，并使用 pandoc 转换为 groff

Question

从 .rst 文件转换为 时，如何让 pandoc 正确设置“标题行”(.TH) 中的所有参数>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-program\f[R]
.SH Description
.PP
\f[B]my-program\f[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-program\f[R]
.SH Description
.PP
\f[B]my-program\f[R] is magical.
It does what you need!
user@buskill:~/tmp/groff$ 

我需要向 source.rst 文件添加什么，以便 pandoc 填充目标文件的 .TH 行中的参数？一般来说，我在哪里可以找到描述这一点的引用文档？

Answer 1

您可以通过在标题中包含该部分来解决此问题，定义 date在source.rst ，并设置 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-program\f[R]
.SH Description
.PP
\f[B]my-program\f[R] is magical.
It does what you need!
user@buskill:~/tmp/groff$ 

为什么这有效

我在 pandoc 中找不到关于 .rst 之间转换的优秀引用文档。和man ，所以我通过反复试验解决了这个问题。

首先我在 pandoc documentation 中找到您可以使用 -D 查看目标格式的默认模板论据

• https://pandoc.org/MANUAL.html#templates

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>) .

我发现你可以设置 date与 Field Name在source.rst

出于某种原因，header 的格式发生了变化。和footer将它们定义为字段名称时会变得困惑，所以我在命令行上设置它们

--variable header=five --variable footer=four