下一步: , 上一步: , 上層: 文件   [目錄][索引]


6.9 Man Pages (手冊頁)

在 GNU 專案中,手冊頁是次要的。並非必要或期望每個 GNU 程式都有手冊頁,但有些程式確實有。是否要在你的程式中包含手冊頁,由你自行決定。

當你做出這個決定時,請考慮到支援手冊頁需要每次程式變更時持續付出努力。你花在手冊頁上的時間,會從更有用的工作上被挪用。

對於一個變動不大的簡單程式來說,更新手冊頁可能只是一件小事。那麼,如果已經有手冊頁,就沒有什麼理由不包含它。

對於一個變動很大的大型程式來說,更新手冊頁可能是一個相當大的負擔。如果使用者主動提供捐贈手冊頁,你可能會發現接受這份禮物代價高昂。除非同一個人同意完全負責維護它,以便你可以完全置身事外,否則最好拒絕手冊頁。如果這位志願者之後停止這項工作,那麼不要覺得有義務自己接手;最好從發行版本中撤下手冊頁,直到其他人同意更新它。

當程式只有少量變更時,你可能會覺得差異很小,以至於手冊頁在不更新的情況下仍然有用。如果是這樣,請在手冊頁開頭附近放置一個顯眼的註記,說明你沒有維護它,並且 Texinfo 手冊更具權威性。該註記應說明如何存取 Texinfo 文件。

請務必確保手冊頁包含版權聲明和自由授權。簡單的完全許可授權適用於簡單的手冊頁(請參閱其他檔案的授權聲明,在GNU 維護者資訊中)。

對於長篇手冊頁,具有足夠的解釋和文件,可以被視為真正的手冊,請使用 GFDL(請參閱手冊的授權)。

最後,GNU help2man 程式 (https://gnu.dev.org.tw/software/help2man/) 是一種自動產生手冊頁的方法,在這種情況下是從 --help 輸出產生。這在許多情況下已足夠。


下一步: , 上一步: , 上層: 文件   [目錄][索引]