Initial revision

diff --git a/jrefentry/README.xml b/jrefentry/README.xml
new file mode 100644 (file)
index 0000000..5209036
--- /dev/null
+++ b/jrefentry/README.xml
@@ -0,0 +1,181 @@
+<!DOCTYPE article
+  PUBLIC "-//Norman Walsh//DTD Simplified DocBk XML V3.1.7.1//EN"
+  "http://nwalsh.com/docbook/simple/3.1.7.1/sdocbook.dtd">
+<article>
+<artheader><title>README for the JRefEntry DTD V1.0</title>
+<copyright><year>2000</year><holder>Norman Walsh</holder></copyright>
+<legalnotice>
+<para>Java and JavaDoc are registered trademarks of
+Sun Microsystems, Inc.</para>
+</legalnotice>
+</artheader>
+
+<para>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.</para>
+
+<section><title>Overview</title>
+
+<para>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:</para>
+
+<informaltable>
+<tgroup cols="2" pgwide="1">
+<thead>
+<row>
+  <entry>JavaDoc tag</entry>
+  <entry>JRefEntry element</entry>
+</row>
+</thead>
+<tbody>
+<row>
+  <entry><emphasis>purpose</emphasis> (contextual)</entry>
+  <entry><sgmltag>refpurpose</sgmltag></entry>
+</row>
+<row>
+  <entry><emphasis>description</emphasis> (contextual)</entry>
+  <entry><sgmltag>refdescription</sgmltag></entry>
+</row>
+<row>
+  <entry>@author</entry>
+  <entry><sgmltag>refauthor</sgmltag></entry>
+</row>
+<row>
+  <entry>@version</entry>
+  <entry><sgmltag>refversion</sgmltag></entry>
+</row>
+<row>
+  <entry>@param</entry>
+  <entry><sgmltag>refparameter</sgmltag></entry>
+</row>
+<row>
+  <entry>@return</entry>
+  <entry><sgmltag>refreturn</sgmltag></entry>
+</row>
+<row>
+  <entry>@exception</entry>
+  <entry><sgmltag>refexception</sgmltag></entry>
+</row>
+<row>
+  <entry>@throws (alternate for @exception)</entry>
+  <entry><sgmltag>refthrows</sgmltag> (alternate for <sgmltag>refexception</sgmltag>)</entry>
+</row>
+<row>
+  <entry>@see</entry>
+  <entry><sgmltag>refsee</sgmltag></entry>
+</row>
+<row>
+  <entry>@since</entry>
+  <entry><sgmltag>refsince</sgmltag></entry>
+</row>
+<row>
+  <entry>@serial</entry>
+  <entry><sgmltag>refserial</sgmltag></entry>
+</row>
+<row>
+  <entry>@deprecated</entry>
+  <entry><sgmltag>refdeprecated</sgmltag></entry>
+</row>
+</tbody>
+</tgroup>
+</informaltable>
+
+<para>Within sections that would normally be repeated (e.g., @param),
+use a <sgmltag>variablelist</sgmltag> for each individual item. To break
+the items into groups, use separate lists.</para>
+
+<note>
+<para>The content models of each of these special sections are
+designed so that the could easily be mapped to a normal DocBook
+<sgmltag>refentry</sgmltag>. For example,
+<sgmltag class="starttag">refdescription</sgmltag>
+could easily be mapped to
+<literal><![CDATA[<refsect1><title>Description</title>]]></literal>.</para>
+</note>
+
+</section>
+<section><title>Manifest</title>
+
+<variablelist>
+<varlistentry><term>README</term>
+<listitem>
+<para>This readme file.</para>
+</listitem>
+</varlistentry>
+<varlistentry><term>jrefentry.dtd</term>
+<listitem>
+<para>The JRefEntry DTD. It is built on top of the XML version of
+DocBook V4.0.</para>
+</listitem>
+</varlistentry>
+</variablelist>
+
+</section>
+<section><title>Installation</title>
+
+<para>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).</para>
+
+<para>Please use the following formal public identifier to identify this
+DTD:</para>
+
+<programlisting>
+  -//Norman Walsh//DTD JRefEntry V1.0//EN
+</programlisting>
+
+<para>For example, to write a JRefEntry document, you might use
+this DOCTYPE declaration:</para>
+
+<programlisting>
+<![CDATA[<!DOCTYPE refentry
+          PUBLIC "-//Norman Walsh//DTD JRefEntry V1.0//EN"
+                 "http://nwalsh.com/docbook/jrefentry/1.0/jrefentry.dtd">
+]]></programlisting>
+
+</section>
+
+<section><title>Copyright</title>
+
+<literallayout>
+JRefEntry DTD V1.0
+Copyright &copy; 2000 Norman Walsh
+http://nwalsh.com/docbook/jrefentry/
+</literallayout>
+
+<para>You may distribute this DTD under the same terms as DocBook.</para>
+
+<para>Please direct all questions and comments about this DTD to
+Norman Walsh, <email>ndw@nwalsh.com</email>.</para>
+
+<para>This DTD is based on DocBook V4.0 from OASIS.</para>
+
+<para>For more information about the DocBook DTD, see
+<ulink url="http://www.oasis-open.org/docbook/">http://www.oasis-open.org/docbook/</ulink>.</para>
+
+</section>
+<section><title>Warranty</title>
+
+<para>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.</para>
+
+</section>
+<section><title>Contacting the Author</title>
+
+<para>This DTD is maintained by Norman Walsh,
+<email>ndw@nwalsh.com</email>.</para>
+
+<para>The best way to reach norm is by email.  You will find additional
+contact information at
+<ulink url="http://nwalsh.com/~ndw/contact.html">http://nwalsh.com/~ndw/contact.html</ulink>.</para>
+
+</section>
+</article>
+

