oreillymedia/HTMLBook — pull request #129 by sandersk (2014-04-16 22:57:43+00:00)
Title: Print URLs, admonition headings, EPUB 2 compatibility, and sidebar XREFs

Four key updates to the HTMLBook XSL stylesheets:

1. New core XSL handling for rendering `href` values for external hyperlinks separately in the output, which is useful for print outputs or any other medium in which clicking hyperlinks is not possible. Handling for rendering `href` URLs in output is enabled by setting the `url.in.parens` parameter to 1. When `url.in.parens` is enabled, markup like the following:

````html
Where EPUB semantics come up short, HTMLBook
falls back to DocBook semantics
````

Will be transformed by XSL to:

````html
Where EPUB semantics come up short, HTMLBook
falls back to DocBook (http://www.docbook.org/) semantics
````

The two classes on ``s ("print_url_in_parens" and "print_url") can be used for CSS styling.
Note that the logic in the XSL will compare the value of the hyperlink text node against the value of the `href`, and will not print out the URL in parens after if they both contain the same URL. In other words, the following markup:

```html
The HTMLBook spec can be found at http://oreillymedia.github.io/HTMLBook/
````

Will be left as is when the XSL is run, even when `url.in.parens` is enabled.

2. New parameter added called `add.title.heading.for.admonitions`. When this param is enabled, headings (`

`s) will be autogenerated for admonitions (`

`s with `data-type` of `note`, `tip`, `warning`, `caution`, or `important`) that do not have an `

`-`

` child already. For example, the following markup:

````html

Please take note of this important information.

````

Will be transformed to:

````html

Note

Please take note of this important information.

````

3. Improvements to handling triggered when `html4.structural.semantics` parameter is set to 1. Rather than convert `

`, `

`, and `

` directly to `

`, the handling now preserves the original HTML5 structural semantic element (for better accessibility in EPUB 3 readers) but adds a "fallback" `

` child that takes the `id` attribute to ensure intracontent hyperlinks and CSS styling work in reading systems (e.g., EPUB 2 readers) that do not support HTML5. For example, the following markup:

````

Chapter 1. HTMLBook Markup

This chapter describes...

````

Will be transformed to:

````

Chapter 1. Chapter 1. HTMLBook Markup

This chapter describes...

````

4. Added missing handling so that gentext for XREFs to `

` elements (e.g., sidebars) would generate properly.