Unit Test: xref.004.xml

Frank Steimke

1Effectivity attributes and profiling

1.1Effectivity

When a document is formatted, the stylesheets can selectively include or omit elements based on their configured effectivity. This “profiled” version of the document is the one that’s explicitly targeted to the audience specified.

DocBook supports a wide variety of common attributes for this purpose:

Table 1Common DocBook effectivity attributes
AttributeNominal effectivity axis
archThe architecture, Intel or AMD
audienceThe audience, operations or development
conditionAny condition (semantically neutral)
conformanceThe conformance level
osThe operating system, Windows or Linux
outputformatThe output format, print or online
revisionThe revision, 3.4 or 4.0.
securityThe security, secret or top-secret
userlevelThe user level, novice or expert
vendorThe vendor, Acme or Yoyodyne
wordsizeThe word size, 32 or 64 bit

2Customize individual cross references

The text that is generated by cross references can be customized for individual elements with the xrefstyle Attribute. Lets say you want to reference a numbered chapter or a section with target as its @xml:id. While <xref linkend='target'/> will give you a generated text in a default style, you can customize it for individual cross references and write something like <xref linkend='target' xrefstyle='%label'>, which would result in the target s name and number, e. g. Section 2.1.

You can use the %c, %l and %p values . There is also an additional %label for the full Label, which is the component`s name and number. The use of these percent-values is explained in the following table, where all cross references target the next section called Syntax highlighting.

Value of xref/@xrefstyle

Result

Remark

(@xrefstyle is absent)Section 3, “Syntax highlighting”Default
%cSyntax highlighting

Content, e. g. title of target

%l3

Label, ususally the targets number.

%labelSection 3

The full Label, ususally the targets number and name.

%p

Page number.

Intended for PDF. Displayed as "#" in HTML, unless you differentiate between the output formats for print and online. See Section 2.1 for a possible solution.

%label (%c)Section 3 (Syntax highlighting)

You can use different %-letters and combine with text

Legacy values for xrefstyle

In order to support migration from XSLT 1.0 Stylesheets, xslTNG supports the template: Syntax which is explained in the Book "DocBook XSL: The Complete Guide", Section "Customizing with an xrefstyle attribute / Using template:". This is explained with the following table.

Value of xref/@xrefstyle

Result

Remark

template:the chapter numbered %nthe chapter numbered 3XSLT 1.0 Legacy Syntax
template:the chapter called %tthe chapter called Syntax highlightingXSLT 1.0 Legacy Syntax

2.1Using pagenumber in cross-references

The %p makes little sense in HTML output, since there are no page numbers. If you use it anyway, it will be displayed as "#", which can be confusing for readers. A possible solution for this problem is the use of the outputformat attribute, that was intoduced in Section 1, “Effectivity attributes and profiling” and Table 1.

This cross reference to Section 3 will include the target`s page number only when the @profile.outputformat parameter is "print", but without the annoying # in HTML.

1 |This cross reference to 
  |            <xref linkend="syntax-highlighting"  xrefstyle="%label/>
  |            <phrase outputformat="print"> 
  |            on <xref linkend="syntax-highlighting" xrefstyle="page %p"/>
5 |            </phrase>
  |            will reference the page number only when the @profile.outputformat parameter is print,
  |            but without the annoying # in HTML.
Example 1Use outputformat to deal with page numbers in cross references

3Syntax highlighting

This section serves as xref target only.