同步阅读进度,多语言翻译,过滤屏幕蓝光,评论分享,更多完整功能,更好读书体验,试试 阅读 ‧ 电子书库
Chapter�燚ocumentation
Explaining Your Code to燼燱eb-Centric World
Table of Contents
Documentation Concepts
The Unix Style
The Large-Document BiasCultural StyleThe Zoo of Unix Documentation Formats
troff and the Documenter's Workbench ToolsTeXTexinfoPODHTMLDocBookThe Present Chaos and a Possible Way Out
DocBook
Document Type DefinitionsOther DTDsThe DocBook ToolchainMigration ToolsEditing ToolsRelated Standards and PracticesSGMLXML-DocBook ReferencesBest 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.
Prev Up Next
Portability, Open Standards, and Open Source Home 燚ocumentation Concepts
请支持我们,让我们可以支付服务器费用。
使用微信支付打赏