The Art of Unix Programming

haoji

This is generally considered the biggest and nastiest conversion problem. And indeed,
the basic troff(1) markup is at too low a presentation level for automatic conversion
tools to do much of any good. However, the gloom in the picture lightens significantly
if we consider translation from sources of documents written in macro packages like
man(7). These have enough structural features for automatic translation to get some
traction.
The author of this book wrote a tool to do troff-to-DocBook himself, because he
couldn't find anything else that did a half-decent job of it. It's called doclifter. It will
translate to either SGML or XML DocBook from man(7), mdoc(7), ms(7), or me(7)
macros. See the documentation for details.


Editing tools

One thing we do not have at time of writing is a good open-source structure editor for
SGML/XML documents.

LyX is a GUI word processor that uses LaTeX for printing and supports structural editing of
LaTeX markup. There is a LaTeX package that generates DocBook, and a how-to document
escribing how to write SGML and XML in the LyX GUI.

GeTox, the GNOME XML Editor, aims at nontechnical users. But the software is still alpha,
more a proof of concept than anything useful, and the project group seems not to be very
active; there have been no updates of the website between May 2001 and time of writing.

GNU TeXMacs is a project aimed at producing an editor that is good for technical and
mathematical material, including displayed formulas. 1.0 was released in April 2002. The
developers plan XML support in the future, but it's not there yet.

ThotBook is a project to put together a GUI editor for DocBook based on the Thot toolkit. It
may be moribund; the web page was not updated from November 2001 to time of writing.

Most people still hack the tags by hand using either vi or Emacs, using psgml to validate the
results.

Related standards and practices

haoji

The tools are coming together, if slowly, to edit and format DocBook markup. But DocBook
itself is a means, not an end. We'll need other standards besides DocBook itself to accomplish
the searchable-documentation-database objective. There are two big issues: document
cataloguing and metadata.

The Scrollkeeper project aims directly to meet this need. It provides a simple set of script
hooks that can be used by package install and uninstall productions to register and unregister
their documentation.

Scrollkeeper uses the Open Metadata Format. This is a standard for indexing open-source
documentation analogous to a library card-catalog system. The idea is to support rich search
facilities that use the card-catalog metadata as well as the source text of the documentation
itself.

SGML

In previous sections, we have thrown away a lot of DocBook's history. XML has an older
brother, SGML or Standard Generalized Markup Language.

Until mid-2002, no discussion of DocBook would have been complete without a long
excursion into SGML, the differences between SGML and XML, and detailed descriptions of
the SGML DocBook toolchain. Life can be simpler now; a XML DocBook toolchain is
available in open source, works as well as the SGML toolchain ever did, and is easier to use,
If you don't think you'll ever have to deal with old SGML-Docbook documents, you can skip
the remainder of this section.

DocBook SGML

DocBook was originally an SGML application, and there was an SGML-based DocBook
toolchain that is now moribund. There are minor differences between the DocBook SGML
DTD and the DocBook XML DTD, but for an introductory discussion we can ignore them.
The only one that's normally user-visible is that in SGML contentless tags did not need to
have a trailing slash added to them before the closing >. (Requiring the trailing / means XML
parsers can be a lot simpler, because they don't have to know about the DTD to know which
opening tags need closers.)

Versions of HTML up to 4.01 (before XHTML) were SGML applications. TEI was originally
an SGML application, too. The groups managing all three DTDs jumped to XML for the

haoji

same reason DocBook's developers did 鈥

haoji

But mostly the DSSSL toolchain is dead because DSSSL itself, the SGML stylesheet
description language in that toolchain, proved just too arcane for most human beings, and
made stylesheets too difficult to write and modify.

XML-Docbook References

One of the things that makes learning DocBook difficult is that the sites related to it tend to
overwhelm the newbie with long lists of W3C standards, massive exercises in SGML
theology, and dense thickets of abstract terminology. See XML In A Nutshell
[Harold&Means] for a good book-length general introduction. Here are some useful Web
resources:

Norman Walsh's DocBook: The Definitive Guide is available in print and on the web. This is
indeed the definitive reference, but as an introduction or tutorial it's a disaster. Instead, read
this:

Writing Documentation Using DocBook: A Crash Course. This is an excellent tutorial.

There is an equally excellent DocBook FAQ with a lot of material on styling HTML output.
There is also a DocBook wiki.

Finally, the The XML Cover Pages will take you into the jungle of XML standards if you
really want to go there.

Prev Up Next

The present chaos and a possible
way out

Home How to write Unix documentation

haoji

How to write Unix documentation

Prev Chapter 16. Documentation

Next



How to write Unix documentation

