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

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. +

--
Sent via pgsql-docs mailing list (pgsql-docs@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-docs

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

--
Sent via pgsql-docs mailing list (pgsql-docs@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-docs

On 17 February 2015 at 15:27, Tom Lane <tgl@sss.pgh.pa.us> wrote:

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.

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

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.

--
Sent via pgsql-docs mailing list (pgsql-docs@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-docs