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

On 17 February 2015 at 15:27, Tom Lane <tgl(at)sss(dot)pgh(dot)pa(dot)us> wrote:

> Bruce Momjian <bruce(at)momjian(dot)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.

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