[docbook-apps] new olink features in XSL 1.66.1

["Bob Stayton" <bobs at sagehill dot net>]

This mail will be of interest mostly to people who are using
olinks, or are thinking of using olinks to create cross references
between DocBook documents.

The olink templates were rewritten in version 1.66 of
the XSL stylesheets.  The goal was to provide more
options for using olinks, and more opportunities
for customizing olinks.   Here is a description of
the changes.  It is a long mail because there were a lot
of changes.

Olinking in FO output
------------------------------
- Now you can use olink to form active hotlinks 
between PDF documents.  In earlier versions the
olink text would resolve, but the links would only
be active if they were to a destination within
the same document.  Now an olink can open another
PDF file, and, under the right circumstances, can scroll
to the exact location in the external document.

- Scrolling to the exact location means that the fragment
identifier that the stylesheet adds to a PDF reference
is resolved:

   myotherbook.pdf#intro

This feature is currently somewhat limited.  Only XEP adds
the correct ID information to the PDF document for it to
work.  Neither FOP nor Antenna House write ihe original ID
values from the XSLT process to the PDF file.  So although
a link with fragment identifier is properly formed, the
ID value it points to does not exist in the PDF.

- Also some browsers don't properly interpret PDF fragment
identifiers.  Adobe Reader seems to work, but Adobe Reader
used as a PDF plugin inside Internet Explorer does not.
Another factor is whether the PDF file is accessed as a local
file or from an HTTP server.  In some cases, the hot link will
open the other PDF file but won't scroll to the exact location.
In other cases, the browser will complain that it
cannot open the other document at all because it is
misinterpreting the fragment identifier as part of the filename.

- Because the fragment identifiers in PDF olinks can
cause such problems, the FO stylesheet turns them off
by default.  You can turn them on if your situation permits
by setting the stylesheet parameter 'insert.olink.pdf.frag'
to 1.

- Since the FO stylesheet now supports olinks, it can also
be used to generate a document's olink data file (whose
default name is 'target.db'). In previous versions you
had to use the HTML stylesheet to generate the data file.

If your customization uses different xref styles in the
two kinds of output, then you will want to maintain
separate data files for HTML and FO output.  Use the
'targets.filename' parameter to change the default data
filename from 'target.db' to something else,

- You will need to create separate master olink database
files (identified by the 'target.database.document' parameter)
for HTML and FO output.  That's because the 'baseuri'
attribute on the <document> element in the database must
be different.
For HTML output, the baseuri would be either the HTML
filename (for nonchunked output), or a directory name
(for chunked output).
For XEP output, the baseuri for local file
access should be "file:myfile.pdf".  For other XSL-FO
processors the baseuri should be just "myfile.pdf".

- It is possible to form olinks between HTML and PDF documents.
In the olink database file (identified by the 'target.database.document'
parameter), an HTML document can have an HTML baseuri, and
a PDF document can have a PDF baseuri.  But you can't do both
formats for one document in the same database because each
'targetdoc' attribute must be unique within each language.

- The olink mechanism includes partial support for page
number references in olinks.  That means you could refer
someone to an actual page number in the other document.
In the olink database, the page number for each target can
be stored in a 'page' attribute on each <div> or <obj>
element.  If an olink style calls for a page number, and if
the data is there, it will be output.  But there is no standard
way of populating the page attribute in the olink data.
Since page numbers are only available in the XSL-FO processor,
some sort of postprocessing would be needed to extract the
page numbers for each element.  The collection of page
numbers is not part of the XSL stylesheets at this time.


Olink resolution
------------------------------
Several new options for resolving olinks were added.

- If you want to point to the top of another document, now
you can omit the 'targetptr' olink attribute.  The stylesheet
will use the 'targetdoc' attribute to locate the data file
for the document, and will use the targetptr of the root
element in the target data to resolve the link.

