1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
|
<html><head>
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<title>README for the JRefEntry DTD V1.1</title><meta name="generator" content="DocBook XSL Stylesheets V1.40"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="article"><div class="titlepage"><div><h2 class="title"><a name="d39e1"></a>README for the JRefEntry DTD V1.1</h2></div><div><p class="copyright">Copyright © 2000, 2001 Norman Walsh</p></div><div><div class="legalnotice"><p>Java and JavaDoc are registered trademarks of
Sun Microsystems, Inc.</p></div></div><hr></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt> <a href="#d39e17">Overview</a></dt><dt> <a href="#d39e128">Manifest</a></dt><dt> <a href="#d39e144">Installation</a></dt><dt> <a href="#d39e157">Copyright</a></dt><dt> <a href="#d39e176">Warranty</a></dt><dt> <a href="#d39e181">Contacting the Author</a></dt></dl></div><p>This is a customization of the DocBook RefEntry model. The
purpose of this customization is to mirror the order and nature
of structured comment tags in JavaDoc documentation.</p><div class="section"><a name="d39e17"></a><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="d39e17"></a>Overview</h2></div></div><p>JavaDoc comments for a consist of a purpose followed by a
description followed by additional, optional tags. This structure
is modelled by JRefEntry as follows:</p><div class="informaltable" id="d39e22"><a name="d39e22"></a><table border="1"><colgroup><col width="50%"><col width="50%"></colgroup><thead><tr><th>JavaDoc tag</th><th>JRefEntry element</th></tr></thead><tbody><tr><td><i>purpose</i> (contextual)</td><td><tt>refpurpose</tt></td></tr><tr><td><i>description</i> (contextual)</td><td><tt>refdescription</tt></td></tr><tr><td>@author</td><td><tt>refauthor</tt></td></tr><tr><td>@version</td><td><tt>refversion</tt></td></tr><tr><td>@param</td><td><tt>refparameter</tt></td></tr><tr><td>@return</td><td><tt>refreturn</tt></td></tr><tr><td>@exception</td><td><tt>refexception</tt></td></tr><tr><td>@throws (alternate for @exception)</td><td><tt>refthrows</tt> (alternate for <tt>refexception</tt>)</td></tr><tr><td>@see</td><td><tt>refsee</tt></td></tr><tr><td>@since</td><td><tt>refsince</tt></td></tr><tr><td>@serial</td><td><tt>refserial</tt></td></tr><tr><td>@deprecated</td><td><tt>refdeprecated</tt></td></tr></tbody></table></div><p>Within sections that would normally be repeated (e.g., @param),
use a <tt>variablelist</tt> for each individual item. To break
the items into groups, use separate lists.</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title"><a name="d39e116"></a>Note</h3><p>The content models of each of these special sections are
designed so that the could easily be mapped to a normal DocBook
<tt>refentry</tt>. For example,
<tt><refdescription></tt>
could easily be mapped to
<tt><refsect1><title>Description</title></tt>.</p></div></div><div class="section"><a name="d39e128"></a><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="d39e128"></a>Manifest</h2></div></div><div class="variablelist"><dl><dt><a name="d39e132"></a><span class="term">README</span></dt><dd><p><a name="d39e135"></a>This readme file.</p></dd><dt><a name="d39e138"></a><span class="term">jrefentry.dtd</span></dt><dd><p><a name="d39e141"></a>The JRefEntry DTD. It is built on top of the XML version of
DocBook V4.0.</p></dd></dl></div></div><div class="section"><a name="d39e144"></a><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="d39e144"></a>Installation</h2></div></div><p>Place the files in this distribution somewhere on your machine. Adjust
your catalog(s) if appropriate (XML tools frequently do not support
catalogs, so this may be irrelevant for you).</p><p>Please use the following formal public identifier to identify this
DTD:</p><pre class="programlisting">
-//Norman Walsh//DTD JRefEntry V1.0//EN
</pre><p>For example, to write a JRefEntry document, you might use
this DOCTYPE declaration:</p><pre class="programlisting">
<!DOCTYPE refentry
PUBLIC "-//Norman Walsh//DTD JRefEntry V1.0//EN"
"http://nwalsh.com/docbook/jrefentry/1.0/jrefentry.dtd">
</pre></div><div class="section"><a name="d39e157"></a><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="d39e157"></a>Copyright</h2></div></div><div class="literallayout"><br>
JRefEntry DTD V1.0<br>
Copyright © 2000 Norman Walsh<br>
http://nwalsh.com/docbook/jrefentry/<br>
</div><p>You may distribute this DTD under the same terms as DocBook.</p><p>Please direct all questions and comments about this DTD to
Norman Walsh, <tt><<a href="mailto:ndw@nwalsh.com">ndw@nwalsh.com</a>></tt>.</p><p>This DTD is based on DocBook XML V4.1.2 from OASIS.</p><p>For more information about the DocBook DTD, see
<a href="http://www.oasis-open.org/docbook/" target="_top">http://www.oasis-open.org/docbook/</a>.</p></div><div class="section"><a name="d39e176"></a><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="d39e176"></a>Warranty</h2></div></div><p>THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
NONINFRINGEMENT. IN NO EVENT SHALL NORMAN WALSH OR ANY OTHER
CONTRIBUTOR BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
OTHER DEALINGS IN THE SOFTWARE.</p></div><div class="section"><a name="d39e181"></a><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="d39e181"></a>Contacting the Author</h2></div></div><p>This DTD is maintained by the DocBook Open Repository team on
<a href="http://sourceforge.net/projects/docbook/" target="_top">SourceForge</a>.
</p></div></div></body></html>
|
