Linux 文档编写全攻略

【IT168 开发】宽带互联网的出现让我们可以很容易地在世界范围内发布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 <goodcjhl@2911.com>

    使用groff命令把标准的文本和特殊的命令翻译成格式化的输出，像你在 man 手册页里看到的那样，输出结果见图1。

$groff －Tascii －man caocao.1

图1： 一个简单手册页面的快照