From 1919ec2bfd95f04591bc06dea4c3c1aa4147260a Mon Sep 17 00:00:00 2001 From: Frank Steimke Date: Thu, 31 Oct 2024 13:02:01 +0100 Subject: [PATCH] Correct the support for xref page with CSS --- src/guide/xml/ch02.xml | 39 +-- src/main/scss/media-all.scss | 5 - src/main/scss/media-paged.scss | 7 + src/main/scss/media-screen.scss | 2 +- src/main/xslt/modules/links.xsl | 2 +- src/test/resources/expected/xref.004.html | 61 ++-- src/test/resources/xml/xref.004.xml | 334 +++++++++------------- 7 files changed, 175 insertions(+), 275 deletions(-) diff --git a/src/guide/xml/ch02.xml b/src/guide/xml/ch02.xml index b2e1e4b20..833bc2f0f 100755 --- a/src/guide/xml/ch02.xml +++ b/src/guide/xml/ch02.xml @@ -1086,7 +1086,7 @@ xrefstyle="%c"/>. - + @@ -1122,10 +1122,7 @@ xrefstyle="%c"/>. %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). Not displayed in HTML. %label (%c) @@ -1149,7 +1146,7 @@ xrefstyle="%c"/>. - + @@ -1177,36 +1174,6 @@ 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. - -
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..660ed6c8b 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; +} \ No newline at end of file diff --git a/src/main/scss/media-screen.scss b/src/main/scss/media-screen.scss index 75abe198b..04743d78b 100644 --- a/src/main/scss/media-screen.scss +++ b/src/main/scss/media-screen.scss @@ -478,4 +478,4 @@ nav.top div { nav.bottom table .next { padding-right: 1rem; } -} +} \ No newline at end of file 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..01258d2c5 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). Not displayed 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..3bc547fbb 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). Not displayed 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). +
+