Bruce Momjian <bruce@momjian.us> writes: > On Mon, Feb 16, 2015 at 05:05:39PM +1300, Craig Ringer wrote: >> 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:
> Have you read README.links in the sgml top-level directory?
Yes.
It doesn't explain why the <title> element isn't used for linktext - but expecting that to work appears to be my misunderstanding from a misreading of the docbook documentation. It seems you need an explicit xreflabel to set the xref link text; openjade will not find the <title> element under the referenced element automatically.
Given that, I think perhaps a *lot* more xreflabel attributes are needed, because this "See Chapter 33" guff is completely uninformative to users. They might as well render as "See [CLICK HERE]" for all the useful information the linktext carries.
I suspect that the answer is different in different output formats, for example PDF format would probably prefer oldschool chapter/section numbers even if we go over to names in HTML versions.
Docbook lets that be overridden per output medium with gentext overrides. See the existing overrides used for the man pages in stylesheet-man.xsl .
(Consider the manual printed on dead trees: named links would be of *zero* value there, while you could still flip to a numbered section reasonably quickly.) This is another reason for not thinking that hacking the text link-by-link is an appropriate answer.
I agree, and that's why I really wanted to avoid doing so.