docbook: Thread: XML v. SGML entities

Hey DB Gang,

I know just enough DB/SGML/XML jargon to be dangerous so forgive abuses
of vocab.

I'm working on an update to my Docbook Quickstart Guide. I was going to
use XML 4.2 only. None of the SGML dtd's are installed. I've
successfully installed the source to the extent that I can process my
xml into tldp'ized html. But I'm getting some lame-o errors. Allow me to
paste. Note the first line is the bash prompt w/ the command I type.
Please, also note that I tried this with just Norm's style sheets and
got the same errors.

------------------------------------------------------------------------
-------
jim@styx:~/dbxmlqs$ openjade -t xml -d
/home/jim/sgml/dsssl/html/ldp.dsl#html
/home/jim/sgml/dsssl/dtds/decls/xml.dcl dbxmlqs.xml     
openjade:/home/jim/sgml/dsssl/html/../common/../common/dbl1no.dsl:2:66:W
: cannot generate system identifier for public text "ISO
8879:1986//ENTITIES Added Latin 1//EN"
openjade:/home/jim/sgml/dsssl/html/../common/../common/dbl1no.dsl:3:5:E:
reference to entity "lat1" for which no system identifier could be
generated
openjade:/home/jim/sgml/dsssl/html/../common/../common/dbl1no.dsl:2:0:
entity was defined here
openjade:/home/jim/sgml/dsssl/html/../common/../common/dbl1ro.dsl:2:66:W
: cannot generate system identifier for public text "ISO
8879:1986//ENTITIES Added Latin 1//EN"
openjade:/home/jim/sgml/dsssl/html/../common/../common/dbl1ro.dsl:3:5:E:
reference to entity "lat1" for which no system identifier could be
generated
openjade:/home/jim/sgml/dsssl/html/../common/../common/dbl1ro.dsl:2:0:
entity was defined here
openjade:/home/jim/sgml/dsssl/html/../common/../common/dbl1ro.dsl:4:66:W
: cannot generate system identifier for public text "ISO
8879:1986//ENTITIES Added Latin 2//EN"
openjade:/home/jim/sgml/dsssl/html/../common/../common/dbl1ro.dsl:5:5:E:
reference to entity "lat2" for which no system identifier could be
generated
openjade:/home/jim/sgml/dsssl/html/../common/../common/dbl1ro.dsl:4:0:
entity was defined here
openjade:/home/jim/sgml/dsssl/html/../common/../common/dbl1ru.dsl:2:69:W
: cannot generate system identifier for public text "ISO
8879:1986//ENTITIES Russian Cyrillic//EN"
openjade:/home/jim/sgml/dsssl/html/../common/../common/dbl1ru.dsl:3:5:E:
reference to entity "cyr1" for which no system identifier could be
generated
openjade:/home/jim/sgml/dsssl/html/../common/../common/dbl1ru.dsl:2:0:
entity was defined here
openjade:/home/jim/sgml/dsssl/html/../common/../common/dbl1sl.dsl:2:66:W
: cannot generate system identifier for public text "ISO
8879:1986//ENTITIES Added Latin 2//EN"
openjade:/home/jim/sgml/dsssl/html/../common/../common/dbl1sl.dsl:3:5:E:
reference to entity "lat2" for which no system identifier could be
generated
openjade:/home/jim/sgml/dsssl/html/../common/../common/dbl1sl.dsl:2:0:
entity was defined here
openjade:/home/jim/sgml/dsssl/html/../common/../common/dbl1sr.dsl:2:66:W
: cannot generate system identifier for public text "ISO
8879:1986//ENTITIES Added Latin 2//EN"
openjade:/home/jim/sgml/dsssl/html/../common/../common/dbl1sr.dsl:3:5:E:
reference to entity "lat2" for which no system identifier could be
generated
openjade:/home/jim/sgml/dsssl/html/../common/../common/dbl1sr.dsl:2:0:
entity was defined here
------------------------------------------------------------------------
-------


Here's what I've installed

openjade-1.3.1 in /home/jim/sgml/openjade-1.3.1
docbook-dsssl-1.77 in /home/jim/sgml/dsssl
docbook-xml-4.2 in /home/jim/sgml/docbook/4.2xml (hooray comes with
entities!)

