Thread: 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.
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>
<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?
--
On Mon, Feb 16, 2015 at 05:05:39PM +1300, Craig Ringer wrote: > 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: Have you read README.links in the sgml top-level directory? -- Bruce Momjian <bruce@momjian.us> http://momjian.us EnterpriseDB http://enterprisedb.com + Everyone has their own god. +
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?
I think Craig's question is more about our overall house style/policy, ie,
how do we want such links to be rendered? I am definitely *not* in favor
of authors of portions of the docs trying to impose their own opinions on
individual links, which is where his question seems to be leading. But it
is a fair question whether we'd like to change the currently existing
global rendering decision, and if so what would be the best way to
implement that.
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. (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.
regards, tom lane
On 17 February 2015 at 15:27, Tom Lane <tgl@sss.pgh.pa.us> wrote:
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.
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.
--
On 2/15/15 11:05 PM, Craig Ringer wrote: > 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. You are looking at XSL style sheets but are (probably) building the documentation with the DSSSL style sheet.