diff --git a/jrefentry/jrefentry.dtd b/jrefentry/jrefentry.dtd
new file mode 100644 (file)
index 0000000..200e864
--- /dev/null
+++ b/jrefentry/jrefentry.dtd
@@ -0,0 +1,197 @@
+<!-- ====================================================================== -->
+<!-- JRefEntry DTD V1.1
+     Copyright (C) 2000 Norman Walsh
+     http://nwalsh.com/docbook/jrefentry/
+
+     Please direct all questions and comments about this DTD to
+     Norman Walsh, <ndw@nwalsh.com>.
+
+     Common declaration:
+
+     <?xml version="1.0"?>
+     <!DOCTYPE refentry
+       PUBLIC "-//Norman Walsh//DTD JRefEntry V1.1//EN"
+       "http://nwalsh.com/docbook/jrefentry/1.1/jrefentry.dtd">
+                                                                            -->
+<!-- ====================================================================== -->
+
+<!ENTITY % refentry.element "IGNORE">
+<!ENTITY % local.link.char.class "|reflink">
+
+<!ENTITY % docbook PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
+                   "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
+%docbook;
+
+<!ELEMENT reflink (#PCDATA)>
+<!ATTLIST reflink
+       type            CDATA           #IMPLIED
+       %common.attrib;
+       role            CDATA           #IMPLIED
+>
+
+<!ELEMENT refentry ((%ndxterm.class;)*,
+                    refentryinfo?, refmeta?, (remark|%link.char.class;)*,
+                    refnamediv, refsynopsisdiv?, refdescription,
+                    refauthor?, refversion?,
+                    refparameter?, refreturn?, (refexception|refthrows)?,
+                    refsee?, refsince?, refserial?, refdeprecated?)>
+
+<!ENTITY % refinfo.mix "(graphic | mediaobject
+               | legalnotice | modespec
+               | subjectset | keywordset | itermset
+                | %bibliocomponent.mix;)+">
+
+<!ELEMENT refdescription (refdescriptioninfo?, (%refcomponent.mix;)+)>
+<!ATTLIST refdescription
+               %status.attrib;
+               %common.attrib;
+               %refsect1.role.attrib;
+               %local.refsect1.attrib;
+>
+
+<!ELEMENT refauthor (refauthorinfo?, (%refcomponent.mix;)+)>
+<!ATTLIST refauthor
+               %status.attrib;
+               %common.attrib;
+               %refsect1.role.attrib;
+               %local.refsect1.attrib;
+>
+
+<!ELEMENT refversion (refversioninfo?, (%refcomponent.mix;)+)>
+<!ATTLIST refversion
+               %status.attrib;
+               %common.attrib;
+               %refsect1.role.attrib;
+               %local.refsect1.attrib;
+>
+
+<!ELEMENT refparameter (refparameterinfo?, (%refcomponent.mix;)+)>
+<!ATTLIST refparameter
+               %status.attrib;
+               %common.attrib;
+               %refsect1.role.attrib;
+               %local.refsect1.attrib;
+>
+
+<!ELEMENT refreturn (refreturninfo?, (%refcomponent.mix;)+)>
+<!ATTLIST refreturn
+               %status.attrib;
+               %common.attrib;
+               %refsect1.role.attrib;
+               %local.refsect1.attrib;
+>
+
+<!ELEMENT refexception (refexceptioninfo?, (%refcomponent.mix;)+)>
+<!ATTLIST refexception
+               %status.attrib;
+               %common.attrib;
+               %refsect1.role.attrib;
+               %local.refsect1.attrib;
+>
+
+<!ELEMENT refthrows (refthrowsinfo?, (%refcomponent.mix;)+)>
+<!ATTLIST refthrows
+               %status.attrib;
+               %common.attrib;
+               %refsect1.role.attrib;
+               %local.refsect1.attrib;
+>
+
+<!ELEMENT refsee (refseeinfo?, (%refcomponent.mix;)+)>
+<!ATTLIST refsee
+               %status.attrib;
+               %common.attrib;
+               %refsect1.role.attrib;
+               %local.refsect1.attrib;
+>
+
+<!ELEMENT refsince (refsinceinfo?, (%refcomponent.mix;)+)>
+<!ATTLIST refsince
+               %status.attrib;
+               %common.attrib;
+               %refsect1.role.attrib;
+               %local.refsect1.attrib;
+>
+
+<!ELEMENT refserial (refserialinfo?, (%refcomponent.mix;)+)>
+<!ATTLIST refserial
+               %status.attrib;
+               %common.attrib;
+               %refsect1.role.attrib;
+               %local.refsect1.attrib;
+>
+
+<!ELEMENT refdeprecated (refdeprecatedinfo?, (%refcomponent.mix;)+)>
+<!ATTLIST refdeprecated
+               %status.attrib;
+               %common.attrib;
+               %refsect1.role.attrib;
+               %local.refsect1.attrib;
+>
+
+
+<!ELEMENT refdescriptioninfo (%refinfo.mix;)>
+<!ATTLIST refdescriptioninfo
+       %common.attrib;
+       role    CDATA   #IMPLIED
+>
+
+<!ELEMENT refauthorinfo (%refinfo.mix;)>
+<!ATTLIST refauthorinfo
+       %common.attrib;
+       role    CDATA   #IMPLIED
+>
+
+<!ELEMENT refversioninfo (%refinfo.mix;)>
+<!ATTLIST refversioninfo
+       %common.attrib;
+       role    CDATA   #IMPLIED
+>
+
+<!ELEMENT refparameterinfo (%refinfo.mix;)>
+<!ATTLIST refparameterinfo
+       %common.attrib;
+       role    CDATA   #IMPLIED
+>
+
+<!ELEMENT refreturninfo (%refinfo.mix;)>
+<!ATTLIST refreturninfo
+       %common.attrib;
+       role    CDATA   #IMPLIED
+>
+
+<!ELEMENT refexceptioninfo (%refinfo.mix;)>
+<!ATTLIST refexceptioninfo
+       %common.attrib;
+       role    CDATA   #IMPLIED
+>
+
+<!ELEMENT refthrowsinfo (%refinfo.mix;)>
+<!ATTLIST refthrowsinfo
+       %common.attrib;
+       role    CDATA   #IMPLIED
+>
+
+<!ELEMENT refseeinfo (%refinfo.mix;)>
+<!ATTLIST refseeinfo
+       %common.attrib;
+       role    CDATA   #IMPLIED
+>
+
+<!ELEMENT refsinceinfo (%refinfo.mix;)>
+<!ATTLIST refsinceinfo
+       %common.attrib;
+       role    CDATA   #IMPLIED
+>
+
+<!ELEMENT refserialinfo (%refinfo.mix;)>
+<!ATTLIST refserialinfo
+       %common.attrib;
+       role    CDATA   #IMPLIED
+>
+
+<!ELEMENT refdeprecatedinfo (%refinfo.mix;)>
+<!ATTLIST refdeprecatedinfo
+       %common.attrib;
+       role    CDATA   #IMPLIED
+>