Re: [Cp-tools-discuss] missing data

[Alex Lancaster]

>>>>> "MH" == Mark Howard <address@hidden> writes:

MH> Hi, I've been helping out with the Debian packaging of
MH> gjdoc. Currently, packages which use javadoc either do not go into
MH> the main Debian archive, or have some hideous hack done by the
MH> maintainers so that the javadoc html is included in the upstream
MH> source tarball. The inclusion of gjdoc should hopefully help out.

MH> I have three problems at the moment which I have been unable to
MH> fix:

MH> 1) gjdoc.dtd is missing. This causes warnings when generating the
MH> html.  I can't find it anywhere in classpath CVS 

Hmm.  I believe we never got around to writing a DTD, even though it's
mentioned in gjdocxml2html.sh.  I think that's a placeholder (unless
Julian didn't have a chance to check it into CVS).

Since it's not strictly necessary to do a validating parser for the
XSL transformation result, you could probably give it an empty
gjdoc.dtd DTD file.

By the way, there's a bug in the gjdocxml2html.sh.  The "--catalog"
option is intended to be for SGML catalogs, not XML catalogs, so
SGML_CATALOG_FILES, should never be mixed with XML catalogs.  XML
catalogs are *always* checked by default, so you actually don't need
any option to enable XML catalogs.  

Also there's a limitation in the (undocumented) XML_CATALOG_FILES
variable: it only responds to one file, it doesn't look through all
files in a ":" separated list like SGML_CATALOG_FILES.

["--catalogs" is a badly chosen name for the option, IMHO, since it
always confuses users, since it suggests that it enables *all*
catalogs.  I suggested to Daniel Veillard, libxslt/xsltproc maintainer
that it be changed to --sgmlcatalogs a while ago, but he didn't
implement my suggestion.]

To be consistent you should probably change gjdocxml2html.sh
(nextCatalog, refers to where the main "system" catalog is located,
it's like a #include for catalog files).

Here's an (untested) solution.  Once I've tested it works, I can
update CVS.

# create the initial catalog, include main system catalog
echo "<?xml version="1.0"?><!DOCTYPE catalog PUBLIC "-//OASIS//DTD Entity 
Resolution XML CatalogV1.0//EN" 
"http://www.oasis-open.org/committees/entity/release/1.0/catalog.dtd";><catalog 
xmlns="urn:oasis:names:tc:entity:xmlns:xml:catalog"> <nextCatalog 
catalog="file:///etc/xml/catalog"/></catalog>" > gjdoccatalog.xml

# add the GNU catalogs
xmlcatalog --noout \
           --add "public" \
               "-//GNU//DTD Gjdoc XML V0.1.1//EN" \
               http://www.gnu.org/software/cp-tools/dtd/gjdoc.dtd \
           --add "rewriteSystem" \
               http://www.gnu.org/software/cp-tools/dtd/ \
               file:///usr/local/share/gjdoc/dtd/ \
           gjdoccatalog.xml 

# Add the local catalog to the catalog search path

export XML_CATALOG_FILES="gjdoccatalog.xml"

# Start the xslt process

xsltproc \
    --param verbose "1" \
    --param now "'`date`'" \
    --param copyrightfile "'../classpath-copyright.xml'" \
    --param windowtitle "'GNU Classpath 0.04'" \
    --param targetdir "'$2'" \
    xslt/gjdocxml2html.xsl \
    $1/index.xml \
    $3 $4 $5 $6 $7 $8 $9

MH> 2) classpath-copyright.xml is missing, also causing lots of
MH> warnings

Again, missing in CVS, not sure what the format should be here, but it
looks to be any valid or well-formed XHTML.  You could try rolling
your own, e.g.:

<p>Copyright &copy; 2002 Free Software Foundation</p>

MH> 3) The output doesn't include comments, only the class/method
MH> names and parameter/return types.  Is this a known problem? How
MH> can I debug this?

Don't know about the status of this, Julian might know.

A.
-- 
  Alex Lancaster | Free Software Developer:  savannah.gnu.org, sourceforge.net