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