Here's my catalog setup

$SGML_CATALOG_FILES=/home/jim/sgml/catalog

where /home/jim/sgml/catalog is
-------------------------------------------------------------------
CATALOG "/home/jim/sgml/openjade-1.3.1/dsssl/catalog"
CATALOG "/home/jim/sgml/dsssl/catalog"
CATALOG "/home/jim/sgml/docbook/4.2xml/catalog"
SYSTEM "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
"docbook/4.2xml/docbookx.dtd"
-------------------------------------------------------------------
(the catalog files are sym links to the .cat files)

The first couple of errors it's complaining about "ISO
8879:1986//ENTITIES Added Latin 1//EN" and "ISO 8879:1986//ENTITIES
Added Latin 2//EN" not being defined. Which they aren't! If we examine
/home/jim/sgml/docbook/4.2xml/docbook.cat we can note that the only
latin 1 & 2 public identifiers are on lines 64 & 67 and look like this

docbook.cat lines 64-78
------------------------------------------------------------------------
-----------
PUBLIC "ISO 8879:1986//ENTITIES Added Latin 1//EN//XML"
       "ent/iso-lat1.ent"

PUBLIC "ISO 8879:1986//ENTITIES Added Latin 2//EN//XML"
       "ent/iso-lat2.ent"
------------------------------------------------------------------------
-----------

Notice the XML after EN. So these identifiers don't match the ones with
the style sheets (dbl1no.dsl, dbl1ro.dsl, dbl1sl.dsl, and dbl1sr.dsl).
The cyrillic public identifier suffers from the same problem. 

Now I'm a good sort of sport. So, I tried to fix the identifiers in
those .dsl files to include the XML part (even though I could have done
it with catalog magic). That would at least make them point correctly
right? Right! But now I get a new set of errors.


a BOATLOAD of these errors
------------------------------------------------------------------------
----------
... snip ...
openjade:/home/jim/sgml/docbook/4.2xml/ent/iso-lat1.ent:7:19:E: "X00C1"
is not a function name
openjade:/home/jim/sgml/docbook/4.2xml/ent/iso-lat1.ent:8:18:E: "X00E2"
is not a function name
openjade:/home/jim/sgml/docbook/4.2xml/ent/iso-lat1.ent:9:18:E: "X00C2"
is not a function name
... snip ...
------------------------------------------------------------------------
----------

This discourse from Norm at
http://sources.redhat.com/ml/docbook-apps/2000-q4/msg00246.html helps
explain that problem some. So I need to use a specific set of entities
when I'm processing XML. According to the word from Norm, that's the
*.ent files that come with the docbook-xml distro. But if I understand
things. That's what I've got. I have some style files that trace the
following path

(my modified dbl1no.dsl)
<!ENTITY % lat1 PUBLIC "ISO 8879:1986//ENTITIES Added Latin 1//EN//XML">

(from 4.2xml/docbook.cat)
PUBLIC "ISO 8879:1986//ENTITIES Added Latin 1//EN//XML"
       "ent/iso-lat1.ent"


So that lat1 ultimately points to
/home/jim/sgml/docbook/4.2xml/ent/iso-lat1.ent right? The *.ent files
are what I'm supposed to be using for XML right? What am I missing here
if I'm going for XML only?

Thanks,
Jim Weller

NEVER POST WITH OUTLOOK!



Hey DB Gang,

I know just enough DB/SGML/XML jargon to be dangerous so forgive abuses 
of vocab.

I'm working on an update to my Docbook Quickstart Guide. I was going to 
use XML 4.2 only. None of the SGML dtd's are installed. I've 
successfully installed the source to the extent that I can process my 
xml into tldp'ized html. But I'm getting some lame-o errors. Allow me 
to paste. Note the first line is the bash prompt w/ the command I type. 
Please, also note that I tried this with just Norm's style sheets and 
got the same errors.

