[docbook-tc] xref style proposal

[Bob Stayton <bobs@caldera.com>]

This is for one of my action items.


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

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:

style      - 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 there is an alternative suggestion of combining
these two functions into a single attribute.


The 'style' attribute
------------------------

The 'style' 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" style="ChapterTitle" text="&#8220;%t&#8221;"/>
</l:context>

Such a style is used as follows:

<xref linkend="UsingMouse" style="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 style name.  
This would produce the chapter title in quotes in the output.

If the style 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 style attribute is similar to the feature of named
cross reference styles in FrameMaker.  Norm has a sample
implementation in the DocBook XSL 1.53.0 stylesheets.

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

An alternative approach that gives greater control 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.

Each assembled text string can 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 'style' attribute can
provide any additional variations in a customization layer.

In general, either the 'style' 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 'style'
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:

style="ChapterTitle"
style="select: quotedtitle pageabbrev"

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

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.  


-- 

Bob Stayton                                 400 Encinal Street
Publications Architect                      Santa Cruz, CA  95060
Technical Publications                      voice: (831) 427-7796
Caldera International, Inc.                 fax:   (831) 429-1887
                                            email: bobs@caldera.com