预计阅读本页时间：-
Chapter�燚ocumentation
Explaining Your Code to燼燱eb-Centric World
Table of Contents
广告：个人专属 VPN，独立 IP，无限流量，多机房切换，还可以屏蔽广告和恶意软件，每月最低仅 5 美元
The Large-Document Bias
Cultural Style
The Zoo of Unix Documentation Formats
troff and the Documenter's Workbench Tools
TeX
Texinfo
POD
HTML
DocBook
The Present Chaos and a Possible Way Out
Document Type Definitions
Other DTDs
The DocBook Toolchain
Migration Tools
Editing Tools
Related Standards and Practices
SGML
XML-DocBook References
Best Practices for Writing Unix Documentation
Unix's first application, in 1971, was as a platform for document preparation — Bell Labs used it to prepare patent documents for filing. Computer-driven phototypesetting was still a novel idea then, and for years after it debuted in 1973 Joe Ossana's troff(1) formatter defined the state of the art.
Ever since, sophisticated document formatters, typesetting software, and page-layout programs of various sorts have been an important theme in the Unix tradition. While troff(1) has proven surprisingly durable, Unix has also hosted a lot of groundbreaking work in this application area. Today, Unix developers and Unix tools are at the cutting edge of far-reaching changes in documentation practice triggered by the advent of the World Wide Web.
At the user-presentation level, Unix-community practice has been moving rapidly toward ‘everything is HTML, all references are URLs’ since the mid-1990s. Increasingly, modern Unix help browsers are simply Web browsers that know how to parse certain specialized kinds of URLs (for example, ‘man:ls(1)’ interprets the ls(1) man page into HTML). This relieves the problems created by having lots of different formats for documentation masters, but does not entirely solve them. Documentation composers still have to grapple with issues about which master format best meets their particular needs.
In this chapter, we'll survey the rather unfortunate surfeit of different documentation formats and tools left behind by decades of experimentation, and we'll develop guidelines for good practice and good style.
Portability, Open Standards, and Open Source Home 燚ocumentation Concepts
