From a77847df4f58f5a671d3142e18677fa47a57d08a Mon Sep 17 00:00:00 2001 From: Norman Walsh Date: Sat, 3 Feb 2024 10:37:04 +0000 Subject: [PATCH 1/3] Documentation fixes; discussion of Schematron for glossaries --- src/guide/resources/css/guide.css | 15 ++- src/guide/xml/ch03.xml | 187 +++++++++++++++++++--------- src/guide/xml/examples/glossary.sch | 25 ++++ 3 files changed, 164 insertions(+), 63 deletions(-) create mode 100644 src/guide/xml/examples/glossary.sch diff --git a/src/guide/resources/css/guide.css b/src/guide/resources/css/guide.css index 7cc8d4b686..eda29e3c6b 100644 --- a/src/guide/resources/css/guide.css +++ b/src/guide/resources/css/guide.css @@ -73,10 +73,8 @@ p .refpurpose-sep { .informalfigure { border: 2px solid #afafaf; border-radius: 1em; - margin-left: 2em; padding-left: 1em; padding-right: 1em; - margin-right: 2em; } .informalfigure .imageobject { @@ -93,11 +91,10 @@ img { .figure { border: 2px solid #afafaf; + border-radius: 0.5em; border-radius: 1em; - margin-left: 2em; padding-left: 1em; padding-right: 1em; - margin-right: 2em; } .figure table { @@ -111,10 +108,16 @@ img { .example { border: 2px solid #afafaf; - margin-left: 2em; + border-radius: 0.5em; padding-left: 1em; padding-right: 1em; - margin-right: 2em; +} + +.example > .programlisting > .pre-wrap, +.example > .programlistingco > .pre-wrap, +.example > .pre-wrap { + margin-top: 0; + padding-top: 0; } .funcname, diff --git a/src/guide/xml/ch03.xml b/src/guide/xml/ch03.xml index 7b3b0ba14a..0612d09310 100644 --- a/src/guide/xml/ch03.xml +++ b/src/guide/xml/ch03.xml @@ -190,7 +190,7 @@ is included. --> If persistent-toc is -true +true a link to the persistent-toc-css stylesheet is included. @@ -288,7 +288,7 @@ audio clip as ../../media/spinning-top.mp4. mo-4 The XML files are still in different directories, but the significant change -here is that the media are in their own hierarchy. +here is that the media are in their own hierarchy. Media references in the source use URIs relative to the root of that hierarchy: book/front/preface.xml refers to the “this is a test” audio clip as spinning-top.mp4. @@ -487,7 +487,7 @@ with the addition of one more parameter: mediaobject-grouped-by-type = "true" -In each case, this adds the extra “media object type” level to the +In each case, this adds the extra “media object type” level to the URI path. @@ -615,7 +615,7 @@ in uncommon cases. sect4, sect5, simplesect. -The refentry section elements are not included because they are +The refentry section elements are not included because they are not typically numbered. @@ -646,7 +646,7 @@ only counts as a formal object if it has a title. sections-number-from, and formal-objects-number-from. In each case, the value of the parameter must be the name of one of the categories. Sets and books -can only number from sets, divisions can number from sets or books, +can only number from sets, divisions can number from sets or books, components can number from sets, books, or divisions, etc. It is also possible to specify the value root to indicate that elements in the relevant category are numbered sequentially through the whole document. @@ -679,55 +679,90 @@ This most closely reproduces the numbering from the 1.x stylesheets. Using glossaries There are essentially two ways to manage glossaries: you can -author them by hand, or you can build them automatically from a +author them by hand, or you can compose them automatically from a collection of glossary entries. -If you build them by hand, if you put glossary elements containing -glossentry elements, etc. in your document, then you have complete control. -What you put in your document is what will be formatted and published. - -If you compose them from glossary collections, only the terms used in your document -(in glossterm or firstterm elements) will appear in the glossary. -The glossary collections can be managed internally or externally. -If multiple definitions appear in the glossary collections, only the first definition -is included. - - The best way to explain automatic glossaries is to use an example. Let's assume that you - have marked the two terms Apple and Pear in your document, so that your automatic glossary should ultimately contain - exactly two entries for these two terms. Create a glossary with - @role='auto' in your document. We call this the internal - glossary. - - - If your internal glossary has three entries for Apple, - Jackfruit and Pear, you will end up with a - glossary in the generated document that has only the two entries for - Apple and Pear. There will be no entry for - Jackfruit, since there is no corresponding glossterm - or firstterm in the main part of your text. - - - You can also use external glossaries for this task, which can be referenced by the use - of the glossary-collection transformation parameter, or the - db processing instruction with a glossary-collection pseudo - attribute. You can leave the internal, automatic glossary completely empty. As long as - there are entries for Apple and Pear in one of - your external gloassries, you will end up with these two entries in the generated - glossary, no matter how much more entries the external glossaries may contain. - - - You can use the internal, automatic glossary in conjunction with external glossaries. - In this case, entries from the internal glossary take precedence over entries for the same - term from external glossaries. Lets say you have entries for Apple - and Pear among others in your external glossary, and also an - glossentry for Apple in your internal glossary. In - this case you will end up with a glossary which contains two entries, one for - Apple with the specific definition taken from the internal - glossary, and one for Pear from the external glossary, which may be a - more general definition. - - +In a glossary authored by hand, no special processing +takes place. The entries appear as they are listed and every entry appears +whether there is a corresponding glossary reference in the document or not. +The author is free to use glossdiv elements +to divide the glossary into sections and the document may have multiple +glossary elements. + +If you compose them from glossary collections, only the terms +used in your document (in glossterm or firstterm +elements) will appear in the glossary. The glossary collections can be +managed internally or externally. If multiple definitions appear in +the glossary collections, only the first definition is +included. + +The best way to explain automatic glossaries is to use an +example. Let's assume that you have marked the two terms +Apple and +Pear as glossterms in your document. +Your automatic glossary should ultimately contain exactly two entries, +one for each of those terms. + +Create a glossary in your document and add auto to the +role attribute on the glossary element. +(If you’re using automatic glossaries, there should only be one glossary +element in your document.) This is the internal glossary. + + + +Even if your internal glossary has three entries, one each for Apple, +Jackfruit and Pear, you will end up with a +glossary in the generated document that has only two entries. There will be no entry for +Jackfruit, since there is no corresponding glossterm +or firstterm in the main part of your text. + + +You can also use external glossaries for +this task, which can be identified by the +glossary-collection parameter, or the +dbdb processing instruction + processing instructions with a +glossary-collection +db processing instruction +glossary-collection pseudo-attribute + pseudo-attribute in the root element. +If you use external glossaries, you can leave the internal, +automatic glossary completely empty. As long as there are entries for +Apple and Pear in one of +your external glossaries, you will end up with those two entries in +the generated glossary, even if the external glossaries contain many +more terms. + + + +You can use the internal, automatic glossary in conjunction with +external glossaries. In this case, entries from the internal glossary +take precedence over entries for the same term from external +glossaries. Lets say you have entries for Apple +and Pear among others in your external glossary, +and also a glossentry for Apple in +your internal glossary. In this case you will end up with a glossary +which contains two entries, one for Apple, with +the definition taken from the internal glossary, and one for +Pear with a definition from the +external glossary. + + + + +Entries will appear in the glossary in the same order as they appear in the +internal and external glossaries unless they are sorted. Sorting is controlled +by the glossary-sort-entries parameter. + +An automatic glossary may have glossary divisions. Those are +controlled by the glossary-automatic-divisions +parameter. + +
+ +Using Schematron +Using Schematron to manage the glossary + Schematron rules can help manage the glossary. The f:glossentries function (defined in @@ -737,10 +772,45 @@ Schematron independently of the xslTNG stylesheets. You can use it to check whether a corresponding glossentry exists for a glossterm or firstterm while you are still writing. Corresponding Schematron schemas are not yet part of the -xslTNG framework. - -Generating glossary divisions automatically is controlled by the -glossary-automatic-divisions parameter. +xslTNG framework. , however, +shows how you could use schematron to check whether there is exactly one glossentry +for the glossterm and firstterm elements in your document. + + + A Schematron schema to check glossary terms + + + + + + + + + Include the standalone-functions.xsl file. + You have to adjust the path accordingly. + Provide declaration for the namespace of functions from xslTNG. + Use the f:glossentries function + to get the number of matching glossentry elements for the given glossterm or firstterm + + + + +If you want to use Schematron rules with external glossaries, +it’s most convenient to use the db processing instruction +to identify the external glossaries. The +f:glossentries function will load them automatically (see ). + + + + Pass the <literal>glossary-collection</literal> parameter to Schematron + <article xmlns="http://docbook.org/ns/docbook" version="5.0"> + <?db glossary-collection='resources/glosscollection.xml' ?> + <title>My document</title> + … +</article> + +
@@ -833,7 +903,7 @@ to divide the bibliography into sections and the document may have multiple Automatic An automatic bibliography is selected by using the token -auto in the role attribute on a bibliography. +auto in the role attribute on a bibliography. Placeholders can still be used, but they are unnecessary when using citation for citations. @@ -855,7 +925,10 @@ divisions.
+ Creating something completely different +Something completely different + Your input documents go through several pre-processing steps before they are rendered into HTML. If you want to produce completely diff --git a/src/guide/xml/examples/glossary.sch b/src/guide/xml/examples/glossary.sch new file mode 100644 index 0000000000..41828ff02e --- /dev/null +++ b/src/guide/xml/examples/glossary.sch @@ -0,0 +1,25 @@ + + + + + + + + + + + + + No entry for + in glossary. + + + entries for in glossary. + + + + + \ No newline at end of file From 511d916297bff48d935162f87f6f5f96a2147b57 Mon Sep 17 00:00:00 2001 From: Norman Walsh Date: Sat, 3 Feb 2024 10:37:16 +0000 Subject: [PATCH 2/3] Added support for titleabbrev-passthrough --- src/guide/xml/ref-params.xml | 51 ++++++++++++++++++++ src/main/web/js/pagetoc.js | 6 ++- src/main/xslt/modules/titles.xsl | 15 ++++++ src/test/resources/expected/article.005.html | 4 +- src/test/resources/expected/book.001.html | 4 +- src/test/resources/expected/fit.001.html | 2 +- src/test/resources/expected/fit.002.html | 2 +- src/test/resources/expected/link.003.html | 2 +- src/test/resources/expected/xref.003.html | 6 +-- src/test/resources/expected/xref.004.html | 2 +- 10 files changed, 82 insertions(+), 12 deletions(-) diff --git a/src/guide/xml/ref-params.xml b/src/guide/xml/ref-params.xml index 846173224a..36f59cd0ae 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 a227a657ad..095cf9632a 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 52d3c8e2ed..858cf934f6 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 20789e03a5..4da0673378 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 7033b169f4..3c32c59453 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 17aabff062..6842a4abfe 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 750aa97f3c..b342b80b0a 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 754964209e..ffd3f514f1 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 fa0b6ee943..faa512674d 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 c1df32ea1b..e7c8926c93 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 From 3497667d3e29d561934dc71588320666be09d868 Mon Sep 17 00:00:00 2001 From: Norman Walsh Date: Sat, 3 Feb 2024 10:37:22 +0000 Subject: [PATCH 3/3] Bump XML Resolver version (still on 5.x for this release) --- properties.gradle | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/properties.gradle b/properties.gradle index dc7a8e6a67..90bd04aafa 100644 --- a/properties.gradle +++ b/properties.gradle @@ -17,6 +17,6 @@ ext { metadataExtractorVersion = '2.18.0' jingVersion = '20220510' - xmlresolverVersion = '5.2.0' + xmlresolverVersion = '5.2.3' sincludeVersion = '5.2.4' }