diff --git a/src/guide/xml/ref-params.xml b/src/guide/xml/ref-params.xml index 846173224..36f59cd0a 100644 --- a/src/guide/xml/ref-params.xml +++ b/src/guide/xml/ref-params.xml @@ -5648,4 +5648,55 @@ in the online stylesheets (but might in the future). + + + + xs:string + titleabbrev-passthrough + 'true' + + + + Pass titleabbrev elements through to the HTML + + +Description + +The titleabbrev element allows an author to provide +an abbreviated title. This is used, for example, in the Table of +Contents and in other “lists of titles” (LoT). + +The actual titles of books, chapters, sections, etc. come from +the title element. But if downstream processing generates an LoT +dynamically, for example the on-page table of contents, +it’s useful to have access to the titleabbrev content. + +Unfortunately, HTML doesn’t provide an obvious mechanism to pass +content that should not be rendered. (Simply suppressing the content +with CSS is insufficient in this case because the abbreviated title +really shouldn’t appear even if CSS is not available.) The only element that won’t +render is the +script element. + +If this parameter is true, the rendered +titleabbrev content will be embedded in the header using a +script element. For example: + + +

+ The Adventures of + Buckaroo Banzai Across the 8th Dimension +

+]]> + +If it’s present, the on-page ToC feature will render the abbreviated title. +This parameter is true by default. Abbreviated titles are relatively uncommon +and the presence of extra script elements isn’t likely to be a problem. But if your +environment has hard requirements to avoid script elements, this feature can +be disabled by setting the parameter to “false”. + + + + diff --git a/src/main/web/js/pagetoc.js b/src/main/web/js/pagetoc.js index a227a657a..095cf9632 100644 --- a/src/main/web/js/pagetoc.js +++ b/src/main/web/js/pagetoc.js @@ -59,9 +59,13 @@ } const id = sect.getAttribute("id"); const header = sect.querySelector("header"); - const title = header && header.querySelector("h1,h2,h3,h4,h5,h6"); const skip = sect.classList.contains("nopagetoc"); + let title = header && header.querySelector("h1,h2,h3,h4,h5,h6"); + if (title.querySelector("script.titleabbrev")) { + title = title.querySelector("script.titleabbrev"); + } + if (title && !skip) { toclength++; sections.push({ diff --git a/src/main/xslt/modules/titles.xsl b/src/main/xslt/modules/titles.xsl index 52d3c8e2e..858cf934f 100644 --- a/src/main/xslt/modules/titles.xsl +++ b/src/main/xslt/modules/titles.xsl @@ -170,6 +170,21 @@ + + + + diff --git a/src/test/resources/expected/article.005.html b/src/test/resources/expected/article.005.html index 20789e03a..4da067337 100644 --- a/src/test/resources/expected/article.005.html +++ b/src/test/resources/expected/article.005.html @@ -7,14 +7,14 @@ Some text. Some text. Some text. Some text. Some text. Some text. Some text. Some text. Some text. Some text. Some text. Some text. Some text. Some text. Some text. Some text. Some text. Some text. -

2. Second Sect1

+

2. Second Sect1

The titleabbrev is set to SecondAbbrev. Ensure it's using the abbreviated title in the TOC.

Foo bar foo bar. Foo bar foo bar. Foo bar foo bar. Foo bar foo bar. Foo bar foo bar. Foo bar foo bar. Foo bar foo bar. Foo bar foo bar. Foo bar foo bar. Foo bar foo bar. -

3. Using Sect1Info

+

3. Using Sect1Info

The titleabbrev is set to Second1Info. Ensure it's using the abbreviated title in the TOC.

diff --git a/src/test/resources/expected/book.001.html b/src/test/resources/expected/book.001.html index 7033b169f..3c32c5945 100644 --- a/src/test/resources/expected/book.001.html +++ b/src/test/resources/expected/book.001.html @@ -140,7 +140,7 @@ aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt - mollit anim id est laborum.

Table of Contents

Chapter 1. First Chapter

Lorem ipsum dolor sit amet, consectetur adipiscing elit, + mollit anim id est laborum.

Table of Contents

Chapter 1. First Chapter

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis @@ -252,7 +252,7 @@ erat. Cras mollis scelerisque nunc. Nullam arcu. Aliquam consequat. Curabitur augue lorem, dapibus quis, laoreet et, pretium ac, nisi. Aenean magna nisl, mollis quis, molestie eu, - feugiat in, orci. In hac habitasse platea dictumst.

1. First Section

Lorem ipsum dolor sit amet, consectetur adipiscing elit, + feugiat in, orci. In hac habitasse platea dictumst.

1. First Section

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis diff --git a/src/test/resources/expected/fit.001.html b/src/test/resources/expected/fit.001.html index 17aabff06..6842a4abf 100644 --- a/src/test/resources/expected/fit.001.html +++ b/src/test/resources/expected/fit.001.html @@ -21,7 +21,7 @@ new (and better!) styles with CSS. You can also write stylesheet extensions to customize the markup, to add additional details to the header and footer, for example. -

Chapter 2. Persistent Table of Contents

The Persistent Table of Contents brings the document’s Table of +

Chapter 2. Persistent Table of Contents

The Persistent Table of Contents brings the document’s Table of Contents navigation hierarchy to every page. Clicking on the [toc] link in the upper right corner slides out the Table of Contents window diff --git a/src/test/resources/expected/fit.002.html b/src/test/resources/expected/fit.002.html index 750aa97f3..b342b80b0 100644 --- a/src/test/resources/expected/fit.002.html +++ b/src/test/resources/expected/fit.002.html @@ -21,7 +21,7 @@ new (and better!) styles with CSS. You can also write stylesheet extensions to customize the markup, to add additional details to the header and footer, for example. -

Chapter 2. Persistent Table of Contents

The Persistent Table of Contents brings the document’s Table of +

Chapter 2. Persistent Table of Contents

The Persistent Table of Contents brings the document’s Table of Contents navigation hierarchy to every page. Clicking on the [toc] link in the upper right corner slides out the Table of Contents window diff --git a/src/test/resources/expected/link.003.html b/src/test/resources/expected/link.003.html index 754964209..ffd3f514f 100644 --- a/src/test/resources/expected/link.003.html +++ b/src/test/resources/expected/link.003.html @@ -1,4 +1,4 @@ Article wrapper

Article wrapper

Table of Contents

1. Section Title

A self-referential link.

A link without content: Section 2, “Long Section Title”.

A link without content, but with an xreflabel: Section 2, “Long Section Title”.

A link with content and an xreflabel: -here.

2. A Very Long Section Title That I Don't Want To Use For My XRef

Some text with a link back to the +here.

2. A Very Long Section Title That I Don't Want To Use For My XRef

Some text with a link back to the first section.

\ No newline at end of file diff --git a/src/test/resources/expected/xref.003.html b/src/test/resources/expected/xref.003.html index fa0b6ee94..faa512674 100644 --- a/src/test/resources/expected/xref.003.html +++ b/src/test/resources/expected/xref.003.html @@ -1,4 +1,4 @@ -Unit Test: xref.003.xml

Unit Test: xref.003.xml

Adam Di Carlo

Table of Contents

1. Xref test: titleabbrev

+Unit 03Unit Test: xref.003.xml

Unit Test: xref.003.xml

Adam Di Carlo

Table of Contents

1. Xref test: titleabbrev

We're testing that xref uses the titleabbrev element where appropriate.

@@ -11,6 +11,6 @@ Example: Example 1, “Short Examp Title”.

Table: Table 1, “Short Table Title”. -

2. Cross-reference targets

+

2. Cross-reference targets

Targets for cross-reference tests. -

Bit of text

Figure 1. Long Title for Figure

Substance of example

Example 1. Long Title for Example
Table 1. Long Title for Table
table cell
\ No newline at end of file +

Bit of text

Figure 1. Long Title for Figure

Substance of example

Example 1. Long Title for Example
Table 1. Long Title for Table
table cell
\ No newline at end of file diff --git a/src/test/resources/expected/xref.004.html b/src/test/resources/expected/xref.004.html index c1df32ea1..e7c8926c9 100644 --- a/src/test/resources/expected/xref.004.html +++ b/src/test/resources/expected/xref.004.html @@ -1,4 +1,4 @@ -Unit 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 +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