在编写手册页时我应该如何以及使用什么样的风格?

我的问题是,在一个项目即将完成之后,是时候专注于文档之类的东西,其中一个是手册页.

现在,人们可能会也可能不会不喜欢手册页,但是随附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
...

它使用prety很多没有转义序列,而文本是这样的结构:

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

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

还有其他类似的例子,任何编写手册页的人都知道各种风格等.

在这一点上,我很困惑我应该遵循哪种风格.至少一些参考指南会很好,基本上可能是一个入门或者应该如何处理它的东西. (例如,我还没弄清楚.SY命令的作用等等)

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

> http://www.linuxhowtos.org/System/creatingman.htm
> https://www.linux.com/news/what-you-need-know-write-man-pages
> http://liw.fi/manpages/

编辑:手册页中的更多信息

> http://man7.org/linux/man-pages/man7/groff_man.7.html
> http://man7.org/linux/man-pages/man7/mdoc.samples.7.html
> http://man7.org/linux/man-pages/man7/mdoc.7.html

谢谢,斯蒂芬哈里斯.

最佳答案
两个版本之间的差异是由于不同的宏集;原始人集和新的mdoc集.您可以看到每个人拥有的命令

man 7 man
man 7 mdoc

所以像.Op这样的东西只能使用mdoc

任何一个版本都应该适用于现代系统;我可能会考虑mdoc格式.

转载注明原文:在编写手册页时我应该如何以及使用什么样的风格? - 代码日志