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

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

Hi David,
I too use cygwin on Windows, and frequently run into issues about how to specify a 
full path.  Generally I solve the problem by specifying a URI instead, as most XML 
software accepts a URI.  On a Windows box, that would be:

file:///c:/my/path/on/windows

Bob Stayton
Sagehill Enterprises
bobs@sagehill.net


----- Original Message ----- 
From: "David Goss" <dgoss@mueller-inc.com>
To: "Bob Stayton" <bobs@sagehill.net>; <docbook-apps@lists.oasis-open.org>
Sent: Monday, March 19, 2012 6:04 AM
Subject: RE: [docbook-apps] xsltproc, glossary.collection, and xinclude - glossary is 
not found


Bob,

Thank you very much for the information! I could see that it was taking
the path relative to the included files, but ../glossary.docbook still
results in the file not being found (same problem with the full path--I
blame path issues on using cygwin). Setting glossterm.auto.link to 0,
however, builds the HTML successfully, though albeit without links.

-----Original Message-----
From: Bob Stayton [mailto:bobs@sagehill.net]
Sent: Saturday, March 17, 2012 5:11 PM
To: David Goss; docbook-apps@lists.oasis-open.org
Subject: Re: [docbook-apps] xsltproc, glossary.collection, and xinclude
- glossary is not found

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#GlossaryCatalogEnt
ry

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