放入手冊頁的最佳做法頁面

Question

是否有寫手冊頁的最佳做法指南？

什麼應該包含在佈局中？標準的有：
NAME
概要
說明
例
另請參閱

還有其他類似選項，作者。

作爲一個用戶什麼是有用的？什麼沒有幫助？

Answer 1

如果你找不到20世紀70年代貝爾實驗室的「troff」文檔的任何舊版本的副本，其中有一些關於編寫手冊頁的很好的部分:-)那麼我建議在他的網站上試用Jens的"HOWTO" on writing man pages。

---

的Unix 7th Edition手冊可在網上​​以多種格式。

Answer 2

這取決於你的軟件的功能。如果它是一個小型獨立應用程序，我肯定會將AUTHOR部分放在手冊頁中，以便如果用戶發現錯誤，他們可以很容易地找到一個電子郵件地址來向您報告錯誤。

至於最佳實踐，除了手冊頁應該簡潔，詳細但不包含太多不需要的信息之外，我不知道的最佳實踐，如果它只是一個工具，內部工作不是必需的例。

Answer 3

BUGS部分很不錯，而EXAMPLES部分總是有用的。某些手冊頁包含一個 FILES部分，其中列出了相關的配置文件，或者包含ENVIRONMENT部分，詳述了任何有影響的環境變量。

要清楚，哪些部分或信息類型對用戶有用取決於您正在記錄的程序或實用程序的性質。

Answer 4

有一個與UNIX系統分佈的規範手冊頁大綱，或者至少通常有。一般來說，我會放入所有字段，並且如果不適用，則包含一個類似「無」的行。

Answer 5

有時候人們忘記放在手冊頁中的一件事是函數返回值的含義。這很容易被遺忘，但這種遺漏會讓那些必須使用你的功能的人變得更加困難。此外，概要中的簡單代碼段或者一個很好的最小工作示例非常有用。

我經常用手冊頁做的一件事是嘗試找到一個相關的命令，即使我知道我正在看的東西沒有做我想要的。在這種情況下，SEE ALSO很棒。