第122页 | The Art of UNIX Programming | 阅读 ‧ 电子书库

同步阅读进度,多语言翻译,过滤屏幕蓝光,评论分享,更多完整功能,更好读书体验,试试 阅读 ‧ 电子书库

Chapter�燚ocumentation

Explaining Your Code to燼燱eb-Centric World

Table of Contents

Documentation Concepts

The Unix Style

The Large-Document BiasCultural Style

The Zoo of Unix Documentation Formats

troff and the Documenter's Workbench ToolsTeXTexinfoPODHTMLDocBook

The Present Chaos and a Possible Way Out

DocBook

Document Type DefinitionsOther DTDsThe DocBook ToolchainMigration ToolsEditing ToolsRelated Standards and PracticesSGMLXML-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.

 

 

 

Prev  Up Next

Portability, Open Standards, and Open Source  Home 燚ocumentation Concepts

请支持我们,让我们可以支付服务器费用。
使用微信支付打赏


上一页 · 目录下一页


下载 · 书页 · 阅读 ‧ 电子书库