Re: DOCBOOK-APPS: xref linkend

[Bob Stayton <bobs at caldera dot com>]

Well, let's be careful about how closely the Definitive
Guide and the DocBook XSL stylesheets have to be aligned.
We want to keep separate the semantic model, which is
described in TDG, from the stylesheets, which are not.

Any DocBook stylesheets should implement the processing
expectations to the degree they are specified in TDG.  In
the case of endterm and xreflabel precedence in an xref
element, there was some ambiguity that has been resolved,
and now the two agree in the latest versions.

Outside of the documented processing expectations, however,
stylesheets are free to implement any rendering style.
Whether an xref to a chapter should render as
"Chapter 3" or "Chapter 3,  My Chapter Title"
is a stylesheet design choice.  TDG is careful to
describe its xref example as:

"One reasonable rendering for the content ..."

Norm has written the stylesheets to be flexible enough to
accomodate style variations.  You don't need to change any
DocBook sources. It can all be done in a stylesheet
customization layer that remains (nearly) constant when you
update the DocBook stylesheets from a new distribution.

Hope this clarifies the issue.

Bob Stayton                                 400 Encinal Street
Publications Architect                      Santa Cruz, CA  95060
Technical Publications                      voice: (831) 427-7796
The SCO Group                               fax:   (831) 429-1887
                                            email: bobs@sco.com


On Sun, Jan 12, 2003 at 01:05:24PM +1100, Sean Wheller wrote:
> Thanks Bob,
> 
> I have read that and found a solution.
> 
> Thanks.
> 
> But I think that on the overall it missed the point. Which, is that TDG and
> the XSL are not aligned, so making the expected results, explained by TDG,
> unreliable. This demotes the value of the TDG as the "definitive guide" and
> IMHO should be fixed. My definition of a BUG is when a piece of software
> does not behave as specified in the requirements. Which for me is "TDG".
> 
> TDG V.2.07 is a work in progress, so we should be able to update either TDG
> or the XSL to perform as required. In this case, given that linkend, endterm
> and xreflabel do not perform as required, I think it should be the XSL. How
> do we do that?
> 
> On the changes to the XSL, I really don't want to change the DocBook
> Sources. If I do, then I will have to remember all the fixes I have done
> when it comes to the next release. As with many, I prefer to change my
> customization layer, but once again, there will be a problem with knowing
> what was fixed in the next release so I can remove fixes from my
> customization.
> 
> Warm Regards,
> 
> Sean Wheller
> 
> 
> 
> > -----Original Message-----
> > From: bobs@caldera.com [mailto:bobs@caldera.com]
> > Sent: Sunday, January 12, 2003 3:25 AM
> > To: Sean Wheller
> > Cc: docbook-apps@lists.oasis-open.org
> > Subject: Re: DOCBOOK-APPS: xref linkend
> >
> >
> > There is an example of an XSL customization to add title
> > to chapter xrefs in:
> >
> > http://www.sagehill.net/xml/docbookxsl/CustomMethods.html#CustomGenText
> >
> >
> > Bob Stayton                                 400 Encinal Street
> > Publications Architect                      Santa Cruz, CA  95060
> > Technical Publications                      voice: (831) 427-7796
> > The SCO Group                               fax:   (831) 429-1887
> >                                             email: bobs@sco.com
> >
> >
> > On Sat, Jan 11, 2003 at 11:41:29PM +1100, Sean Wheller wrote:
> > > In the archives I found the message below which illustrates my
> > problem. I also
> > > found a solution for DSSSL from another list member.
> > >
> > > However, I am using:
> > > XSL Stylesheets V1.58.1
> > > DocBook XML DTD V4.2
> > >
> > > My xref points to a chapter element <chapter
> > > id="introduction><title>Introduction</title>
> > >
> > > The xref looks like this <xref linkend="introduction"/>
> > >
> > > Has anyone come across this problem? If so is there a solution?
> > Preferably
> > > something I can add to my customization layer, rather than editing the
> > > docbook xsl.
> > >
> > > Also, has someone added this to the buglist?
> > >
> > > >Subject: DOCBOOK-APPS: Re: DOCBOOK: xref or link?
> > > From: Bob McIlvride <robert@cogent.ca>
> > > >To: "docbook-apps@lists.oasis-open.org"
> > <docbook-apps@lists.oasis-open.org>
> > > >Date: Fri, 08 Jun 2001 10:24:49 -0400
> > > >
> > > > Xref will automatically generate the link text;
> > > >
> > > >I don't get the output that TDG suggests.  TDG says this SGML:
> > > >
> > > >     <para>A straight link generates the
> > > >     cross-reference text: <xref linkend="ch02">.
> > > >     </para>
> > > >
> > > >reasonably renders like this:
> > > >
> > > >     A straight link generates the cross-reference text:
> > > >     Chapter 2, "The Second Chapter"
> > > >
> > > >My SGML:
> > > >
> > > >     <para>Here is a test xref to
> > > >     <xref linkend="testoftables">.</para>
> > > >
> > > >renders like this:
> > > >
> > > >     Here is a test xref to Chapter 3.
> > > >
> > > >I'd really like to get the name of the chapter in there, if possible.
> > > >Any suggestions?
> > > >Currently using:
> > > >DocBook v. 4.1.2
> > > >DocBook stylesheets v. 1.64
> > > >OpenJade v. 1.3
> > >
> > > Many thanks,
> > > --
> > > Sean Wheller
> > > swheller@bigpond.net.au
> > > XWriter
> > >
> > >
> >
> > --
> >
> > Bob Stayton                                 400 Encinal Street
> > Publications Architect                      Santa Cruz, CA  95060
> > Technical Publications                      voice: (831) 427-7796
> > The SCO Group                               fax:   (831) 429-1887
> >                                             email: bobs@sco.com
> 

-- 

Bob Stayton                                 400 Encinal Street
Publications Architect                      Santa Cruz, CA  95060
Technical Publications                      voice: (831) 427-7796
The SCO Group                               fax:   (831) 429-1887
                                            email: bobs@sco.com