DocBook XSL Stylesheet Release Notes
DocBook Project Development Team
$Id: RELEASE-NOTES.xml,v 1.42 2005/08/11 23:27:13 xmldoc Exp $
2005-08-12
------------------------------------------------------------------------------
Table of Contents
Release 1.69.1
Release 1.69.0
Common
FO
Help
HTML
man
Release 1.68.1
Release 1.68.0
Release 1.67.2
Release 1.67.1
Release 1.67.0
Release 1.66.1
Release 1.65.0
Release 1.64.1
Release 1.61.0
Release 1.60.1
Release 1.59.2
Release 1.59.1
Release 1.58.0
Release 1.57.0
Release 1.56.0
Older releases
About dot-zero releases
These are the release notes for the DocBook XSL Stylesheets. At a minimum,
this file attempts to document changes to the public APIs, particularly to
user-configurable parameters. This file also provides a high-level overview of
the features added in each release.
Bug fixes are (mostly) not documented here. For a complete list of changes,
including descriptions of bug fixes, see the NEWS file, which is
auto-generated from the checkin descriptions for changes in the project CVS
repository.
Release 1.69.1
This release is a minor bug-fix update to the 1.69.0 release. Along with bug
fixes, it includes one configuration-parameter change: The default value of
the annotation.support parameter is now 0 (off). The reason for that change is
that there have been reports that annotation handling is causing a significant
performance degradation in processing of large documents with xsltproc.
Release 1.69.0
The release includes major feature changes, particularly in the manpages
stylesheets, as well as a large number of bug fixes.
As with all DocBook Project "dot zero" releases, this is an experimental
release .
Common
* This release adds localizations for the following languages: Albanian,
Amharic, Azerbaijani, Hindi, Irish (Gaelic), Gujarati, Kannada, Mongolian,
Oriya, Punjabi, Tagalog, Tamil, and Welsh.
* Added support for specifying number format for auto labels for chapter,
appendix, part, and preface. Contolled with the appendix.autolabel,
chapter.autolabel, part.autolabel, and preface.autolabel parameters.
* Added basic support for biblioref cross referencing.
* Added support for align on caption in mediaobject.
* Added support for processing documents that use the DocBook V5 namespace.
* Added support for termdef and mathphrase.
* EXPERIMENTAL: Incorporated the Slides and Website stylesheets into the
DocBook XSL stylesheets package. So, for example, Website documents can
now be processed using the following URI for the driver Website
tabular.xsl file:
http://docbook.sourceforge.net/release/xsl/current/website/tabular.xsl
* A procedure without a title is now treated as an "informal" procedure
(meaning that it is not added to any generated "list of procedures" and
has no affect on numbering of generated labels for other procedures).
* docname is no longer added to olink when pointing to a root element.
* Added support for generation of choice separator in inline simplelist.
This enables auto-generation of an appropriate localized "choice
separator" (for example, "and" or "or") before the final item in an inline
simplelist.
To indicate that you want a choice separator generated for a particular
list, you need to put a processing instruction (PI) of the form
as a child of the list. For example:
Choose from
ONE and ONLY ONE of the following:
A
B
C.
Output (for English):
Choose from ONE and only ONE of the following choices: A, B, or C.
As a temporary workaround for the fact that most of the DocBook
non-English locale files don't have a localization for the word "or", you
can put in a literal string to be used; example for French:
. That is, use "ou" instead of "or".
FO
* Added content-type property to external-graphic element, based on
imagedata format attribute.
* Added support for generating field for
XEP output. This makes the DocBook XSL stylesheet version information
available through the Document Properties menu in Acrobat Reader and other
PDF viewers.
* Trademark symbol handling made consistent with handling of same in HTML
stylesheets. Prior to this change, if you processed a document that
contained no value for the class attribute on the trademark element, the
HTML stylesheets would default to rendering a superscript TM symbol after
the trademark contents, but the FO stylesheets would render nothing.
* Added support for generating XEP bookmarks for refentry.
* Added support for HTML markup table border attribute, applied to each
table cell.
* The table.width template can now sum column specs if none use % or *.
* Added fox:destination extension inside fox:outline to support linking to
internal destinations.
* Added support for customizing abstract with property sets. Controlled with
the abstract.properties and abstract.title.properties parameters.
* Add footnotes in table title to table footnote set, and add support for
table footnotes to HTML table markup.
* Added support for title in glosslist.
* Added support for itemizedlist symbol none.
* Implemented the new graphical.admonition.properties and
nongraphical.admonition.properties attribute sets.
* Added id to formalpara and some other blocks that were missing it.
* Changed the anchor template to output fo:inline instead of fo:wrapper.
* Added support for toc.max.depth parameter.
Help
* Eclipse Help: Added support for generating olink database.
HTML
* Added a first cut at support in HTML output for DocBook 5 style
annotations. Controlled using the annotation.support parameter, and
implemented using JavaScript and CSS styling. For more details, see the
documentation for the annotation.js, annotation.css,
annotation.graphic.open, and annotation.graphic.close parameters.
* Generate client-side image map for imageobjectco with areas using calspair
units
* Added support for PI.
* Added support for passing img.src.path to DocBook Java XSLT image
extensions when appropriate. Controlled using the
graphicsize.use.img.src.path parameter.
* Added support for (not valid for DocBook 4) xlink:href on area and (not
valid for DocBook 4) alt in area.
* Added new parameter default.table.frame to control table framing if there
is no frame attribute on a table.
* Added initial, experimental support for generating content for the HTML
title attribute from content of the alt element. This change adds support
for the following inline elements only (none of them are block elements):
abbrev, accel, acronym, action, application, authorinitials, beginpage,
citation, citerefentry, citetitle, city, classname, code, command,
computeroutput, constant, country, database, email, envar, errorcode,
errorname, errortext, errortype, exceptionname, fax, filename, firstname,
firstterm, foreignphrase, function, glossterm, guibutton, guiicon,
guilabel, guimenu, guimenuitem, guisubmenu, hardware, honorific, interface
, interfacename, keycap, keycode, keysym, lineage, lineannotation, literal
, markup, medialabel, methodname, mousebutton, option, optional, otheraddr
, othername, package, parameter, personname, phone, pob, postcode,
productname, productnumber, prompt, property, quote, refentrytitle, remark
, replaceable, returnvalue, sgmltag, shortcut, state, street, structfield,
structname, subscript, superscript, surname, symbol, systemitem, tag,
termdef, token, trademark, type, uri, userinput, varname, and wordasword
* Added support for chunking revhistory into separate file (similar to the
support for doing same with legalnotice). Patch from Thomas Schraitle.
Controlled through new generate.revhistory.link parameter.
* l10n.xsl: Made language codes RFC compliant. Added a new boolean config
parameter, l10n.lang.value.rfc.compliant. If it is non-zero (the default),
any underscore in a language code will be converted to a hyphen in HTML
output. If it is zero, the language code will be left as-is.
man
This release closes out 44 manpages stylesheet bug reports and feature
requests. It adds more than 35 new configuration parameters for controlling
aspects of man-page output -- including hyphenation and justification,
handling of links, conversion of Unicode characters, and contents of man-page
headers and footers.
* New options for globally disabling/enabling hyphenation and justification:
man.justify and man.hyphenate.
Note that the default for the both of those is zero (off), because
justified text looks good only when it is also hyphenated; to quote the
"Hyphenation" node from the groff info page:
Since the odds are not great for finding a set of words, for every
output line, which fit nicely on a line without inserting excessive
amounts of space between words, `gtroff' hyphenates words so that it
can justify lines without inserting too much space between words.
The problem is that groff can end up hyphenating a lot of things that you
don't want hyphenated (variable names and command names, for example).
Keeping both justification and hyphenation disabled ensures that hyphens
won't get inserted where you don't want to them, and you don't end up with
lines containing excessive amounts of space between words. These default
settings run counter to how most existing man pages are formatted. But
there are some notable exceptions, such as the perl man pages.
* Added parameters for controlling hyphenation of computer inlines,
filenames, and URLs. By default, even when hyphenation is enabled
(globally), hyphenation is now suppressed for "computer inlines"
(currently, just classname, constant, envar, errorcode, option,
replaceable, userinput, type, and varname, and for filenames, and for URLs
from link. It can be (re)enabled using the man.hyphenate.computer.inlines,
man.hyphenate.filenames, and man.hyphenate.urls parameters.
* Implemented a new system for replacing Unicode characters. There are two
parts to the new system: a "string substitution map" for doing "essential"
replacements, and a "character map" that can optionally be disabled and
enabled.
The new system fixes all open bugs that had to do with literal Unicode
numbered entities such as “ and ” showing up in output, and
greatly expands the ability of the stylesheets to generate "good" roff
equivalents for Unicode symbols and special characters.
Here are some details...
The previous manpages mechanism for replacing Unicode symbols and special
characters with roff equivalents (the replace-entities template) was not
scalable and not complete. The mechanism handled a somewhat arbitrary
selection of less than 20 or so Unicode characters. But there are
potentially more than 800 Unicode special characters that have some groff
equivalent they can be mapped to. And there are about 34 symbols in the
Latin-1 (ISO-8859-1) block alone. Users might reasonably expect that if
they include any of those Latin-1 characters in their DocBook source
documents, they will get correctly converted to known roff equivalents in
output.
In addition to those common symbols, certain users may have a need to use
symbols from other Unicode blocks. Say, somebody who is documenting an
application related to math might need to use a bunch of symbols from the
"Mathematical Operators" Unicode block (there are about 65 characters in
that block that have reasonable roff equivalents). Or somebody else might
really like Dingbats -- such as the checkmark character -- and so might
use a bunch of things from the "Dingbat" block (141 characters in that
that have roff equivalents or that can at least be "degraded" somewhat
gracefully into roff).
So, the old replace-entities mechanism was replaced with a completely
different mechanism that is based on use of two "maps": a "substitution
map" and a "character map" (the latter in a format compliant with the XSLT
2.0 spec and therefore completely "forward compatible" with XSLT 2.0).
The substitution map is controlled through the man.string.subst.map
parameter, and is used to replace things like the backslash character
(which needs special handling to prevent it from being interpreted as a
roff escape). The substitution map cannot be disabled, because disabling
it will cause the output to be broken. However, you can add to it and
change it if needed.
The "character map" mechanism, on the other hand, can be completely
disabled. It is enabled by default, and, by default, does replacement of
all Latin-1 symbols, along with most special spaces, dashes, and quotes
(about 75 characters by default). Also, you can optionally enable a "full"
character map that provides support for converting all 800 or so of the
characters that have some reasonable groff equivalent.
The character-map mechanism is controlled through the following
parameters:
man.charmap.enabled
turns character-map support on/off
man.charmap.use.subset
specifies that a subset of the character map is used instead of the
full map
man.charmap.subset.profile
specifies profile of character-map subset
man.charmap.uri
specifies an alternate character map to use instead of the "standard"
character map provided in the distribution
* Implemented out-of-line handling of display of URLs for links (currently,
only for ulink). This gives you three choices for handling of links:
1. Number and list links. Each link is numbered inline, with a number in
square brackets preceding the link contents, and a numbered list of
all links is added to the end of the document.
2. Only list links. Links are not numbered, but an (unnumbered) list of
links is added to the end of the document.
3. Suppress links. Don't number links and don't add any list of links to
the end of the document.
You can also choose whether links should be underlined. The default is
"the works" -- list, number, and underline links. You can use the
man.links.list.enabled, man.links.are.numbered, and
man.links.are.underlined parameters to change the defaults. The default
heading for the link list is REFERENCES. You can be change that using the
man.links.list.heading parameter.
* Changed default output encoding to UTF-8. This does not mean that man
pages are output in raw UTF-8, because the character map is applied before
final output, causing all UTF-8 characters covered in the map to be
converted to roff equivalents.
* Added support for processing refsect3 and formalpara and nested refsection
elements, down to any arbitrary level of nesting.
* Output of the NAME and SYNOPSIS and AUTHOR headings and the headings for
admonitions (note, caution, etc.) are no longer hard-coded for English.
Instead, headings are generated for those in the correct locale (just as
the FO and HTML stylesheets do).
* Re-worked mechanism for assembling page headers/footers (the contents of
the .TH macro "title line").
Here are some details...
All man pages contain a .TH roff macro whose contents are used for
rendering the "title line" displayed in the header and footer of each
page. Here are a couple of examples of real-world man pages that have
useful page headers/footers:
gtk-options(7) GTK+ User's Manual gtk-options(7) <-- header
GTK+ 1.2 2003-10-20 gtk-options(7) <-- footer
svgalib(7) Svgalib User Manual svgalib(7) <-- header
Svgalib 1.4.1 16 December 1999 svgalib(7) <-- footer
And here are the terms with which the groff_man(7) man page refers to the
various parts of the header/footer:
title(section) extra3 title(section) <- header
extra2 extra1 title(section) <- footer
Or, using the names with which the man(7) man page refers to those same
fields:
title(section) manual title(section) <- page header
source date title(section) <- page footer
The easiest way to control the contents of those fields is to mark up your
refentry content like the following (note that this is a "minimal"
example).
2003-10-20 1
gtk-options 2
7 3
GTK+ 4
1.2 5
GTK+ User's Manual 6
gtk-options
Standard Command Line Options for GTK+ Programs
Description
This manual page describes the command line options, which
are common to all GTK+ based applications.
1 Sets the "date" part of the header/footer.
2 Sets the "title" part.
3 Sets the "section" part.
4 Sets the "source name" part.
5 Sets the "version" part.
6 Sets the "manual" part.
Below are explanations of the steps the stylesheets take to attempt to
assemble and display "good" headers and footer. [In the descriptions, note
that *info is the refentry "info" child (whatever its name), and
parentinfo is the "info" child of its parent (again, whatever its name).]
extra1 field (date)
Content of the "extra1" field is what shows up in the center footer
position of each page. The man(7) man page describes it as "the date
of the last revision".
To provide this content, if the refentry.date.profile.enabled is
non-zero, the stylesheets check the value of refentry.date.profile.
Otherwise, by default, they check for a date or pubdate not only in
the *info contents, but also in the parentinfo contents.
If a date cannot be found, the stylesheets now automatically generate
a localized "long format" date, ensuring that this field always has
content in output.
However, if for some reason you want to suppress this field, you can
do so by setting a non-zero value for man.th.extra1.suppress.
extra2 field (source)
On Linux systems and on systems with a modern groff, the content of
the "extra2" field are what shows up in the left footer position of
each page.
The man(7) man page describes this as "the source of the command", and
provides the following examples:
o For binaries, use somwething like: GNU, NET-2, SLS Distribution,
MCC Distribution.
o For system calls, use the version of the kernel that you are
currently looking at: Linux 0.99.11.
o For library calls, use the source of the function: GNU, BSD 4.3,
Linux DLL 4.4.1.
In practice, there are many pages that simply have a version number in
the "source" field. So, it looks like what we have is a two-part
field, Name Version, where:
Name
product name (e.g., BSD) or org. name (e.g., GNU)
Version
version name
Each part is optional. If the Name is a product name, then the Version
is probably the version of the product. Or there may be no Name, in
which case, if there is a Version, it is probably the version of the
item itself, not the product it is part of. Or, if the Name is an
organization name, then there probably will be no Version.
To provide this content, if the refentry.source.name.profile.enabled
and refentry.version.profile.enabled parameter are non-zero, the
stylesheets check the value of refentry.source.name.profile
refentry.version.profile.
Otherwise, by default, they check the following places, in the
following order:
1. *info/productnumber
2. *info/productnumber
3. refmeta/refmiscinfo[@class = 'version']
4. parentinfo/productnumber
5. *info/productname
6. parentinfo/productname
7. refmeta/refmiscinfo
8. [nothing found, so leave it empty]
extra3 field
On Linux systems and on systems with a modern groff, the content of
the "extra3" field are what shows up in the center header position of
each page. Some man pages have "extra2" content, some don't. If a
particular man page has it, it is most often "context" data about some
larger system the documented item belongs to (for example, the name or
description of a group of related applications). The stylesheets now
check the following places, in the following order, to look for
content to add to the "extra3" field.
1. parentinfo/title
2. parent's title
3. refmeta/refmiscinfo
4. [nothing found, so leave it empty]
* Reworked *info gathering. For each refentry found, the stylesheets now
cache its *info content, then check for any valid parent of it that might
have metainfo content and cache that, if found; they then then do all
further matches against those node-sets (rather than re-selecting the
original *info nodes each time they are needed).
* New option for breaking strings after forward slashes. This enables long
URLs and pathnames to be broken across lines. Controlled through
man.break.after.slash parameter.
* Output for servicemark and trademark are now (SM) and (TM). There is a
groff "\(tm" escape, but output from that is not acceptable.
* New option for controlling the length of the title part of the .TH title
line. Controlled through the man.th.title.max.length parameter.
* New option for specifying output encoding of each man page; controlled
with man.output.encoding (similar to the HTML chunker.output.encoding
parameter).
* New option for suppressing filename messages when generating output;
controlled with man.output.quietly (similar to the HTML chunk.quietly
parameter).
* The text of cross-references to first-level refentry (refsect1, top-level
refsection, refnamediv, and refsynopsisdiv) are now capitalized.
* Cross-references to refnamediv now use the localized NAME title instead of
using the first refname child. This makes the output inconsistent with
HTML and FO output, but for man-page output, it seems to make better sense
to have the NAME. (It may actually make better sense to do it that way in
HTML and FO output as well...)
* Added support for processing funcparams.
* Removed the space that was being output between funcdef and paramdef;
example: was: float rand (void); now: float rand(void)
* Turned off bold formatting for the type element when it occurs within a
funcdef or paramdef
* Corrected rendering of simplelist. Any
Invoke Saxon with the encoding.windows-1252 Java system property set
to com.nwalsh.saxon.Windows1252; for example
java \
-Dencoding.windows-1252=com.nwalsh.saxon.Windows1252 \
com.icl.saxon.StyleSheet \
mydoc.xml mystylesheet.xsl
Or, for a more complete "real world" case showing other options you'll
typically want to use:
java \
-Dencoding.windows-1252=com.nwalsh.saxon.Windows1252 \
-Djavax.xml.parsers.DocumentBuilderFactory=org.apache.xerces.jaxp.DocumentBuilderFactoryImpl \
-Djavax.xml.parsers.SAXParserFactory=org.apache.xerces.jaxp.SAXParserFactoryImpl \
-Djavax.xml.transform.TransformerFactory=com.icl.saxon.TransformerFactoryImpl \
com.icl.saxon.StyleSheet \
-x org.apache.xml.resolver.tools.ResolvingXMLReader \
-y org.apache.xml.resolver.tools.ResolvingXMLReader \
-r org.apache.xml.resolver.tools.CatalogResolver \
mydoc.xml mystylesheet.xsl
In both cases, the "mystylesheet.xsl" file should be a DocBook
customization layer containing the parameters show in step 2.
* Saxon extensions: Removed Saxon 8 extensions from release package
Release 1.67.0
* A number of important bug fixes, documented in WhatsNew.
* Added Saxon8 extensions
* Enabled dbfo table-width on entrytbl in FO output
* Added support for role=strong on emphasis in FO output
* Added new FO parameter hyphenate.verbatim that can be used to turn on
"intelligent" wrapping of verbatim environments.
* Replaced all output with