Preface

You are reading the documentation for a CS445 Independent Programming Project. The project involves building a basic servlet for reference manual entries.

Background

A key element of product documentation for software written on UNIX systems, online man pages have been around for a long time. Dennis Ritchie originally wrote the man command to format reference documentation for display on a terminal. The command has a few helpful but aging features for searching and displaying reference documentation. Although more recent forms of online help have surpassed its user-friendliness, many UNIX developers use man more than any other documentation tool.

The man command implementations available today remain based on roff formatting tools, so documenters either format online manual pages directly with roff macros, or they mark up the manual pages in another language, which the command then translates to roff markup for formatting with the old tools.

Recently, XML languages and tools have begun to appear. Applications have started to offer support for languages such as XSLT and XPath to format and search XML documents. Today applications can do more, more simply, with reference manual entries edited using XML markup than used to be feasible with roff markup. XML makes it easier for example to write a reference manual browser that beginners find intuitive.

XML also implies semantic rather than presentational markup. This means XML RefEntry documents need no rewriting when tools change, only when content changes. Documenters can mark up given content once and then web developers can reformat them as needed using languages such as XSLT. Furthermore, as XSLT engines are available on all platforms, developers no longer need lots of extra software or a UNIX system to read RefEntry documents. This could encourage documenters to write reference manual entries with XML markup for cross-platform portability.