編寫手冊頁時應該如何以及使用什麼風格？

我的問題是，在一個項目接近完成之後，是時候關注文件之類的事情了，其中之一就是手冊頁。

現在，人們可能不喜歡手冊頁，也可能不喜歡手冊頁，但是隨 Linux 工具一起發布是非常標準的。

然而，我的問題是找到有關如何準確建構和編寫一個的資訊。

我知道有一些粗略的指導方針，應始終包括哪些部分，等等，但我主要依賴於已經編寫的手冊頁，例如groff, ssh，並base64了解如何（正確）編寫一個。

問題是，他們的風格差異很大。

的手冊頁使用和base64等正常命令，但不使用通常用於選項表的命令。但是它使用類似 troff 的轉義序列：.SH``.TP``.OP

.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命令的作用等）

這些頁面是一個有用的開始，但我很快就用盡了它們的用處：

• 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

謝謝，斯蒂芬哈里斯。

兩個版本的差異是由於不同的宏集；原始man集和新mdoc集。你可以看到每個人都有什麼命令

man 7 man
man 7 mdoc

所以像這樣.Op的東西只有使用才有效mdoc

在現代系統上，任何一個版本都應該沒問題；我可能會考慮mdoc格式。

引用自：https://unix.stackexchange.com/questions/302907