cocoon-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Bernhard Huber <berni_hu...@a1.net>
Subject Re: Javadocs: need basic package information
Date Wed, 25 Dec 2002 09:12:43 GMT
hi,
<snip/>
> 
>>* add a packages.dtd ala faq.dtd
> 
> 
> Yes, it is good to constrain the content.
> How much constraint is suitable? Perhaps faq.dtd
> is too loose, e.g. it allows <table> ...
> On the other hand, perhaps we should not try to
> pre-determine the content model. 
> 
Hmm, i think we should reuse as much document-v10.dtd
as possible to keep the docs structure coherent.

Moreover I think packages.xml should reside in the xdocs/developing
directory of cocoon documentation.

* package.dtd suggestion:

<!-- augment standard header with local header elements names
   since : add Cocoon XX.YY version info here
-->
<!ENTITY % local.headers ", since">

<!ENTITY % document-dtd SYSTEM "document-v10.dtd">
%document-dtd;


<!-- =============================================================== -->
<!-- Document Type Definition -->
<!-- =============================================================== -->

<!ELEMENT packages (authors?, package)+>
<!ATTLIST
   packages %common.att;
 >

<!ELEMENT package (header, description, appendices?)>
<!ATTLIST package
   %name.att;
   %common.att;
 >

<!ELEMENT since (#PCDATA)>

<!ELEMENT description (anchor|figure| %blocks;)+>
<!ATTLIST description %common.att;>

<!ELEMENT appendices (%sections;)+>
<!ATTLIST appendices %common.att;>


* package.xml sample :
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE packages PUBLIC "-//APACHE//DTD PACKAGE V1.0//EN" 
"../dtd/package-v10.dtd">

<packages>
   <package name="org.apache.cocoon">
     <header>
       <title>Provides interfaces, classes, and exceptions of Cocoon's
         processor.
       </title>
       <version>0.1</version>
       <type>API documentation</type>
       <authors>
         <person name="Bernhard Huber" email="huber@apache.org"/>
       </authors>
       <since>Cocoon 2.0"</since>
     </header>

     <description>
       <p>
         The Cocoon processor is the top-level controller of the Cocoon
         system.
         The interface Processor defines the basic contract of the Cocoon
         processor.
         The class Cocoon implements the Processor interface.
       </p>
       <p>
         The Cocoon processor is an Avalon component, processing an
         Environment object.
         The Environment is created in a concrete runtime environment,
         like
         Servlet environment, and Commandline environment.
       </p>
     </description>
     <appendices>
       <s1 title="Specification">
         <p></p>
       </s1>
       <s1 title="See Also">
         <p></p>
       </s1>
     </appendices>
   </package>
   <!-- more packages -->
</packages>

> 
> I am not sure what you mean by "specs documents", and i have
> never understood what this DTD was intended for.
well, writting specs for sitemap components, et al.

bye bernhard


---------------------------------------------------------------------
To unsubscribe, e-mail: cocoon-dev-unsubscribe@xml.apache.org
For additional commands, email: cocoon-dev-help@xml.apache.org


Mime
View raw message