docbook: Thread: DocBook XML HOWTOs in the LDP collection

Hmm, I decided to expand my DocBook XML processing with Xalan experiments
to include the other HOWTOs in the LDP collection that use DocBook XML
(the XML-RPC HOWTO and the JavaStation HOWTO).

It turns out that both of those HOWTOs are missing the system identifier;
that is, they both declare:

<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
[ ... entities ... ]>

rather than:

<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
          "http://docbook.org/xml/4.1.2/docbookx.dtd"
[ ... entities ... ]>

This causes the Xalan XSLT processor to die a quick death.

Fixing the documents to be XML-compliant isn't quite as easy as adding
the system identifier, though. The XML-RPC HOWTO appears to contain some
funky parameter entity stuff that Xalan again barfs on:

<!ENTITY % GoodStyleSheets "IGNORE">
<![%GoodStyleSheets;[
<!ENTITY legal.notice "
    <legalnotice id='xmlrpc-howto-legal'>&license;</legalnotice>
    ">
<!ENTITY legal.section "">
]]>

(Xalan barfs on the second line, above. I'm not fluent enough in XML to
know the exact ins and outs of entity declarations within the DOCTYPE
declaration, so I'm not sure if that's a limitation of the tool or a
no-no in XML)

The JavaStation HOWTO, in turn declares an external entity that is
not included in its gzip archive:

<!ENTITY gfdl SYSTEM "gfdl.xml">

When it actually attempts to use this entity elsewhere in the document,
Xalan again dies (because I don't happen to have a copy of gfdl.xml
hanging around). This appears to be a case where the doc needs its own
directory in CVS so it can include multiple files, yes?

The reason I bring this up is because I was going to volunteer the LDP
set of DocBook XML docs as representative examples for a gentleman's
parser experiments on comp.text.xml, but thought I should test them out
first. I didn't end up volunteering our documents because only the
DB2-HOWTO works without any editing.

What this suggests to me is one or both of the following:

a. the Jade XML transform is a little too lenient, allowing SGML
   syntax that shouldn't be allowed in XML
b. the Xalan XML transform is buggy, and doesn't allow some XML
   syntax that does comply with the XML 1.0 specs

Anyone more knowledgeable out there care to speculate?

Dan

-- 
Dan Scott

On 21 May 2001 15:48:41 -0400, Dan Scott wrote:
> Hmm, I decided to expand my DocBook XML processing with Xalan experiments
> to include the other HOWTOs in the LDP collection that use DocBook XML
> (the XML-RPC HOWTO and the JavaStation HOWTO).
> 
> It turns out that both of those HOWTOs are missing the system identifier;
> that is, they both declare:
> 
> <!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
> [ ... entities ... ]>
> 
> rather than:
> 
> <!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
>           "http://docbook.org/xml/4.1.2/docbookx.dtd"
> [ ... entities ... ]>

Ugh, yes, the system identifier is required.  You may find that
processing is faster if you keep a copy of the DTD locally, although it
makes that system identifier not sure to work elsewhere...

> This causes the Xalan XSLT processor to die a quick death.
> 
> Fixing the documents to be XML-compliant isn't quite as easy as adding
> the system identifier, though. The XML-RPC HOWTO appears to contain some
> funky parameter entity stuff that Xalan again barfs on:
> 
> <!ENTITY % GoodStyleSheets "IGNORE">
> <![%GoodStyleSheets;[
> <!ENTITY legal.notice "
>     <legalnotice id='xmlrpc-howto-legal'>&license;</legalnotice>
>     ">
> <!ENTITY legal.section "">
> ]]>

