DOCBOOK-APPS: xref style proposal

[Bob Stayton <bobs@caldera.com>]

This is a proposal for enabling individual
xref elements to be presented differently
from the default.  It is under consideration
by the DocBook Technical Committee, and I
thought it would be good to get feedback
from the docbook-apps mailing list.


Proposed xref style attributes
================================

When generating cross reference text for xref and olink
elements, the DocBook XSL stylesheets use gentext templates
that are defined in the locale files in the 'common'
subdirectory of the distribution (see 'en.xml' for
example).  Although the gentext templates can be
customized, there is still only one template defined per target
element.  That means there is only one style of generated
text for each element.

Authors sometimes need to present a given cross reference
differently, depending on the context.  For example, a
section title might need to be quoted when it appears in
the middle of a sentence, but unquoted when standing alone
as a list item.  Or you may want to make several references
using abbreviated syntax such as "See Figures 3.2, 3.5, and
3.6" rather than "See Figure 3.2, Figure 3.5, and Figure 3.6".

Xref style choices could be put into processing
instructions, but PIs are subject to being lost
in multiple transformations.  An attribute to the xref
element seems the best choice for this additional
information, similar to hints provided in attributes
for presentation of graphics.

One could use the xref 'role' attribute to specify
a different style for a given xref, but role might
be needed for other purposes.

This proposal suggests two new attributes for the xref and
olink elements that provide some control over generated xref text:

xrefstyle      - the name of a prefdefined style template.
select         - one or more keywords to select components of xref text.

Both of these attributes are of type CDATA with no
defaults.  At the end of this mail there is an alternative
suggestion of combining these two functions into a single
attribute.


The 'xrefstyle' attribute
------------------------

The 'xrefstyle' attribute is used to select one of a set of
predefined style names. For each name there must be a cross
reference gentext template defined as part of the stylesheet
customization layer.  For example:

<l:context name="xref">
  <l:template name="chapter" xrefstyle="ChapterTitle" text="&#8220;%t&#8221;"/>
</l:context>

Such a style is used as follows:

<xref linkend="UsingMouse" xrefstyle="ChapterTitle"/>

If 'UsingMouse' is the id of a chapter element, then 
the customized template is used since it matches on
the element name and the xrefstyle name.  
This would produce the chapter title in quotes in the output.

If the xrefstyle name is not defined for the element type that is the
target of the cross reference, then the stylesheet falls
back to the regular xref template for that element.

The xrefstyle attribute is similar to the feature of named
cross reference styles in FrameMaker.  Norm has a sample
implementation starting in the DocBook XSL 1.53.0 stylesheets.

The 'select' attribute
------------------------

An alternative approach uses the
'select' attribute.  It is used to specify one or more
components of the cross reference text.  The stylesheet
algorithm then assembles the cross reference text using
those components.  The components are selected from a set
of keywords that the stylesheet recognizes.

[Note: this part of the proposal is derived from
suggestions and the sample implmentation in 
the SourceForge Feature Request #451011 submitted by Erik Hennum.]

A simple example might be:

<xref linkend="UsingMouse" select="quotedtitle"/>

This produces the element's title in quotes.
A more complex example might be:

<xref linkend="UsingMouse" select="label title"/>

This produces chapter number (the label) and the title
without quotes.

In this proposal, each assembled text string could have
three parts:  label, title, and page.  The parts always
appear in this order if they are included.

The page portion can be turned off for output forms like HTML that
don't have page numbers.  For print output, you can specify
that page numbering be turned on globally, and then use
the 'nopage' keyword to turn off specific references.

These are the proposed 'select' keywords for the three parts:

label         - label name and number, such as "Figure 3.2"
labelname     - label name only, such as "Figure"
labelnumber   - label number only, such as "3.2"

title         - text of element title
quoted title  - title text enclosed in quotes

page          - lowercase page reference, such as "on page 32"
Page          - Uppercase page reference, such as "Page 32"
pageabbrev    - Abbreviated page reference, such as "p. 32"
pagenumber    - Page number only, such as "32"
nopage        - no page number reference at all


The text generated by each of these keywords comes from
gentext templates, sometimes directly, sometimes using
existing DocBook named XSL templates:

labelname     - from <l:gentext key="elementname" text="..." /> 
labelnumber   - from the element processed in 'label.markup' mode
label         - combination of the preceding two,
                  separated by a non-breaking space

title         - from the element processed in 'title.markup' mode
quoted title  - same, preceded by <l:dingbat key="startquote" text="..."/>
                  and followed by <l:dingbat key="endquote" text="..."/>

page          - from new gentext template in xref context. Example:
                  <l:template name="page" text="on page %p" /> 
Page          - from new gentext template in xref context. Example:
                  <l:template name="Page" text="Page %p" /> 
pageabbrev    - from new gentext template in xref contest: Example:
                  <l:template name="pageabbrev" text="(p. %p)" /> 
pagenumber    - just the %p gentext markup


Several stylesheet parameters are used to define joining
text to "glue" the parts together.  The parameters are:

xref.label-title.separator  - inserted between label and title
xref.label-page.separator   - inserted between label and page
xref.title-page.separator   - inserted between title and page

A given separator is used only if both of its parts are
included in the xref string.  Since the order of parts
is fixed, only three separators are needed.

Once the set of gentext templates and stylesheet parameters
are established, a given xref or empty olink can use 
a 'select' attribute to specify any combination of the three 
parts as keywords.  

This design covers the most common variations needed
for cross references.  It cannot cover all possible styles
without becoming overly complex.  It also may not
work in all languages.  In those cases, the 'xrefstyle' attribute can
provide any additional variations in a customization layer.

The 'select' attribute is less flexible than the 'xrefstyle'
attribute, which can be customized to any form.  But
the 'select' attribute has one advantage: it does not
require any customization of the stylesheets to be used.
The algorithm is built in.

In general, either the 'xrefstyle' or the 'select' attribute
is used.  If both are used, the stylesheet policy decides
which has precedence.  Also, if two keywords are used
for the same part (e.g. title and quotedtitle),
then the stylesheet determines their precedence.


Single attribute alternative
-------------------------------

Since the two functions are mutually exclusive, it might be
worthwhile combining the two attributes into one 'xrefstyle'
attribute.  In that case, the stylesheet needs to specify
the syntax it uses to tell whether a given value is a named
style or a 'select' string.  For example:

xrefstyle="ChapterTitle"
xrefstyle="select: quotedtitle pageabbrev"

In this alternative, the minimal change to the DocBook DTD is to
add a single 'xrefstyle' attribute of type CDATA to xref
and olink.

Another issue is whether the DocBook documentation should
prescribe the 'select' syntax, even if it is not part of
the DTD itself.  The advantage is that interchange of
documents is easier if there is a standard syntax.
However, there is no way to validate the syntax, so it
would just be a convention.  So I don't think the
DTD should prescribe values for the attribute.

Comments?
-- 

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