![](/img/trans.png)
[英]Missing ".TH" section when converting .rst file to groff format in pandoc (reStructuredText, manpage)
[英]How to set all arguments of the Title line in manpage written in reStructuredText, converted to groff with pandoc
从 a.rst 文件转换为man
文件时,如何让pandoc
在“标题行”( .TH
)中正确设置所有 arguments ?
根据文档man man-pages
,“标题行”的位置为 arguments:
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 标题的 a.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
的第一个参数,但其余的 arguments 都是空白的。 如果我尝试直接在标题中指定它们,那是行不通的。
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
行中填充 arguments? 而且,一般来说,我在哪里可以找到描述这一点的参考文档?
您可以通过在标题中包含该部分、在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-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 文档中发现您可以使用-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
声明:本站的技术帖子网页,遵循CC BY-SA 4.0协议,如果您需要转载,请注明本站网址或者原文地址。任何问题请咨询:yoyou2525@163.com.