Re: [docbook-apps] xsltproc, glossary.collection, and xinclude - glossary is not found

["Bob Stayton" <bobs@sagehill.net>]

Hi David,
It seems the documentation about glossary.collection fails to mention how a relative 
path to the collection file is interpreted. The short answer is:

a.  If you have glossterm.auto.link set to zero, the path is taken as relative to the 
file containing the empty <glossary> element.

b.  If you have glossterm.auto.link set to non-zero, the path is taken as relative to 
the file containing the *first* inline glossterm or firstterm in the document, in 
document order.

In your case, I think you must have glossterm.auto.link set to 1, and the firstterm in 
your xincluded file is the first instance.  So for your particular case, setting the 
param this way should work:

--stringparam glossary.collection ../glossary.docbook


If you want to see why it works this way, read on.

Note that the XSL stylesheet does not know from what directory you issued your 
processing command.  Your shell interpreter resolves the path to only the document and 
stylesheet files, but has no effect on parameter settings.  The XSL processor itself 
does not normally have your location information, and so does not know that 
"doc/docbook.glossary" means relative to CWD.

In the stylesheet, the instruction that opens the glossary collection looks like this:

 <xsl:variable name="collection" select="document($glossary.collection, .)"/>

The first argument of the document() function specifies the file to open, but the 
second argument can specify a base URI that is prepended to the filename.   Here, the 
second argument of the document() function is . which represents the current node in 
the document (not the stylesheet).  In this function, the XSL processor interprets 
that . to mean the base dir for the file containing the current document element.

If the second argument is omitted, then the first argument path is interpreted as 
relative to the stylesheet file.  Since most people keep their collection file with 
the doc files, using . usually makes sense.

So what is the current document element?  In the case where $glossterm.auto.link is 
set to zero, the collection file is not opened until the <glossary role="auto"> 
element is processed.  In that case, the collection path is relative to the file 
containing that empty glossary element.

In the case where $glossterm.auto.link is non-zero, the first instance of an inline 
glossterm or firstterm will trigger opening the collection file.  That's because it 
must have the information from the database to form the link.  Once the collection has 
been opened, the processor keeps it in memory and does not need to open it again.  So 
any subsequent references, and the glossary element itself, will reuse that already 
opened collection.

Obviously this arrangement may not suit everyone.  In your case, the first instance 
happens to be in an Xincluded file in a subdirectory, so the glossary.collection path 
would have to be relative to that subdirectory.  In other cases, you might have a 
collection file shared by documents in many locations, which requires setting the 
glossary.collection parameter according to where the glossary element resides, which 
can be inconvenient.  In such cases, you could specify a full path in the 
glossary.collection param, or you could specify a phony path and reinterpret it with 
an XML catalog file.  See this reference for details on the latter option:

http://www.sagehill.net/docbookxsl/GlossDatabase.html#GlossaryCatalogEntry

Bob Stayton
Sagehill Enterprises
bobs@sagehill.net


----- Original Message ----- 
From: "David Goss" <dgoss@mueller-inc.com>
To: <docbook-apps@lists.oasis-open.org>
Sent: Friday, March 16, 2012 12:14 PM
Subject: [docbook-apps] xsltproc, glossary.collection, and xinclude - glossary is not 
found


Hello, I'm having a bit of a problem using the glossary.collection
parameter with xincluded files. My project directory looks something
like this:

  /
  /doc/glossary.docbook
  /doc/article1.docbook
  /doc/article1/sect1.docbook
  /xsl/stylesheet.xsl

Doc/Article1.docbook contains an xinclude element for
doc/article1/sect1.docbook. At the bottom of doc/article1.docbook is
<glossary role='auto' />; within doc/article1/sect1.docbook I have
<firstterm></firstterm around an entry in glossary.docbook.

Now, I run xsltproc like so from the root directory:

  Xsltproc --xinclude \
     --stringparam glossary.collection doc/glossary.docbook \
     --output article1.html xsl/stylesheet.xsl doc/article1.docbook

And I get the following warnings:
  Warning: failed to load external entity
"doc/article1/doc/glossary.docbook"

And none of the glossary entries are loaded.

For the life of me, I have no idea why "doc/article1" is being prefixed
to the location of the glossary.


DAVID GOSS | Technical Writer
P 1.800.876.9218 x 345 | F 1.800.588.9866
dgoss@mueller-inc.com
http://www.MuellerReports.com


---------------------------------------------------------------------
To unsubscribe, e-mail: docbook-apps-unsubscribe@lists.oasis-open.org
For additional commands, e-mail: docbook-apps-help@lists.oasis-open.org