☰

编写手册页时应该如何使用以及使用什么风格？

tag-icon • tag-icon man documentation
编写手册页时应该如何使用以及使用什么风格？

我的问题是，在项目接近完成后，是时候专注于文档之类的事情了，其中之一就是手册页。

现在，人们可能不喜欢手册页，也可能不喜欢，但随 Linux 工具一起提供几乎是标准做法。

然而，我的问题是找到有关如何准确构建和编写一个的信息。

我知道有一些粗略的指导方针，应该始终包含哪些部分等等。但我主要依靠已经编写的手册页来了解诸如groff、ssh、 之类的内容，并base64了解如何（正确）编写一个。

问题是，他们的风格差异很大。

的手册页base64使用常规命令，如.SH和.TP，但不使用.OP通常用于选项表的命令。然而它使用类似 troff 的转义序列：

.TP
\fB\-d\fR, \fB\-\-decode\fR
decode data

可以这么说，这很简单。

的手册页groff是一个完全不同的故事。它在概要中使用类似的开关.SY命令：.OP

.SH SYNOPSIS
.\" --------------------------------------------------------------------
.
.SY groff
.OP \-abcegijklpstzCEGNRSUVXZ
.OP \-d cs
.OP \-D arg
.OP \-f fam
...

它几乎不使用转义序列，而是文本的结构如下：

.TP
.B \-j
Preprocess with
.BR chem .
.
Implies
.BR \-p .

即使用 troff 命令而不是转义序列。

还有其他类似的例子，任何写过手册页的人都知道不同的风格，等等。

此时，我很困惑我应该遵循哪种风格。至少有一些参考指南会很好，基本上可能是一本入门书或一些关于如何实现这一点的东西。 （例如，我还没弄清楚该.SY命令是做什么的，等等）

这些页面是一个有用的开始，但我很快就耗尽了它们的用处：

编辑：手册页中的一些更多信息

谢谢，斯蒂芬·哈里斯。

答案1

两个版本的差异是由于宏集不同造成的；原始man集和新mdoc集。你可以看到每个人都有什么命令

man 7 man
man 7 mdoc

所以像这样的东西.Op只有使用才有效mdoc

任一版本在现代系统上都应该没问题；我可能会考虑mdoc格式。

相关内容