------------------------------------------------------------------------
-------
jim@styx:~/dbxmlqs$ openjade -t xml -
d /home/jim/sgml/dsssl/html/ldp.dsl#html /home/jim/sgml/dsssl/dtds/decls
/xml.dcl dbxmlqs.xml     
openjade:/home/jim/sgml/dsssl/html/../common/../common/dbl1no.dsl:2:66:W
: cannot generate system identifier for public text "ISO 
8879:1986//ENTITIES Added Latin 1//EN"
openjade:/home/jim/sgml/dsssl/html/../common/../common/dbl1no.dsl:3:5:E:
 reference to entity "lat1" for which no system identifier could be 
generated
openjade:/home/jim/sgml/dsssl/html/../common/../common/dbl1no.dsl:2:0: 
entity was defined here
openjade:/home/jim/sgml/dsssl/html/../common/../common/dbl1ro.dsl:2:66:W
: cannot generate system identifier for public text "ISO 
8879:1986//ENTITIES Added Latin 1//EN"
openjade:/home/jim/sgml/dsssl/html/../common/../common/dbl1ro.dsl:3:5:E:
 reference to entity "lat1" for which no system identifier could be 
generated
openjade:/home/jim/sgml/dsssl/html/../common/../common/dbl1ro.dsl:2:0: 
entity was defined here
openjade:/home/jim/sgml/dsssl/html/../common/../common/dbl1ro.dsl:4:66:W
: cannot generate system identifier for public text "ISO 
8879:1986//ENTITIES Added Latin 2//EN"
openjade:/home/jim/sgml/dsssl/html/../common/../common/dbl1ro.dsl:5:5:E:
 reference to entity "lat2" for which no system identifier could be 
generated
openjade:/home/jim/sgml/dsssl/html/../common/../common/dbl1ro.dsl:4:0: 
entity was defined here
openjade:/home/jim/sgml/dsssl/html/../common/../common/dbl1ru.dsl:2:69:W
: cannot generate system identifier for public text "ISO 
8879:1986//ENTITIES Russian Cyrillic//EN"
openjade:/home/jim/sgml/dsssl/html/../common/../common/dbl1ru.dsl:3:5:E:
 reference to entity "cyr1" for which no system identifier could be 
generated
openjade:/home/jim/sgml/dsssl/html/../common/../common/dbl1ru.dsl:2:0: 
entity was defined here
openjade:/home/jim/sgml/dsssl/html/../common/../common/dbl1sl.dsl:2:66:W
: cannot generate system identifier for public text "ISO 
8879:1986//ENTITIES Added Latin 2//EN"
openjade:/home/jim/sgml/dsssl/html/../common/../common/dbl1sl.dsl:3:5:E:
 reference to entity "lat2" for which no system identifier could be 
generated
openjade:/home/jim/sgml/dsssl/html/../common/../common/dbl1sl.dsl:2:0: 
entity was defined here
openjade:/home/jim/sgml/dsssl/html/../common/../common/dbl1sr.dsl:2:66:W
: cannot generate system identifier for public text "ISO 
8879:1986//ENTITIES Added Latin 2//EN"
openjade:/home/jim/sgml/dsssl/html/../common/../common/dbl1sr.dsl:3:5:E:
 reference to entity "lat2" for which no system identifier could be 
generated
openjade:/home/jim/sgml/dsssl/html/../common/../common/dbl1sr.dsl:2:0: 
entity was defined here
------------------------------------------------------------------------
-------


Here's what I've installed

openjade-1.3.1 in /home/jim/sgml/openjade-1.3.1
docbook-dsssl-1.77 in /home/jim/sgml/dsssl
docbook-xml-4.2 in /home/jim/sgml/docbook/4.2xml (hooray comes with 
entities!)

Here's my catalog setup

$SGML_CATALOG_FILES=/home/jim/sgml/catalog

where /home/jim/sgml/catalog is
-------------------------------------------------------------------
CATALOG "/home/jim/sgml/openjade-1.3.1/dsssl/catalog"
CATALOG "/home/jim/sgml/dsssl/catalog"
CATALOG "/home/jim/sgml/docbook/4.2xml/catalog"
SYSTEM "http://www.oasis-
open.org/docbook/xml/4.2/docbookx.dtd" "docbook/4.2xml/docbookx.dtd"
-------------------------------------------------------------------
(the catalog files are sym links to the .cat files)

