[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [Elist Home]
Subject: DOCBOOK: packagename proposal/RFE
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/ | +----------------------------------+---------------------------------+
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [Elist Home]
Powered by eList eXpress LLC