DOCBOOK: packagename proposal/RFE

[Elliotte Rusty Harold <elharo at metalab dot unc dot edu>]

Here's an initial proposal for a new packagename element. As I recall, 
Norm prefers these to be posted here and to put them in SourceForge 
himself. If that's incorrect, just let me know where you'd like me to 
send this. Please note the open issues for discussion at the end.

Currently when referrring to Java package names such as
org.xml.sax or java.lang.reflect in DocBook documents it is
necessary to mark them up as literals because there is no more
specific construct which matches them. That is, they are not
classnames, vars, types, methodnames, exceptionnames, ooclasses,
oointerfaces, or any of the other constructs DocBook provides
for programming language markup.

I suggest adding a <packagename> to do this:

<para>
The <packagename>org.xml.sax</packagename> is the key
package in SAX.
</para>

This would also be useful in classsynopsis:

<classsynopsis language="Java">
  <packagename>org.xml.sax</packagename>
  <oointerface>
    <modifier>public</modifier>
    <interfacename>XMLReader</interfacename>
  </oointerface>
</classsynopsis>

I propose:

1.    Add a packagename element that has the same content
and attributes as classname:

<!ENTITY % packagename.module "INCLUDE">
<![%packagename.module;[
<!ENTITY % local.packagename.attrib "">
<!ENTITY % packagename.role.attrib "%role.attrib;">

<!ENTITY % packagename.element "INCLUDE">
<![%packagename.element;[
<!ELEMENT packagename (%smallcptr.char.mix;)*>
<!--end of packagename.element-->]]>

<!ENTITY % packagename.attlist "INCLUDE">
<![%classname.attlist;[
<!ATTLIST packagename
        %common.attrib;
        %packagename.role.attrib;
        %local.packagename.attrib;
 >
<!--end of packagename.attlist-->]]>
<!--end of packagename.module-->]]>


2.    Add packagename (or whatever it's called) to tech.char.class:

<!ENTITY % tech.char.class
        "action|application
                |classname|methodname|interfacename|exceptionname
                |ooclass|oointerface|ooexception
                |command|computeroutput
        |database|email|envar|errorcode|errorname|errortype|filename
        |function|guibutton|guiicon|guilabel|guimenu|guimenuitem
        |guisubmenu|hardware|interface|keycap
        |keycode|keycombo|keysym|literal|constant|markup|medialabel
        |menuchoice|mousebutton|option|optional|packagename|parameter
        |prompt|property|replaceable|returnvalue|sgmltag|structfield
        |structname|symbol|systemitem|token|type|userinput|varname
                %ebnf.inline.hook;
        %local.tech.char.class;"
 >
 

3. Add a single initial packagename as an optional child of classsynopsis:

<!ELEMENT classsynopsis (packagename?, (ooclass|oointerface|ooexception)+,
                         (classsynopsisinfo
                          |fieldsynopsis|%method.synop.class;)*)>

                         
Issues for discussion:

1. Is "packagename" the right name for symmetry with classname and
interfacename or should this be simply "package"? Or perhapps
"oopackage" for symmetry with ooclass and oointerface?

2. Is there any need for a package synopsis, either as its own element
 or a kind of classysnopsis?

3. I'm mostly familiar with Java. Is there anything similar in other
language we should address here; e.g. C++ or C# namespaces or Perl
modules? If so, how does this affect the choice of name for this element?
Also, do any of these languages ever put a single class or interface
in more than one package?

-- 
+-----------------------+------------------------+-------------------+
| Elliotte Rusty Harold | elharo@metalab.unc.edu | Writer/Programmer |
+-----------------------+------------------------+-------------------+ 
|           The XML Bible, 2nd Edition (IDG Books, 2001)             |
|             http://www.cafeconleche.org/books/bible2/              |
|   http://www.amazon.com/exec/obidos/ISBN=0764547607/cafeaulaitA/   |
+----------------------------------+---------------------------------+
|  Read Cafe au Lait for Java News:   http://www.cafeaulait.org/     | 
|  Read Cafe con Leche for XML News:  http://www.cafeconleche.org/   |
+----------------------------------+---------------------------------+