Unit Test: xref.004.xml
1. Effectivity attributes and profiling
1.1. Effectivity
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:
| Attribute | Nominal effectivity axis |
|---|---|
| arch | The architecture, Intel or AMD |
| audience | The audience, operations or development |
| condition | Any condition (semantically neutral) |
| conformance | The conformance level |
| os | The operating system, Windows or Linux |
| outputformat | The output format, print or online |
| revision | The revision, 3.4 or 4.0. |
| security | The security, secret or top-secret |
| userlevel | The user level, novice or expert |
| vendor | The vendor, Acme or Yoyodyne |
| wordsize | The word size, 32 or 64 bit |
2. Customize 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 | Result | Remark |
|---|---|---|
(@xrefstyle is absent) | Section 3, “Syntax highlighting” | Default |
%c | Syntax highlighting | Content, e. g. title of target |
%l | 3 | Label, ususally the targets number. |
%label | Section 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 | Result | Remark |
|---|---|---|
template:the chapter numbered %n | the chapter numbered 3 | XSLT 1.0 Legacy Syntax |
template:the chapter called %t | the chapter called Syntax highlighting | XSLT 1.0 Legacy Syntax |
2.1. Using 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.
3. Syntax highlighting
This section serves as xref target only.