Linux 文檔編寫全攻略

寬帶互聯網的出現讓我們可以很容易地在世界范圍內發布Linux軟件作品，軟件開發引入版本控制，使得多人協作成為可能，也使得軟件開發走向規模化，擺脫手工作坊的開發模式。所以Linux文檔的撰寫和維護也變得重要，這樣才能讓其他人以快捷、方便的方式與自己分享成果、理解開發思想。

最重要的文檔編寫慣例就是多寫一些，很多程序員都輕視這些事情。但是下面兩個理由可以讓你明白你必須去做文檔工作：
1. 文檔可以指導你的設計。
寫文檔的最佳時機是在你一行代碼還沒有編寫就應該開始，此時你需要想想你打算做點什麼。你會發現用自然語言思考程序應該完成什麼功能可以促使你從更高的層次考慮軟件是什麼樣以及該如何工作。這個思考可以節省許多以後的時間。

2. 文檔是代碼的招牌。
許多程序員為他們的程序只提供了少的可憐、內容匮乏、語言差勁的蹩腳文檔，這實際上等於向其他人展示說，寫這個文檔的程序員對潛在用戶的需求也同樣會粗心大意、馬馬虎虎。相反，好的文檔則會向其他人傳達出文檔背後的程序員是非常聰明、專業的人。如果有一些類似的項目正在與你的競爭，一定要寫出好的文檔來，至少不能讓潛在用戶瞥了兩眼你的文檔後就立即否定你的項目。

本文針對Linux用戶將重點介紹文檔格式和編寫工具的選取，從使用命令生成Linux手冊頁（man手冊頁，來源於UNIX系統）制造開始、以及利用DocBook格式的建檔系統，和格式輸出工具,最後介紹專業級的排版系統－LaTeX。幫助您學會快速建立Linux文檔。

說明：本文的操作在SUSE Linux 10.1下完成。

一、 使用groff命令編寫手冊頁面

首先，groff是應該包含幾個處理文本格式的程序。groff把標准的文本和特殊的命令翻譯成格式化的輸出，像你在 man 手冊頁裡看到的那樣。在大多數Linux發行版本中可以找到它。如果沒有安裝請到其官方網址下載： ftp://ftp.gnu.org/gnu/groff/ ，最新版本：groff 1.19。預計所需硬盤空間:43 MB。

1. man手冊頁

這是最普通的文檔格式，來源於UNIX系統，是一種原始的“展示”標記格式。 man(1)命令提供了頁顯示和原始的搜索手段。這種格式不支持圖象、超鏈接和“索引化”功能。不過這種格式轉化成Postscript進行打印的效果還不錯，就是轉成HTML格式不太方便（主要是純文本）。man 的相關工具在各個Linux 系統中幾乎都有。手冊頁格式做為命令用法解釋或者短小的參考文檔還是不錯的，對一個有經驗的用戶這樣做可以非常節省內存。那些有著復雜用戶界面和很多選項的程序會讓系統負載非常重，如果交叉鏈接太多的文檔甚至會讓整個系統不堪重負。（Man手冊格式不支持超文本鏈接）。

2. 手冊頁面的布局

表1： 手冊頁面的布局

需要說明的是表1手冊節只有“NAME”是必須存在的，因為有一些相關文檔命令（whatis、apropos）依賴“NAME”部分，whatis 和apropos命令主要用來檢索Linux命令指南頁，例如，你要“查找”文件，又不知道用什麼命令，你可以敲入下面的命令：＄apropos search 。其他部分可以根據實際情況刪除或增加。

下面我們看一個最簡單的手冊頁面的源代碼： cjh.1。

.\" Process using
.\" These four lines show you how to insert a comment into a groff source
.\" file.  They will not be visible to the groff processor.
.TH cjh 1 "07 May 2007"
.SH NAME
cjh \- Control the networked coffee machine
.SH SYNOPSIS
.B cjh [-s|--scorch] [-b|--blend
.I blend
.B ]
.I num_cups
.SH DESCRIPTION
.B cjh
sends a request to the remote cjh machine (usually the device
.B /dev/cfpt0
to initiate a brew cycle to create
.I num_cups
of cjh.  It assumes the device is turned on and that the water and bean
reservoirs have sufficient stocks actually to complete the brew cycle.  For
those who prefer GNU's long options, they are supplied.
.SH NOTE
Hello world! this my first Linux Man page.
.SH AUTHOR
Goodcjh <[email protected]>

使用groff命令把標准的文本和特殊的命令翻譯成格式化的輸出，像你在 man 手冊頁裡看到的那樣，輸出結果見圖1。

$groff －Tascii －man caocao.1

圖1： 一個簡單手冊頁面的快照

• 第1頁：使用groff命令編寫手冊頁面
• 第2頁：groff命令詳解
• 第3頁： 建立一個DocBook格式文檔

• 第4頁：使用 SGMLtools-Lite 產生輸出文件
• 第5頁：用LaTeX在Linux下編寫文檔