Colophon for the WN User's Guide

colophon n. An inscription placed usually at the end of a book, giving facts about its publication. [< Gk. kolophon, finishing touch.] - The American Heritage dictionary

The User's Guide for the WN Server was written by John Franks who is also the author of the WN software. Editorial changes and cleanup of the HTML source for the User's Guide was contributed by Jean Pierre LeJacq. This colophon describes the approach and tools used to write and validate the HTML source code.

I.1 Goals

We had the following goals for the HTML source code:

I.1.1 Valid HTML

WN emphasizes the adherence the Internet standards such as HTML and HTTP. Basically, we want to practice what we preach in the documentation for WN.

The User's Guide was written using HTML 3.2 instead of the more recent HTML 4.0 since the former is currently better supported in both textual and graphical browsers.

I.1.2 HTML That Follows Good Style

As with any language, valid HTML can be written in a way that makes it difficult to maintain, non-portable and against the basic principles HTML embodies.

For example of the latter, we consider HTML primarily as a language that describes the semantic structure and not the visual representation of documents. Consequently, only minor use of HTML tags was made for formatting (e.g. centering of a documents title). Even these minor formatting decisions could be eliminated through the use of Style Sheets. However, these are currently not well supported by many browsers so they were not employed.

As an example or more minor portability issue, we check that there is no intervening white space in the start of an anchor, "<a>", tag. Browsers are inconsistent in how the display this extra white space.

I.1.3 Extensive Use of Valid Links

One of the great strengths of HTML is the linking of widely dispersed documents to create a seamless virtual document. We have provided extensive links to relevant standards, manual pages and sites to maximize this advantage. The User's Guide itself is extensively cross-linked. We also wanted to insure that the links were valid.

I.1.4 Example of Well Written HTML

One of the unfortunate consequences of the popularity of the Internet is the low quality of much of the HTML documents. Since learning by example is so important, we wanted to provide WN users an example of well written HTML.

I.2 Tools

I.2.1 Operating Systems

I.2.1.1 Linux

All of the editing and validation of the User's Guide was done using the Linux Operating System developed primarily by Linus Torvalds. We used the Debian GNU/Linux distribution developed by many volunteers on the Internet. Much of the editing was done as part of the packaging of WN for Debian.

I.2.2 Editors

I.2.2.1 Xemacs Editor

All of the editing of the User's Guide was done using the Xemacs text editor. XEmacs stems from a collaboration of Lucid, Inc. with Sun Microsystems, Inc. and the University of Illinois with additional support having been provided by Amdahl Corporation, Altrasoft and a huge amount of volunteer effort.

Much of the power of Xemacs is based on the lisp packages that are either part of the core Xemacs distribution or add-ons. We cannot list all of the packages but I do follow with several particularly important packages for editing HTML documents.

I.2.2.1.1 Emacs hm--html-menus Mode

The hm--html-menus package provides functions and various popup and pulldown menus for a HTML mode called hm--html-mode, a mode for writing HTML pages. The primary author is Heiko Muenkel. It provides also a minor mode, hm--html-minor-mode, which can be used together with another HTML major mode, like the psgml-html mode which is exactly what we did.

I.2.2.1.2 Emacs psgml Mode

psgml is a major mode for editing SGML documents. psgml contains a simple SGML parser and can work with any DTD. Functions provided includes menus and commands for inserting tags with only the contextually valid tags, identification of structural errors, editing of attribute values in a separate window with information about types and defaults and structure based editing. It also provides an interface to an external SGML parser, such as SP, to rigorously validate a file.

psgml is currently maintained by Lennart Staflin.

I.2.2.1.3 Emacs/W3 Browser

Emacs/W3 is a full-featured web browser, written entirely in Emacs-Lisp, that supports all the bells and whistles you will find in use on the web today, including frames, tables, stylesheets, and much more. We used as a quick validation of the basic presentation of the pages.

I.2.3 Validators

I.2.3.1 SP SGML Parser

SP is a free object-oriented toolkit for SGML parsing and entity management developed by James Clark. It includes the nsgmls program which parses and validates the SGML documents whose document entity is specified by the system identifiers sysid.

The Emacs psgml mode supports invoking nsgmls and parsing its output. We used the following sysid at the beginning of all HTML documents:

<!doctype html public "-//W3C//DTD HTML 3.2 Final//EN">

I.2.3.2 Weblint HTML Style Checker

Weblint is a Perl program for syntax and minimal style checking of HTML developed by Neil Bowers. We use in conjunction to SP to prevent the use of valid HTML that is either difficult to maintain or poorly supported by current browsers.

I.2.3.3 Linbot HTML Link Checker

linbot is a Python program that allows webmasters to: view the structure of a site; track down broken links; find potentially outdated HTML pages; list links pointing to external sites; view portfolio of inline images; and do all this periodically and without user intervention. Results are displayed in a set of HTML pages.