The first couple of errors it's complaining about "ISO 
8879:1986//ENTITIES Added Latin 1//EN" and "ISO 8879:1986//ENTITIES 
Added Latin 2//EN" not being defined. Which they aren't! If we 
examine /home/jim/sgml/docbook/4.2xml/docbook.cat we can note that the 
only latin 1 & 2 public identifiers are on lines 64 & 67 and look like 
this

docbook.cat lines 64-78
------------------------------------------------------------------------
-----------
PUBLIC "ISO 8879:1986//ENTITIES Added Latin 1//EN//XML"
       "ent/iso-lat1.ent"

PUBLIC "ISO 8879:1986//ENTITIES Added Latin 2//EN//XML"
       "ent/iso-lat2.ent"
------------------------------------------------------------------------
-----------

Notice the XML after EN. So these identifiers don't match the ones with 
the style sheets (dbl1no.dsl, dbl1ro.dsl, dbl1sl.dsl, and dbl1sr.dsl). 
The cyrillic public identifier suffers from the same problem. 

Now I'm a good sort of sport. So, I tried to fix the identifiers in 
those .dsl files to include the XML part (even though I could have done 
it with catalog magic). That would at least make them point correctly 
right? Right! But now I get a new set of errors.


a BOATLOAD of these errors
------------------------------------------------------------------------
----------
... snip ...
openjade:/home/jim/sgml/docbook/4.2xml/ent/iso-lat1.ent:7:19:E: "X00C1" 
is not a function name
openjade:/home/jim/sgml/docbook/4.2xml/ent/iso-lat1.ent:8:18:E: "X00E2" 
is not a function name
openjade:/home/jim/sgml/docbook/4.2xml/ent/iso-lat1.ent:9:18:E: "X00C2" 
is not a function name
... snip ...
------------------------------------------------------------------------
----------

This discourse from Norm at http://sources.redhat.com/ml/docbook-
apps/2000-q4/msg00246.html helps explain that problem some. So I need 
to use a specific set of entities when I'm processing XML. According to 
the word from Norm, that's the *.ent files that come with the docbook-
xml distro. But if I understand things. That's what I've got. I have 
some style files that trace the following path

(my modified dbl1no.dsl)
<!ENTITY % lat1 PUBLIC "ISO 8879:1986//ENTITIES Added Latin 1//EN//XML">

(from 4.2xml/docbook.cat)
PUBLIC "ISO 8879:1986//ENTITIES Added Latin 1//EN//XML"
       "ent/iso-lat1.ent"


So that lat1 ultimately points to /home/jim/sgml/docbook/4.2xml/ent/iso-
lat1.ent right? The *.ent files are what I'm supposed to be using for 
XML right? What am I missing here if I'm going for XML only?

Thanks,
Jim Weller

> openjade:/home/jim/sgml/docbook/4.2xml/ent/iso-lat1.ent:9:18:E: "X00C2"
> is not a function name


  I solved this by installing the .gml entity files and
  adjusting my catalog file accordingly.  Took me a while
  to find the solution. I also now have 4.2 DocBook XML
  building cleanly (with all proper entities) - error and
  warning free...

  Grab the DTD package, which includes my adjustments and give it
  a try:  http://ibiblio.org/gferg/ldp/docbook-xml-4.2-dtd.tar.gz

regards,

-- 
Greg Ferguson    * SGI principal engr / LDP contributor
SGI Tech Pubs    * http://techpubs.sgi.com/ | gferg(at)sgi.com
Linux Doc Project* http://tldp.org/         | gferg(at)metalab.unc.edu

Greg,
As always thanks for the prompt and pertinent reply.

I grabbed your distro and took a look, but I'm also trying to understand
the workings here. I notice that you put the ISO* entity files in the
same folder as the DTD and the *.gml files in the ents/ sub folder.
Where are those referenced by catalogs? I notice that dbcentx.mod has
matching "ISO*.module" type lines does that cover the ISO* files? But
where are the *.gml files mentioned?

OK. Looking closer it looks like you build a custom catalog (catalog)
that is different from docbook.cat to reference the *.gml files. What is
your SGML_CATALOG_FILES? Do you use both docbook.cat and catalog? If so
I would think that you don't have an XML only setup, but that you are
using SGML & XML entities.

