我的问题是,在一个项目接近完成后,是时候专注于文档之类的事情了,其中之一就是手册页。
现在,人们可能不喜欢手册页,也可能不喜欢手册页,但是随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命令是做什么的,等等)
这些页面是一个有益的开端,但我很快就用尽了它们的用处:
编辑:手册页中的更多信息
谢谢,史蒂芬·哈里斯。
发布于 2016-08-12 02:52:36
这两个版本之间的差异是由于不同的宏集:原始man集和较新的mdoc集。您可以看到每个命令都有哪些命令。
man 7 man
man 7 mdoc所以像.Op这样的东西只有使用mdoc才是有效的。
这两种版本都适用于现代系统;我可能会考虑使用mdoc格式。
https://unix.stackexchange.com/questions/302907
复制相似问题