| WebMan: A Basic RefEntry Servlet | ||
|---|---|---|
| <<< Previous | Using the RefEntry Servlet and Client | Next >>> |
For this section it is assumed you have some experience editing XML documents, that you know how to handle DTDs in your environment, and that you know enough about DocBook reference entries and man pages to write documents against the RefEntry DTD without breaking much of a sweat. If you do not feel comfortable editing SGML/XML documents in your environment, consider reading Bob DuCharme's book, SGML CD. Bob shows you how to get started with free software tools, so you do not have to pour money in before you even get started. (In my experience, the free tools are easier to use than the expensive ones, anyway.) If you do not feel comfortable writing man pages in DocBook, consider Norman Walsh's DocBook: The Definitive Guide. You can get a preview from http://docbook.org/. This servlet comes with a number of examples, too. My markup is less informed than Norman's, but then my DTD is a lot simpler than DocBook.
In addition to prerequisite knowledge, you'll also need an XML parser, such as Xerces, which you may have installed with the other software as part of the HttpUnit pack. You cannot use the servlet format tool without org.apache.xerces.parsers.SAXParser in your CLASSPATH. You may decide that you want an alternative XSLT processor as well for general purposes, in which case a useful free tool is Xalan for Java from the Apache Software Foundation, somewhere under http://xml.apache.org/. If you have the Xalan *.jar files in your CLASSPATH, you also have the Xerces SAXParser.
To Get Started
Follow these steps:
Unpack the servlet content into a working directory using the jar utility.
For example:
$ mkdir -p working-dir $ cd working-dir $ jar -xvf install-dir/refentry.war |
Set your CLASSPATH to include at least the Xerces SAX Parser, the current directory, and the WEB-INF/classes directory where you unpacked the servlet content.
For example:
$ export CLASSPATH=.:working-dir/WEB-INF/classes:$CLASSPATH $ export CLASSPATH=$CLASSPATH:/path/to/xercesImpl.jar |
If you installed the HttpUnit package and set your CLASSPATH as described in the installation procedure, you need only set the current directory and the WEB-INF/classes directory. HttpUnit comes with a Xerces parser implementation.
Set up your system to use the refentry.dtd when editing.
This step depends on your system, and you may have to hack a little to get this to work. On Red Hat Linux 7.2, I had some difficulty when using both DocBook (to write this document) and the RefEntry DTD (to write RefEntry documents) at the same time. Maybe Emacs in PSGML mode had some trouble with both a DocBook RefEntry document type and a system RefEntry document type.
To Create Your First RefEntry
Follow these steps:
Create a new file, test.xml, with the following content:
<?xml version="1.0"?>
<!DOCTYPE refentry SYSTEM "working-dir/src/refentry.dtd">
<refentry>
<refmeta>
<refentrytitle>test</refentrytitle>
<manvolnum>test</manvolnum>
</refmeta>
<refnamediv>
<refname>test</refname>
<refpurpose>test RefEntry servlet code</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>SYNOPSIS</title>
<synopsis>A synopsis.</synopsis>
</refsynopsisdiv>
<refsect1>
<title>REFSECT1</title>
<para>A reference section.</para>
</refsect1>
</refentry> |
Depending on how you set up you set up your environment to edit the document, you may want to change the document type declaration line.
Convince yourself that you can edit this document as you intend.
In particular, if you expect your editor to be aware of the DTD and to facilitate your work, verify that the editor actually does help you insert the elements and attributes as you edit.
Experience has shown me that using an XML-aware editor is a good way to get to know a DTD.
To Create Check RefEntry Validity
Follow these steps:
Ensure you have set your CLASSPATH appropriately as described in Procedure 1, To Get Started.
Change to the directory where you unpacked the servlet content.
Run the format command on the file.
For example:
$ java format -infile working-dir/src/test/test.xml <html xmlns="http://www.w3.org/1999/xhtml"> <head> <title>test(test) - test RefEntry servlet code</title> </head> <body bgcolor="white"> <form> <input name="SrchString" size="60" value="" /> <input type="submit" value="Search" /> </form> <hr /> <div> <table width="100%" border="0"> <tr> <td align="left">test(test)</td><td align="center">Section unknown (see refentry.xslt)</td><td align="right">test(test)</td> </tr> </table> <h1>NAME</h1> <blockquote> <tt>test</tt> - test RefEntry servlet code</blockquote> <h1>SYNOPSIS</h1> <blockquote> <p> <tt>A synopsis.</tt> </p> </blockquote> <h1>REFSECT1</h1> <blockquote> <p>A reference section.</p> </blockquote> </div> <table border="0" width="100%"> <tr> <td align="left">Generated [Sun Feb 23 07:22:52 CET 2003]</td> <td align="right">Server [CLI format]</td> </tr> </table> </body> </html> |
At this point, if your XML is not valid, the format command tells you why.
For example:
$ java format -infile src/test/invalid.xml ==>Fatal parse error<== Line: 21 URI: null Message: XML document structures must start and end within the same entity. org.xml.sax.SAXException: Fatal parse error encountered Input file is not valid. |
| <<< Previous | Home | Next >>> |
| Using the RefEntry Servlet and Client | Up | Building A Servlet of Your Own |