If I remember correctly, including marked sections as entities in XML is
a no-no.  Checking with my friendly XML Guru (Either Daniel Veillard or
Liam Quin, depends on who's awake)...

> (Xalan barfs on the second line, above. I'm not fluent enough in XML to
> know the exact ins and outs of entity declarations within the DOCTYPE
> declaration, so I'm not sure if that's a limitation of the tool or a
> no-no in XML)
> 
> The JavaStation HOWTO, in turn declares an external entity that is
> not included in its gzip archive:
> 
> <!ENTITY gfdl SYSTEM "gfdl.xml">
> 
> When it actually attempts to use this entity elsewhere in the document,
> Xalan again dies (because I don't happen to have a copy of gfdl.xml
> hanging around). This appears to be a case where the doc needs its own
> directory in CVS so it can include multiple files, yes?

Possibly.  I strongly suspect that this file is the GNU Free
Documentation License, marked up in Docbook XML.  If this is so, perhaps
there's a way to keep a single copy in CVS, and include it in relavent
docs.  Then again, maybe not.

> The reason I bring this up is because I was going to volunteer the LDP
> set of DocBook XML docs as representative examples for a gentleman's
> parser experiments on comp.text.xml, but thought I should test them out
> first. I didn't end up volunteering our documents because only the
> DB2-HOWTO works without any editing.
> 
> What this suggests to me is one or both of the following:
> 
> a. the Jade XML transform is a little too lenient, allowing SGML
>    syntax that shouldn't be allowed in XML

Jade is JAmes DSSSL Engine.  It's based on top of SP, which is "SGML
Parser".  It doesn't actually contain a parser specific to XML, instead,
it works with XML by providing a specific SGML declaration (xml.dcl, or
something similar).  Since XML is a strict sub-set of SGML, it works,
mostly.  

> b. the Xalan XML transform is buggy, and doesn't allow some XML
>    syntax that does comply with the XML 1.0 specs

Well, that's -probably- the case as well, but the above errors aren't
bugs in Xalan.  If you're playing with XSLT engines, have you tried
libxslt?  Apparently, it's even faster than Microsoft's, and as such,
should completely blow Xalan out of the water.  It works here, when I
provide it a valid DTD.  :)  http://www.xmlsoft.org/  

> Anyone more knowledgeable out there care to speculate?

Perhaps, see above.  No confirmation on the marked sections, but I'll
probably mail again when one of those two responds in about 30 seconds.
:)
	Greg

On May 21, 10:17pm, Gregory Leblanc wrote:
> Subject: Re: DocBook XML HOWTOs in the LDP collection
> On 21 May 2001 15:48:41 -0400, Dan Scott wrote:
> > Hmm, I decided to expand my DocBook XML processing with Xalan
> > experiments to include the other HOWTOs in the LDP collection
> > that use DocBook XML (the XML-RPC HOWTO and the JavaStation HOWTO).
> >
> > It turns out that both of those HOWTOs are missing the system
> > identifier; that is, they both declare:
> >
> > <!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
> > [ ... entities ... ]>
> >
> > rather than:
> >
> > <!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
> >           "http://docbook.org/xml/4.1.2/docbookx.dtd"
> > [ ... entities ... ]>
>
> Ugh, yes, the system identifier is required.  You may find that
> processing is faster if you keep a copy of the DTD locally, although
> it makes that system identifier not sure to work elsewhere...

There's another way to do this that works quite nicely - keeping the
URI-style system identifier in the document, a publisher can
specify "OVERRIDE YES" in a referenced catalog file - this triggers
the use of a local instance.

In fact, Dan (Scott) and I used this in publishing his XML document
as part  of the LDP collection.

--
r,
Ferg

On the XML note. openjade-1.3 does *not* like URLS in the system identifier.

I updated my 'DocBook XML 4.1.2 QuickStart'
(http://www.jimweller.net/jim/dbxmlqs/index.html). You can get the XML
source here (http://www.jimweller.net/jim/dbxmlqs/dbxmlqs.xml).

Jim


----- Original Message -----
From: "Greg Ferguson" ####@####.####
Sent: Tuesday, May 22, 2001 5:51 AM
Subject: Re: DocBook XML HOWTOs in the LDP collection


> On May 21, 10:17pm, Gregory Leblanc wrote:
> > Subject: Re: DocBook XML HOWTOs in the LDP collection
> > On 21 May 2001 15:48:41 -0400, Dan Scott wrote:
> > > Hmm, I decided to expand my DocBook XML processing with Xalan
> > > experiments to include the other HOWTOs in the LDP collection
> > > that use DocBook XML (the XML-RPC HOWTO and the JavaStation HOWTO).
> > >
> > > It turns out that both of those HOWTOs are missing the system
> > > identifier; that is, they both declare:
> > >
> > > <!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
> > > [ ... entities ... ]>
> > >
> > > rather than:
> > >
> > > <!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
> > >           "http://docbook.org/xml/4.1.2/docbookx.dtd"
> > > [ ... entities ... ]>
> >
> > Ugh, yes, the system identifier is required.  You may find that
> > processing is faster if you keep a copy of the DTD locally, although
> > it makes that system identifier not sure to work elsewhere...
>
> There's another way to do this that works quite nicely - keeping the
> URI-style system identifier in the document, a publisher can
> specify "OVERRIDE YES" in a referenced catalog file - this triggers
> the use of a local instance.
>
> In fact, Dan (Scott) and I used this in publishing his XML document
> as part  of the LDP collection.
>
> --
> r,
> Ferg
>
> _________________________
> http://list.linuxdoc.org/
>
>