xref labels: "Chapter 33", "Section 33.2"

Hi all

Every time I go to work on the SGML docs I find myself struggling with
<xref> linktext, to the point where I thought I'd ask for a few pointers
here.

I've read the relevant docs on DocBook linking - the introductory/newbie
stuff (
http://newbiedoc.sourceforge.net/metadoc/docbook-guide.html#LINKS-DOCBOOK-GUIDE),
the tech docs (http://www.sagehill.net/docbookxsl/CrossRefs.html),
customisation docs (http://www.sagehill.net/docbookxsl/CustomXrefs.html)
and element docs (http://docbook.org/tdg/en/html/xref.html).

I can't seem to make an <xref linkend="spi"> render the <title>...</title>
element text. The DocBook documentation implies that this should be the
default; e.g. if you have:

<chapter id="spi">
<title>Server Programming Interface</title>

then

<xref linkend="spi">

should render as "Server Programming Interface" because the <title> element
is looked up.

This doesn't seem to be the case in the official docs on postgresql.org or
in "make html" builds.

The stylesheets don't seem to specify the <xsl:param>
xref.with.number.and.title - if that was set to zero then the behaviour I
see would be expected. Setting it explicitly in stylesheet-common.xsl:

<xsl:param name="xref.with.number.and.title">1</xsl:param>

appears to have no effect.

The only gentext customisations seem to be in styleshet-man.xsl so it
doesn't seem to be being overridden.

These links are quite user-unfriendly when our chapter numbering isn't
really very informative. "See [Section 33.1.2]" tells the user nothing. I'd
really like to change the default to actually use the title texts.

Am I just missing something obvious? Is this linking style, where the
chapter title is ignored, by design?

I can just use <link> elements, but I'd really rather avoid endlessly
repeating things like

<link linkend="spi">Server Programming Interface
(<acronym>SPI</acronym>)</link>

everywhere, especially as that's the whole purpose of <xref> and the
<title> element.

Comments?

--
Craig Ringer http://www.2ndQuadrant.com/
PostgreSQL Development, 24x7 Support, Training & Services