The advice we gave earlier in the chapter about reading Unix documentation can be turned
around. When you write documentation for people within the Unix culture, don't dumb it
down, and don't think for a moment that that volume will be mistaken for quality. If you
write as if for idiots, you will be written off as an idiot yourself. Especially, never ever omit
functional details because you fear they might be confusing, or warnings about problems
because you don't want to look bad. It is unanticipated problems that will cost you credibility
and users, not the ones you were honest about.

If your project is of any significant size, you should probably be shipping three different
kinds of documentation: man pages, a tutorial manual, and a FAQ (Frequently Asked
Questions) list.

In your source code, include the standard metainformation files described in Chapter 17
(Open Source)'s section on open-source release practices, such as README. Even if your
code is going to be proprietary, these are Unix conventions and future maintainers coming
from a Unix background will come up to speed faster if they are followed.

Your man pages should be command references in the traditional Unix style for the
traditional Unix audience. The tutorial manual should be long-form documentation for non-
technical users. And the FAQ should be an evolving resource that grows as your software
support group learns what the frequent questions are and how to answer them.

There are more specific habits you should adopt if you want to get a little ahead of early
2003's practice:

1.
Maintain your document masters in XML-DocBook. Even your man pages can be
DocBook RefEntry documents. There is a very good HOWTO on writing manual
pages that explains the sections and organization your users will expect to see.
2.
Ship the XML masters. Also, in case your users' systems don't have xmlto(1) ship the
troff sources that you get by running xmlto man on your masters. Your software
distribution's installation procedure should install those in the normal way, but direct
people to the XML files if they want to write documentation patches.

haoji

3.
Make your project's installation package Scrollkeeper-ready.
4.
Generate XHTML from your masters (with xmlto xhtml) and make it available from
your project's web page.


Whether you're using XML-Docbook as a master format, you'll want to find a way to convert
your documentation to HTML. Whether your software is open-source or proprietary, users
are increasingly likely to find it via the Web. Putting your documentation on-line has the
direct effect of making it easier for potential users and customers who know your software
exists to read it and learn about it. It has the indirect effect that your software will become
more likely to turn up in a Web search by people who don't know about it.

Prev Up Next

DocBook

Home Chapter 17. Open Source

haoji

Chapter 17. Open Source

Prev Part IV. Community

Next



Chapter 17. Open Source

Programming In The Unix Community

Table of Contents

Unix and open source
Best practices for working with open-source developers
Good patching practice
Good project- and archive- naming practice
Good development practice
Good distribution-making practice
Good communication practice



The logic of licenses: how to pick one
Why you should use a standard license
Varieties of Open-Source Licensing
X Consortium License
BSD Classic License
Artistic License
General Public License
Mozilla Public License





Software is like sex 鈥

haoji

We'll then descend from realm of abstraction and describe some of the most important folk
customs that Unix has picked up from the open-source community 鈥

haoji

Unix and open source

Prev Chapter 17. Open Source

Next



Unix and open source

Open-source development exploits the fact that characterizing and fixing bugs 鈥

haoji

The rules of open-source development are simple:

1.
Let the source be open. Have no secrets. Make the code and the process that produces
it public. Encourage third-party peer review. Grow the co-developer community as big
as you can.
2.
Release early, release often. A rapid release tempo means quick and effective
feedback. When each incremental release is small, changing course in response to real-
world feedback is easier. But don't release too early; a first release that won't build and
can permanently kill interest in a project (as nearly happened to Mozilla).
3.
Reward contribution with praise. If you can't give your co-developers material
rewards, they need immaterial ones. Even if you can, people will often work harder for
reputation than they would for gold.


Open-source development uses large teams of programmers distributed over the Internet and
communicating primarily via email and Web documents. Typically, most contributors to any
given project are volunteers contributing in order to be rewarded by the increased usefulness
of the software to them, and by reputation incentives. A central individual or core group
steers the project; other contributors may drop in and drop out sporadically.

Open-source projects follow the Unix-tradition advice of automating wherever possible. They
use the patch(1) tool to pass around incremental changes. Many projects (and all large ones)
have network-accessible code repositories using version-control systems like CVS (recall the
discussion in chapter 13 (Tools)). Use of automated bug- and patch-tracking systems is also
common.

In 1997, almost nobody outside the hacker culture understood that it was even possible to run
a large project this way, let alone get high-quality results. In 2003 this is no longer news;
projects like Linux, Apache, and Mozilla have achieved both success and high public
visibility.

Abandoning the habit of secrecy in favor of process transparency and and peer review was
the crucial step by which alchemy became chemistry. In the same way, it is beginning to
appear that open-source development may signal the long-awaited maturation of software
development as a discipline.

Prev Up Next