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

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?

--