首页
学习
活动
专区
圈层
工具
发布
社区首页 >问答首页 >在编写手册页时,我应该使用什么样式?

问在编写手册页时,我应该使用什么样式?
EN

Unix & Linux用户
提问于 2016-08-12 02:29:42
回答 1查看 225关注 0票数 4

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

现在,人们可能不喜欢手册页,也可能不喜欢手册页,但是随Linux工具一起提供是很正常的。

然而,我的问题是找到关于如何准确地构造和编写结构的信息。

我知道有一些粗略的指导方针,应该总是包括哪些部分,等等,但我主要依靠已经编写好的手册页来编写诸如groff、ssh和base64之类的内容,以获得如何(正确)编写手册的想法。

问题是,他们的风格有很大的不同。

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

代码语言:javascript
复制
.TP
\fB\-d\fR, \fB\-\-decode\fR
decode data

可以说,这是相当简单的。

groff的手册是完全不同的故事。它在概要中对开关使用.SY和.OP命令:

代码语言:javascript
复制
.SH SYNOPSIS
.\" --------------------------------------------------------------------
.
.SY groff
.OP \-abcegijklpstzCEGNRSUVXZ
.OP \-d cs
.OP \-D arg
.OP \-f fam
...

它使用prety --根本没有转义序列,相反,文本是这样的结构:

代码语言:javascript
复制
.TP
.B \-j
Preprocess with
.BR chem .
.
Implies
.BR \-p .

也就是说,使用troff命令而不是转义序列。

还有其他类似的例子,任何写手册的人,都会注意到不同的风格等等。

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

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

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

谢谢,史蒂芬·哈里斯。

EN

回答 1

Unix & Linux用户

回答已采纳

发布于 2016-08-12 02:52:36

这两个版本之间的差异是由于不同的宏集:原始man集和较新的mdoc集。您可以看到每个命令都有哪些命令。

代码语言:javascript
复制
man 7 man
man 7 mdoc

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

这两种版本都适用于现代系统;我可能会考虑使用mdoc格式。

票数 3
EN
页面原文内容由Unix & Linux提供。腾讯云小微IT领域专用引擎提供翻译支持
原文链接:

https://unix.stackexchange.com/questions/302907

复制
相关文章

相似问题

领券
问题归档专栏文章快讯文章归档关键词归档开发者手册归档开发者手册 Section 归档