Re: [docbook-apps] olink .db file entity - absolute or relative to what?

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

----- Original Message ----- 
From: <tom.kirkpatrick@virusbtn.com>
To: <docbook-apps@lists.oasis-open.org>
Sent: Thursday, September 15, 2005 9:24 AM
Subject: [docbook-apps] olink .db file entity - absolute or relative to
what?


> I'm trying to familirise myself with the scematics of olinking (without
> actually having a working system to try things out on at the moment). One
> thing I'm not quite sure about is the use of ENTITY declarations to point
> to the location of the targets.db file.
>
> In the example...
> <?xml version="1.0" encoding="utf-8"?>
> <!DOCTYPE targetset SYSTEM
> "file:///tools/docbook-xsl/common/targetdatabase.dtd"
> [ <!ENTITY ugtargets SYSTEM "file:///doc/userguide/target.db">
> <!ENTITY agtargets SYSTEM "file:///doc/adminguide/target.db">
> <!ENTITY reftargets SYSTEM "file:///doc/man/target.db"> ]>
>  <targetset>
>         <targetsetinfo> Description of this target database document,
> which is for the examples in olink doc. </targetsetinfo>
>         <!-- Site map for generating relative paths between documents -->
>         <sitemap>
>                 <dir name="documentation">
>                         <dir name="guides">
>                         <dir name="mailuser">
>                                 <document targetdoc="MailUserGuide"
> baseuri="userguide.html"> &ugtargets; </document>
>                         </dir>
>
>
> where is this target.db file located? is it:
>
> /doc/userguide/target.db
> or
> /[webroot]/doc/userguide/target.db
> or
> /[sitemap-top-level-directory]/doc/userguide/target.db
> ?

You are using absolute path URLs, so they are not relative to anything.  The
processor will always look for the file at /doc/userguide/target.db.  If you
used relative paths (without the file:/// prefix), then it would be taken
relative to the file containing the reference, which is the target database
document.

> Also, I have seen that you can use Xincludes to specify the location
> (which I think I prefer), is there any advantage to one method over the
> other?

A couple of advantages are listed in this reference:

http://www.sagehill.net/docbookxsl/OlinkVariations.html#XincludeOlinkdb

> I have many Docbook books, each containing many Docbook articles (in
> seperate files as I like to be able to use them individually). Would I
> include every single module (books and articles) in the sitemap? and would
> I need to have a seperate target.db file for every single module (books
> and articles) too?

A target.db file is needed for each document that you render, not for each
module.  Olinks are always resolved relative to an actual rendered document,
that is, one that has been assembled and processed into output that someone
can link to.  The sitemap indicates the *output* map, not the location of
the source files.   It is used to form relative paths between documents in
the output tree.

> My archive containes several thousand articles. Is there any way to create
> the sitemap automatically or must it be done by hand?

A shell script could easily generate the sitemap, if it reflects the source
tree, and if it is given a bit more information. You would need some way of
specifying the targetdoc (and baseuri if it has one) attribute for each
document element, as those cannot be derived from the directory structure.
You could by convention use each document's root element as its targetdoc,
but you must make sure each is unique in the database.

Bob Stayton
Sagehill Enterprises
DocBook Consulting
bobs@sagehill.net