Re: DOCBOOK-APPS: Including titles with xrefs in XML

[Bob Stayton <bobs at caldera dot com>]

> From: Dennis Grace <dgrace@us.ibm.com>
> 
> According to Norm Walsh'sTDG, a reasonable rendering for an unadorned xref
> should include a referenced chapter's title.  In other words, if my second
> chapter is tagged:
> 
>      <chapter id="stuff">
>           <title>Stuff and Nonsense</title>
> 
> then an xref like so:
> 
>      <xref linkend="ch2"/>
> 
> should be rendered:
> 
>      Chapter 2, "Stuff and Nonsense"
> 
> I have not found this to be the case with either the 1.59 DSSSL or the 1.41
> XSL. All I get is
> 
>      Chapter 2
> 
> I found Jirka's archived explanation of how to add the title in with the
> DSSSLs (which worked, incidentally). Does anyone know how to accomplish the
> same via the XSLs?

The XSL stylesheets use another kind of template system to
form xref text and other generated text strings (not to be
confused with XSL apply-templates). It uses
templates of text strings, sort of like the strings used in 
printf statements, where some of the text is fixed and
some is variable to be substituted at runtime.

The string templates are localized, and may be
highly customized.  In your 1.41 distribution, you should
find common/en.xml.  That contains all the generated text strings
for processing with the default lang="en".

Search in en.xml for <context name="xref">.  That
element contains <template> elements for each
kind of element that can have automatically generated
xref text.  The default one for chapter says:

<template name="chapter" text="Chapter %n"/>

The %n represents the item number (chapter number in
this case). You can use %t to represent the title.
So you could change it to:

<template name="chapter" text='Most Worthy Chapter %n, "%t"'/>

Note that I changed the enclosing attribute quote characters
to permit using "" around the title.

BTW, don't be put off by the message at the top of the file
"Do not edit this file by hand!". That only applies if you
are building the template files from the CVS source.  Since
the stylesheet distro doesn't come with the source or
Makefile, you can ignore that comment and customize it to
suit your needs.

However, you can also do such customization without
touching the original distro files. It takes a few
more steps:

1.  In 'common' directory, copy en.xml to a new name
like custom-en.xml and make your changes there.

2.  Also in common, copy l10n.xml to a new name
like custom-l10n.xml.  Edit custom-l10n.xml to change

<!ENTITY en SYSTEM "en.xml">
 to
<!ENTITY en SYSTEM "custom-en.xml"> 

so that it references your customized file.

3.  In your customization layer for your stylesheet,
add another parameter:

<xsl:param name="l10n.xml"
           select="document('../common/custom-l10n.xml')"/>            

This parameter sets the parameter named "l10n.xml"
(yes, it sure looks like a filename) to your custom
filename, which pulls in your custom english template
file.  This parameter should probably be listed in
param.xsl, but it isn't.

Of course, if you were hoping for just a simple parameter
that would turn on chapter titles, well, it isn't there.
The template system gives you a great deal of control,
but it is a bit more complex.

I'm updating the doc on XSL customization to include
stuff like this.

bobs
Bob Stayton                                 400 Encinal Street
Publications Architect                      Santa Cruz, CA  95060
Technical Publications                      voice: (831) 427-7796
Caldera International, Inc.                 fax:   (831) 429-1887
                                            email: bobs@caldera.com

------------------------------------------------------------------
To unsubscribe from this elist send a message with the single word
"unsubscribe" in the body to: docbook-apps-request@lists.oasis-open.org