- In one special circumstance you can now omit the
'targetdoc' attribute from your olinks.  You can do this
only if there is a single document in the olink database.
When is that useful?  When you are using olinks only
within a modular document that is assembled by XInclude.
Using olink instead of xref to form your cross references
within your document permits you to validate each file
module.  When you process the document, the olinks must
have an olink database to resolve such olinks.  If you
aren't using olinks for external cross references, then the
olink database just needs to include the single document.

- Another feature to support modular source files is the
'prefer.internal.olink' stylesheet parameter.  This is
useful when you reuse a content module in more than one
document.  If you cross reference to such a module, you don't
want to open another document if the content exists in the
current document.  Setting 'prefer.internal.olink' to 1 causes
the stylesheet to first test the current document's olink
data to see if it has the id value of the targetptr.  If it
does not, then it falls back to the requested 'targetdoc'
data set.

- Another new feature is the 'olink.base.uri' stylesheet parameter.
This lets you establish a URI prefix for all generated olink URIs.
If you put all your content in one location, then you can put
the common parts of the URI in this parameter.  Then each
'baseuri' attribute in the olink database can be relative
to the olink.base.uri value.  This is most useful when you are
not using relative references between a set of documents, but rather
are referring to other documents, perhaps on another website.
The olink.base.uri value is prepended to *all* olink URIs,
so only use it if all of the content is at that address.  Otherwise,
put the address information in the individual document
baseuri attributes in the olink database.

- Because olink resolution is more complex now, a new stylesheet
parameter 'olink.debug' was added.  When set to 1, the stylesheet
will output messages on how each olink is being resolved.


Olink language resolution
------------------------------------
- Now olinks will try to resolve to a document in the same
language as the source document.  If that fails, then the
stylesheet can fall back through a sequence of languages
that you specify in the 'olink.lang.fallback.sequence'
parameter.  This is similar to the language negotiation
performed by an HTTP browser and server.

- This means olinks can work within a collection
in which only some of the documents are currently translated.  In
general you want an olink to resolve to a target document
in the same language.  This means the olink database
should include the data for all translated versions of a
document.  You can do this by including multiple <document>
elements in the database and setting the 'lang' attribute
to different values.  You can have <document> elements
with duplicate 'targetdoc' attributes only if their 'lang'
attributes differ.

- During processing, the olink source language is determined
by the closest ancestor 'lang' attribute in the source document.
The stylesheet looks for the olink's targetdoc in that language
first.  If that fails, then it tries the first language in
the fallback sequence.  If that fails, it goes on to the next, etc.

For example, if you set the 'olink.lang.fallback.sequence'
parameter to 'de en', and the olink's closest ancestor
lang attribute in the source document is 'fr', then
the stylesheet first looks in the olink database for
a <document> element with a matching targetdoc and with
lang="fr".  If that combination is not found, then the same
targetdoc with lang="de" is tried, and finally lang="en",

- In addition, the 'use.local.olink.style' parameter was
fixed for non-English content.  If this parameter is set
to 1, it causes the stylesheet to assemble your olink
text using your stylesheet's gentext templates.  If it
is set to 0, then it uses the text as it was generated
for the original document.  Prior to version 1.66, this
feature did not work properly for non-English olinks.
Now it works properly for all languages.


xrefstyle
--------------------------------

- olinks now support the xrefstyle attribute that was introduced
in version 4.3 of the DocBook DTD.  The xrefstyle attribute
on an xref or olink element is used to pass hints to the XSL
stylesheet about how to generate the text for the current
cross reference instance.  You can specify a named style,
a select list of keywords, or a gentext template.  Starting
with version 1.66 of the stylesheets, olinks now support
the same features of xrefstyle as for the xref element.

- In the 'select:' type of xrefstyle, two new keywords were
added in 1.66.  The 'docname' keyword will generate the title
of the other document, and the 'docnamelong' keyword can be used
to generate a longer reference to the title.  These keywords
are resolved using the following gentext templates:

  <l:template name="docname" text=" in %o"/>
  <l:template name="docnamelong" text=" in the document titled %o"/>

