RefEntry Development

The documenter creating content marks up RefEntry documents using a text editor or specialized XML editor. Non-conforming documents are rejected by the formatter with detailed information as to where the XML document fails to conform either to the DTD or to the XML standard so the documenter can fix the problem.

The documenter works on an unpacked copy of the original RefEntry servlet. RefEntry documents to be included in the new servlet are listed in a configuration file. This allows the writer to locate the documentation wherever is convenient, but maintain total control over the documents handled by the servlet.

After creating a RefEntry document, the documenter runs the format utility on the document to obtain an XHTML version. This allows the documenter to verify that the formatting appears as desired. Inter-document links may not work during the initial file by file formatting, but otherwise the format utility shows essentially the same final result as the servlet would. The documenter alternately browses and fixes bugs until satisfied with the output.

Once all pages have been developed and the documenter is satisfied with the results, the documenter edits a properties file specifying the content of the new servlet. The documenter may also edit a properties file specifying the words to ignore, and if changing the stylesheets, can edit the properties file specifying the XSLT stylesheets to use. The documenter then builds a new servlet using the Ant build file, build.xml. The new servlet can then be installed in a servlet container and used to serve RefEntry documents.