I'll play with some more permutations and report back. 

Jim


-----Original Message-----
From: Greg Ferguson ####@####.#### 
Sent: Tuesday, November 12, 2002 6:04 AM
To: James Weller; ####@####.####
Subject: Re: XML v. SGML entities


> openjade:/home/jim/sgml/docbook/4.2xml/ent/iso-lat1.ent:9:18:E: 
> "X00C2" is not a function name


  I solved this by installing the .gml entity files and
  adjusting my catalog file accordingly.  Took me a while
  to find the solution. I also now have 4.2 DocBook XML
  building cleanly (with all proper entities) - error and
  warning free...

  Grab the DTD package, which includes my adjustments and give it
  a try:  http://ibiblio.org/gferg/ldp/docbook-xml-4.2-dtd.tar.gz

regards,

-- 
Greg Ferguson    * SGI principal engr / LDP contributor
SGI Tech Pubs    * http://techpubs.sgi.com/ | gferg(at)sgi.com
Linux Doc Project* http://tldp.org/         | gferg(at)metalab.unc.edu

On Nov 12,  7:58am, Jim Weller wrote:
> Subject: RE: XML v. SGML entities
> Greg,
> As always thanks for the prompt and pertinent reply.
>
> I grabbed your distro and took a look, but I'm also trying to understand
> the workings here. I notice that you put the ISO* entity files in the
> same folder as the DTD and the *.gml files in the ents/ sub folder.
> Where are those referenced by catalogs? I notice that dbcentx.mod has
> matching "ISO*.module" type lines does that cover the ISO* files? But
> where are the *.gml files mentioned?

They aren't mentioned. This was discovered while I was trying to find
a solution for the "is not a function name" XML entity problem.

Also, some of the entity-related files in the DTD directory (and
perhaps in the ents directory) might be "cruft". I never bothered to
clean everything up (sorry about that!). I wanted to get to the
solution...!

> OK. Looking closer it looks like you build a custom catalog (catalog)
> that is different from docbook.cat to reference the *.gml files.

Correct.

> What is your SGML_CATALOG_FILES? Do you use both docbook.cat and
> catalog?

No, both are not needed. I point SGML_CATALOG_FILES at 'catalog'
(my modified version) and the jade dsssl 'catalog'.

If you wish to see how this is setup for the LDP (the document
publishing script), grab the following:

http://tldp.org/authors/tools/ldp_mk

With this script I can publish all (LDP) supported DTDs (XML or SGML).
Email w/any questions.

regards-



-- 
Greg Ferguson    * SGI principal engr / LDP contributor
SGI Tech Pubs    * http://techpubs.sgi.com/ | gferg(at)sgi.com
Linux Doc Project* http://tldp.org/         | gferg(at)metalab.unc.edu

Gang,
Good lord this is reverse engineering of the worst kind. I feel
enlightened, much like Socrates' people chained to the cave wall
watching shadows of reality dancing must have felt when they saw the
real world. And I wrote a bloody howto on and using these tools!

I have got three collections of entitity files. 

ISO* (ISO)
*.gml (gml)
*.ent (ent)

The parens tell how I will reference them.

There are 21 of each and 62 entities in the latin 1 file. I'm using the
latin-1 file as my basis for comparison. They are all describing the
same thing; lists of special characters/entities. The ISOs and gmls are
the same file line for line. 

That leaves us with 2 sets; the ents & ISO/gml (gmls). 