The '%o' placeholder is filled in with the other document's title.
It is taken from the title associated with the root element of
the other document in the olink database.  You can customize the
wording of these two gentext templates to suit your needs,
and translate them for other languages.  You can also use the
%o in named xrefstyles in the gentext templates as well.

- You can also use the '%o' placeholder in a 'template:'
type of xrefstyle in an olink.  That lets you word a cross
reference as you like and include the other document's
title.

- You can also globally control the addition of the other
document's title using the 'olink.doctitle' stylesheet
parameter.  If it is set to 'yes', then the stylesheet will
append the other document's title for every olink.  It will
use the 'docname' gentext template, which you can customize.
If the 'olink.doctitle' parameter is set to 'maybe', then
you will get a title only if the xrefstyle calls for it.
If you set olink.doctitle to 'no', then no
olinks will get a document title, even if the xrefstyle
calls for it.  The latter setting lets you turn off the
feature for all olinks.  The default value of
olink.doctitle is 'no'.

- You can also use the '%p' placeholder to generate a page number
for an olink.  This requires your olink database to have
'page' attribute values on the <div> and <obj> elements, something
that the stylesheet currently cannot generate.  But if you find
a way to collect such page number information, the olink template
will use the data to generate a page number reference.

- If you have set up page numbers for olinks, then you can also
turn them on globally using the 'insert.olink.page.number'
parameter.  If it is set to 'yes', then the stylesheet will
try to append a page reference to all olinks.  It will
use the gentext template named 'olink.page.citation' to
generate the text, so you can customize that.  If the page
data for an olink is empty, then no text is generated.
If you set 'insert.olink.page.number' to 'maybe', then
you will get a page reference only if the xrefstyle calls for it.
If you set 'insert.olink.page.number' to 'no', then no
olinks will get a page reference, even if the xrefstyle
calls for it.  The latter setting lets you turn off the
feature for all olinks.  The default value of
'insert.olink.page.number' is 'no'.

- Version 1.66 of the stylesheets also introduces the
'olink.properties' attribute set for FO output.  This lets
you can control how format styles are applied to olinks
in print.  Any attributes defined in the 'olink.propeties'
attribute set are added to the <fo:basic-link> element in
the output.  The optional document title and page citation
are not included inside the <fo:basic-link>.

- For HTML, the olink output now has a class="olink" 
attribute.  That permits a CSS stylesheet to apply 
format styles to olinks.


Olink customization
------------------------------
The XSL templates for generating olinks were modularized
in version 1.66 to permit easier customization.  These are
the templates that now be customized:

- select.target.database:  This template is called
for each olink to select the olink target database
filename.  By default, it selects the value of the
'target.database.document' parameter.  If you customize
this template, then you could use more than one olink
database.

- select.olink.key:  This template is called for
each olink to select the data for the olink.
The 'key' here is the combination of targetdoc/targetptr/lang
that will actually be used for this olink.  Currently this
template recurses through the languages to find the best match.
It also handles the cases of a missing targetdoc or targetptr
attribute, and the 'prefer.internal.olink' parameter.

- make.olink.href:  This template assembles the complete
URI for each olink.  This is output as the href for an HTML link, or
as the external-destination attribute for an FO link.  

- olink.hottext:  This template assembles the generated
text for an olink, except for the optional document title 
or page citation.

- olink.docname.citation: This template generates the
optional title of the other document.  You may not need
to customize this template if you customize the
associated gentext template instead.

- olink.page.citation: This template generates the optional
page number citation for an olink.  You may not need to
customize this template if you customize the associated
gentext template instead.

- insert.olink.docname.markup mode:  This is a mode that
handles wrapping format styles around the optional document
title generated for a olink.  This permits you to make
the other document's title italic or some other format.

Bob Stayton
Sagehill Enterprises
DocBook Consulting
bobs@sagehill.net