pg.ddx.io pgsql-docs@postgresql.org mailing list archive
help / color / mirror / Atom feedxref labels: "Chapter 33", "Section 33.2"
5+ messages / 4 participants
[nested] [flat]
* xref labels: "Chapter 33", "Section 33.2"
@ 2015-02-16 04:05 Craig Ringer <craig@2ndquadrant.com>
2015-02-16 22:08 ` Re: xref labels: "Chapter 33", "Section 33.2" Bruce Momjian <bruce@momjian.us>
2015-02-23 18:04 ` Re: xref labels: "Chapter 33", "Section 33.2" Peter Eisentraut <peter_e@gmx.net>
0 siblings, 2 replies; 5+ messages in thread
From: Craig Ringer @ 2015-02-16 04:05 UTC (permalink / raw)
To: pgsql-docs
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
^ permalink raw reply [nested|flat] 5+ messages in thread
* Re: xref labels: "Chapter 33", "Section 33.2"
2015-02-16 04:05 xref labels: "Chapter 33", "Section 33.2" Craig Ringer <craig@2ndquadrant.com>
@ 2015-02-16 22:08 ` Bruce Momjian <bruce@momjian.us>
2015-02-17 02:27 ` Re: xref labels: "Chapter 33", "Section 33.2" Tom Lane <tgl@sss.pgh.pa.us>
1 sibling, 1 reply; 5+ messages in thread
From: Bruce Momjian @ 2015-02-16 22:08 UTC (permalink / raw)
To: Craig Ringer <craig@2ndquadrant.com>; +Cc: pgsql-docs
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
^ permalink raw reply [nested|flat] 5+ messages in thread
* Re: xref labels: "Chapter 33", "Section 33.2"
2015-02-16 04:05 xref labels: "Chapter 33", "Section 33.2" Craig Ringer <craig@2ndquadrant.com>
2015-02-16 22:08 ` Re: xref labels: "Chapter 33", "Section 33.2" Bruce Momjian <bruce@momjian.us>
@ 2015-02-17 02:27 ` Tom Lane <tgl@sss.pgh.pa.us>
2015-02-17 08:36 ` Re: xref labels: "Chapter 33", "Section 33.2" Craig Ringer <craig@2ndquadrant.com>
0 siblings, 1 reply; 5+ messages in thread
From: Tom Lane @ 2015-02-17 02:27 UTC (permalink / raw)
To: Bruce Momjian <bruce@momjian.us>; +Cc: Craig Ringer <craig@2ndquadrant.com>; 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
^ permalink raw reply [nested|flat] 5+ messages in thread
* Re: xref labels: "Chapter 33", "Section 33.2"
2015-02-16 04:05 xref labels: "Chapter 33", "Section 33.2" Craig Ringer <craig@2ndquadrant.com>
2015-02-16 22:08 ` Re: xref labels: "Chapter 33", "Section 33.2" Bruce Momjian <bruce@momjian.us>
2015-02-17 02:27 ` Re: xref labels: "Chapter 33", "Section 33.2" Tom Lane <tgl@sss.pgh.pa.us>
@ 2015-02-17 08:36 ` Craig Ringer <craig@2ndquadrant.com>
0 siblings, 0 replies; 5+ messages in thread
From: Craig Ringer @ 2015-02-17 08:36 UTC (permalink / raw)
To: Tom Lane <tgl@sss.pgh.pa.us>; +Cc: Bruce Momjian <bruce@momjian.us>; 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
^ permalink raw reply [nested|flat] 5+ messages in thread
* Re: xref labels: "Chapter 33", "Section 33.2"
2015-02-16 04:05 xref labels: "Chapter 33", "Section 33.2" Craig Ringer <craig@2ndquadrant.com>
@ 2015-02-23 18:04 ` Peter Eisentraut <peter_e@gmx.net>
1 sibling, 0 replies; 5+ messages in thread
From: Peter Eisentraut @ 2015-02-23 18:04 UTC (permalink / raw)
To: Craig Ringer <craig@2ndquadrant.com>; pgsql-docs
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
^ permalink raw reply [nested|flat] 5+ messages in thread
end of thread, other threads:[~2015-02-23 18:04 UTC | newest]
Thread overview: 5+ messages (download: mbox mbox.gz follow: Atom feed)
-- links below jump to the message on this page --
2015-02-16 04:05 xref labels: "Chapter 33", "Section 33.2" Craig Ringer <craig@2ndquadrant.com>
2015-02-16 22:08 ` Bruce Momjian <bruce@momjian.us>
2015-02-17 02:27 ` Tom Lane <tgl@sss.pgh.pa.us>
2015-02-17 08:36 ` Craig Ringer <craig@2ndquadrant.com>
2015-02-23 18:04 ` Peter Eisentraut <peter_e@gmx.net>
This inbox is served by DDX for PostgreSQL; see mirroring instructions
for how to clone and mirror all data and code used for this inbox