The ISO/gml files have lots of "<!ENTITY aacute SDATA "[aacute]"--=small
a, acute accent-->" type defintions with SDATAs. The gml group is the
one we all spend lots of time hand crafting catalogs and file names for.
They are the SDATA sgml type that Norm references in the url I posted
earlier. That's the data type expected by the command that I've
traditionally used to compile docbook xml (e.g. openjade -t xml -d
ldp.dsl#html xml.dcl howto.xml ).

But the ent files are HEX "<!ENTITY aacute	"&#x00E1;"> <!-- LATIN
SMALL LETTER A WITH ACUTE -->" type definitions.  These are the normal
files that are referenced in and distribuited with the docbook.cat
catalog file.

So, to clarify. The docbook distribution's catalog file points to a
series of *.ent files in the ent directory to define glyphs/entities.
Those entities by default are are in &#xHEX format. Openjade expects
that hex to be a function name (SDATA). So openjade freaks and prints
all those errors. Does jade do this?

I'd like to see this "fixed" such that either openjade handles the
&#xHEX references correctly or docbook catalog points to SDATA entity
definitions.

The obvious work arounds are 
1. Write a custom catalog that points to the correct entity files. See
Greg's docbook distro mentioned in his reply.(Thanks Greg!).
2. Replace the *.ent files with the *.gml file distro but changing the
.ent ending to .gml. The name change is because that's file extension
the docbook.cat from the docbook distro expects. Tested this. It works.

I've also recently tried using the xsl stylesheets with xsltproc. It
definetely gave me output, but in one (ugly) html file. I think the
dsssl style sheet transformation was more elegant and navigable. I've of
course heard that there is chunky xsl sheet out there somewhere. I'll
look into that.

I think I've got it down to openjade, docbook-dsssl, ldp-dsssl,
docbook-dtd, and the SDATA entities (renamed or cataloged). That even
feels excessive. I should just be able to use the entities that come
with the dtd. I'm really just interested in the simplest light-weight
processing environment possible. I mean as an author I just care about
my markup being correct and complete. I'm assuming that there are a
bug-a-jillion people out there that can process my original content
their particular way.

Thoughts?
Jim

-----Original Message-----
From: Greg Ferguson ####@####.#### 
Sent: Tuesday, November 12, 2002 8:03 AM
To: Jim Weller; ####@####.####
Subject: Re: XML v. SGML entities


On Nov 12,  7:58am, Jim Weller wrote:
> Subject: RE: XML v. SGML entities
> Greg,
> As always thanks for the prompt and pertinent reply.
>
> I grabbed your distro and took a look, but I'm also trying to 
> understand the workings here. I notice that you put the ISO* entity 
> files in the same folder as the DTD and the *.gml files in the ents/ 
> sub folder. Where are those referenced by catalogs? I notice that 
> dbcentx.mod has matching "ISO*.module" type lines does that cover the 
> ISO* files? But where are the *.gml files mentioned?

They aren't mentioned. This was discovered while I was trying to find a
solution for the "is not a function name" XML entity problem.

Also, some of the entity-related files in the DTD directory (and perhaps
in the ents directory) might be "cruft". I never bothered to clean
everything up (sorry about that!). I wanted to get to the solution...!

> OK. Looking closer it looks like you build a custom catalog (catalog) 
> that is different from docbook.cat to reference the *.gml files.

Correct.

> What is your SGML_CATALOG_FILES? Do you use both docbook.cat and 
> catalog?

No, both are not needed. I point SGML_CATALOG_FILES at 'catalog' (my
modified version) and the jade dsssl 'catalog'.

If you wish to see how this is setup for the LDP (the document
publishing script), grab the following:

http://tldp.org/authors/tools/ldp_mk

With this script I can publish all (LDP) supported DTDs (XML or SGML).
Email w/any questions.

regards-



-- 
Greg Ferguson    * SGI principal engr / LDP contributor
SGI Tech Pubs    * http://techpubs.sgi.com/ | gferg(at)sgi.com
Linux Doc Project* http://tldp.org/         | gferg(at)metalab.unc.edu

______________________
http://lists.tldp.org/

On Nov 12,  9:02pm, Jim Weller wrote:
> Subject: RE: XML v. SGML entities
> ...
> I've also recently tried using the xsl stylesheets with xsltproc. It
> definetely gave me output, but in one (ugly) html file. I think the
> dsssl style sheet transformation was more elegant and navigable. I've of
> course heard that there is chunky xsl sheet out there somewhere. I'll
> look into that.

Look no further...

We have XSL stylesheets that give ldp.dsl-type output (and provide
for chunking).  Check the "Resources" area:
http://tldp.org/authors/#resources

  http://www.tldp.org/authors/tools/ldp-xsl.zip

Thanks to Dan York for putting them together :-)

--
regards,
Ferg