OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.

 


Help: OASIS Mailing Lists Help | MarkMail Help

docbook message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [Elist Home]


Subject: DOCBOOK: Reference markup for Java interfaces


Hi all!

I have question about how to mark up a reference of Java
interfaces. Perhaps you can enlighten me some :-)

We want to document Java interfaces that look like

public interface XMLProducer {
  /** Set the <code>XMLConsumer</code> that will receive XML data. */
  public void setConsumer(XMLConsumer consumer);
}

Now I wanted to mark these up properly in Docbook (4.1.2 XML) and
create a interface reference. What I ended up with after studying TDG
(paper and online) for hours was the following: 

  <reference>
    <title>Sitemap interface reference</title>
    <refentry id="whatever"><!-- FIXME -->
      <refnamediv>
	<refname>XMLProducer</refname>
	<refpurpose>produces <acronym>XML</acronym> data</refpurpose>
      </refnamediv>
      <refsynopsisdiv>
	<classsynopsis class="interface" language="java">
	  <ooclass>
	    <classname>MyProducer</classname>
	  </ooclass>
	  <oointerface>
	    <interfacename>XMLProducer</interfacename>
	  </oointerface>
	  <methodsynopsis>
	    <modifier>public</modifier>
	    <void/>
	    <methodname>setConsumer</methodname>
	    <methodparam rep="norepeat" choice="req">
	      <type>XMLConsumer</type>
	      <parameter moreinfo="none">consumer</parameter>
	    </methodparam>
	  </methodsynopsis>
	</classsynopsis>
      </refsynopsisdiv>
      <refsect1>
	<title>Description</title>
	<para>
          This interfaces identifies classes that produce 
          ...
          which the <acronym>XML</acronym> data production is started.
        </para>
      </refsect1>
    </refentry>
  </reference>

But then I got some doubts and resulting questions:

1. Do I use <classsynopsis> correctly?

2. Is a <classsynopsis> within the <refsynopsisdiv> really what I
   want?

3. How can I markup more information about the methods of the
   interface (what it does, what the params mean, etc.)?

The only alternative I can think of would be using a reference
<chapter> with a <section> for each interface and a sub <section> for
each method where all <section>s adhere to some still-to-be-defined
markup standards. But this is not what I understand Docbook is
about. There must be a way to completely describe a Java interface in
Docbook. 

Thanks a lot for any hint.

Uli


[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [Elist Home]


Powered by eList eXpress LLC