diff --git a/src/guide/xml/ch02.xml b/src/guide/xml/ch02.xml index b2e1e4b20..6def75c4e 100755 --- a/src/guide/xml/ch02.xml +++ b/src/guide/xml/ch02.xml @@ -1055,7 +1055,7 @@ and unnumbered sections have? The mechanisms for changing this generated text ar described in . These mechanisms control the formatting of cross references. -But it’s sometimes desirable to be able to change the format of a +But it’s sometimes useful to be able to change the format of a cross reference on an individual basis (that is, on the basis of the context in which the reference occurs, not the nature of what is referenced). You might, for @@ -1080,19 +1080,20 @@ linkend="table.template-letter-substitutions"/> in xrefstyle. 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 . +explained in the following table. The result column shows how a +cross references to the section below entitled + would appear +in each xrefstyle. - + - Value of xref/@xrefstyle + Value of xrefstyle attribute on xref Result Remark @@ -1112,31 +1113,29 @@ xrefstyle="%c"/>. %l - Label, ususally the targets number. + Label, usually the target’s number. %label - The full Label, ususally the targets number and name. + The full Label, usually the target’s number and name. %p - - Page number. Intended for print output (PDF). Displayed as "#" in HTML, - unless you differentiate between the output formats for print and online. See for a possible - solution. + + Page number in print output (PDF). Displays as “#” in HTML. %label (%c) - You can use different %-letters and combine with text + You can combine %-letters with text -Legacy values for xrefstyle + +Legacy values for xrefstyle In order to support migration from XSLT 1.0 Stylesheets, xslTNG supports the template: Syntax which is explained in @@ -1149,13 +1148,13 @@ xrefstyle="%c"/>. - + - Value of xref/@xrefstyle + Value of xrefstyle attribute on xref Result Remark @@ -1177,36 +1176,51 @@ xrefstyle="%c"/>. + -
+ 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 and - on page . - - This cross reference to - on will include the target`s page number only when the - @profile.outputformat parameter is "print", but without - the annoying # in HTML. - - - Use outputformat to deal with page numbers in cross references - This cross reference to -<xref linkend="syntax-highlighting" xrefstyle="%label/> -<phrase outputformat="print"> - on <xref linkend="syntax-highlighting" xrefstyle="page %p"/> -</phrase> -will reference the page number only when the -@profile.outputformat parameter is print, but -without the annoying # in HTML. - -
+ + The %p value in xrefstyle makes + little sense in HTML output, since there are no page numbers. If you use it + anyway, it will be displayed as + “#”. + This may be confusing for readers. A possible solution for this problem is the use of + the outputformat attribute. For example: + + +
+The outputformat attribute was intoduced in + and + on page +. + +
+ + +The paragraph markup in that example is: + + + Use outputformat to deal with page numbers in cross references + The outputformat attribute was intoduced in + and + on page +. +]]> + + +Where the page number appears in the print version, but not in the HTML version. +Note that some care has been taken with line breaks and spaces around markup +to avoid extraneous whitespace in either version. + +
diff --git a/src/main/scss/media-all.scss b/src/main/scss/media-all.scss index 93390ada3..341ee3be7 100644 --- a/src/main/scss/media-all.scss +++ b/src/main/scss/media-all.scss @@ -359,11 +359,6 @@ a.pmuj { font-style: italic; } -.xref-pagenum { - content: target-counter(attr(href), page); - font-style:normal; -} - .xref-area, .xref-areaset, .xref-co, diff --git a/src/main/scss/media-paged.scss b/src/main/scss/media-paged.scss index 4bb2e0afe..3bf922347 100644 --- a/src/main/scss/media-paged.scss +++ b/src/main/scss/media-paged.scss @@ -211,3 +211,10 @@ span.footnote p { padding-top: 0; margin-top: 0; } + +/* xref with pagenumber ====================================== */ + +.xref-pagenum::after { + content: target-counter(attr(href), page); + font-style:normal; +} diff --git a/src/main/scss/media-screen.scss b/src/main/scss/media-screen.scss index 75abe198b..911378310 100644 --- a/src/main/scss/media-screen.scss +++ b/src/main/scss/media-screen.scss @@ -450,6 +450,13 @@ nav.top div { /* ============================================================ */ +@media screen { + .xref-pagenum::after { + content: "#"; + font-style:normal; + } +} + @media screen and (max-width: 1199px) { nav.top div { padding-left: 2rem; diff --git a/src/main/xslt/modules/links.xsl b/src/main/xslt/modules/links.xsl index 5e411fde7..c161f2f4f 100644 --- a/src/main/xslt/modules/links.xsl +++ b/src/main/xslt/modules/links.xsl @@ -245,7 +245,7 @@ group-adjacent=". instance of node() and local-name() = ('pagenum')"> - # + diff --git a/src/test/resources/expected/xref.004.html b/src/test/resources/expected/xref.004.html index d211db43c..2ab105a18 100644 --- a/src/test/resources/expected/xref.004.html +++ b/src/test/resources/expected/xref.004.html @@ -1,30 +1,31 @@ -Unit 04Unit Test: xref.004.xml

Unit Test: xref.004.xml

Frank Steimke

Table of Contents

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:

Table 1. Common 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

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 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.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.
-
Example 1. Use outputformat to deal with page numbers in cross references

3. Syntax highlighting

This section serves as xref target only.

\ No newline at end of file +Unit 04Unit Test: xref.004.xml

Unit Test: xref.004.xml

Frank Steimke

Table of Contents

1. Customize individual cross references

Most kinds of generated text apply across an entire document: do you want chapters + to be numbered? Should generated text be in English or French? What form should numbered + and unnumbered sections have? The mechanisms for changing this generated control the formatting + of cross references.

But it’s sometimes desirable to be able to change the format of a + cross reference on an individual basis (that is, on the basis of the + context in which the reference occurs, not the + nature of what is referenced). You might, for + example, want to shorten a cross reference to just a label if it’s + already been referenced several times.

Consider a cross reference to a section: + see <xref linkend="syntax-highlighting"/>. + In the localization style of this guide, that is rendered like this: + see Section 2, “Syntax highlighting”.

The text that is generated by a cross reference can be customized + for individual references with the xrefstyle attribute. + For example, + see <xref linkend="syntax-highlighting" xrefstyle="%l"/>, + will produce a result like this: + see 2.

You can use the %c, %l and + %p values in + xrefstyle. 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/@xrefstyleResultRemark
(@xrefstyle is absent)Section 2, “Syntax highlighting”Default
%cSyntax highlightingContent, e. g. title of target
%l2Label, ususally the targets number.
%labelSection 2The full Label, ususally the targets number and name.
%pPage number in print output (PDF). Displayed as “#” in HTML.
%label (%c)Section 2 (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 + “Customizing + with an xrefstyle attribute / Using template:” in + the book “DocBook XSL: The Complete + Guide”. This is summarized in the following + table.

Value of xref/@xrefstyleResultRemark
template:the chapter numbered %nthe chapter numbered 2XSLT 1.0 Legacy Syntax
template:the chapter called %tthe chapter called Syntax highlightingXSLT 1.0 Legacy Syntax

2. Syntax highlighting

Program listings and other verbatim environments can be “syntax highlighted”, + that is, the significant tokens in the listing can be colored differently (keywords in red, + quoted strings in blue, that sort of thing).

\ No newline at end of file diff --git a/src/test/resources/xml/xref.004.xml b/src/test/resources/xml/xref.004.xml index 3146f507d..098cd4cca 100644 --- a/src/test/resources/xml/xref.004.xml +++ b/src/test/resources/xml/xref.004.xml @@ -17,213 +17,143 @@ -
- Effectivity attributes and profiling -
- 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: - - - Common DocBook effectivity attributes - - - - 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 - - - -
-
-
- -
- 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 . - - - - - - - - - Value of xref/@xrefstyle - Result - Remark - - - - - - (@xrefstyle is absent) - - Default - - - %c - - Content, e. g. title of target - - - %l - - Label, ususally the targets number. - - - %label - - 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 for a - possible solution. - - - %label (%c) - - 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 %n - - XSLT 1.0 Legacy Syntax - - - template:the chapter called %t - - XSLT 1.0 Legacy Syntax - - - - -
- 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 and on page . + +
+ Customize individual cross references + + Most kinds of generated text apply across an entire document: do you want chapters + to be numbered? Should generated text be in English or French? What form should numbered + and unnumbered sections have? The mechanisms for changing this generated control the formatting + of cross references. + + But it’s sometimes desirable to be able to change the format of a + cross reference on an individual basis (that is, on the basis of the + context in which the reference occurs, not the + nature of what is referenced). You might, for + example, want to shorten a cross reference to just a label if it’s + already been referenced several times. + + Consider a cross reference to a section: + ]]>. + In the localization style of this guide, that is rendered like this: + see . - This cross reference to - on will include the target`s page number only when the - @profile.outputformat parameter is "print", but - without the annoying # in HTML. + The text that is generated by a cross reference can be customized + for individual references with the xrefstyle attribute. + For example, + ]]>, + will produce a result like this: + see . - - Use outputformat to deal with page numbers in cross references - This cross reference to - <xref linkend="syntax-highlighting" xrefstyle="%label/> - <phrase outputformat="print"> - on <xref linkend="syntax-highlighting" xrefstyle="page %p"/> - </phrase> - will reference the page number only when the @profile.outputformat parameter is print, - but without the annoying # in HTML. - + You can use the %c, %l and + %p values in + xrefstyle. 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 . + + + + + + + + + + Value of xref/@xrefstyle + Result + Remark + + + + + + (@xrefstyle is absent) + + Default + + + %c + + Content, e. g. title of target + + + %l + + Label, ususally the targets number. + + + %label + + The full Label, ususally the targets number and name. + + + %p + + Page number in print output (PDF). Displayed as “#” in HTML. + + + %label (%c) + + 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 + “Customizing + with an xrefstyle attribute / Using template:” in + the book “DocBook XSL: The Complete + Guide”. This is summarized in the following + table. + + + + + + + + + + Value of xref/@xrefstyle + Result + Remark + + + + + + template:the chapter numbered %n + + XSLT 1.0 Legacy Syntax + + + template:the chapter called %t + + XSLT 1.0 Legacy Syntax + + + +
-
+
Syntax highlighting - This section serves as xref target only. + + Program listings and other verbatim environments can be “syntax highlighted”, + that is, the significant tokens in the listing can be colored differently (keywords in red, + quoted strings in blue, that sort of thing). +
+