1 DocBook XSL Stylesheet Release Notes
3 DocBook Project Development Team
9 ------------------------------------------------------------------------------
38 About dot-zero releases
40 These are the release notes for the DocBook XSL Stylesheets. At a minimum,
41 this file attempts to document changes to the public APIs, particularly to
42 user-configurable parameters. This file also provides a high-level overview of
43 the features added in each release.
45 Bug fixes are (mostly) not documented here. For a complete list of changes,
46 including descriptions of bug fixes, see the NEWS file, which is
47 auto-generated from the checkin descriptions for changes in the project CVS
52 This release is a minor bug-fix update to the 1.69.0 release. Along with bug
53 fixes, it includes one configuration-parameter change: The default value of
54 the annotation.support parameter is now 0 (off). The reason for that change is
55 that there have been reports that annotation handling is causing a significant
56 performance degradation in processing of large documents with xsltproc.
60 The release includes major feature changes, particularly in the manpages
61 stylesheets, as well as a large number of bug fixes.
63 As with all DocBook Project "dot zero" releases, this is an experimental
68 * This release adds localizations for the following languages: Albanian,
69 Amharic, Azerbaijani, Hindi, Irish (Gaelic), Gujarati, Kannada, Mongolian,
70 Oriya, Punjabi, Tagalog, Tamil, and Welsh.
72 * Added support for specifying number format for auto labels for chapter,
73 appendix, part, and preface. Contolled with the appendix.autolabel,
74 chapter.autolabel, part.autolabel, and preface.autolabel parameters.
76 * Added basic support for biblioref cross referencing.
78 * Added support for align on caption in mediaobject.
80 * Added support for processing documents that use the DocBook V5 namespace.
82 * Added support for termdef and mathphrase.
84 * EXPERIMENTAL: Incorporated the Slides and Website stylesheets into the
85 DocBook XSL stylesheets package. So, for example, Website documents can
86 now be processed using the following URI for the driver Website
89 http://docbook.sourceforge.net/release/xsl/current/website/tabular.xsl
91 * A procedure without a title is now treated as an "informal" procedure
92 (meaning that it is not added to any generated "list of procedures" and
93 has no affect on numbering of generated labels for other procedures).
95 * docname is no longer added to olink when pointing to a root element.
97 * Added support for generation of choice separator in inline simplelist.
98 This enables auto-generation of an appropriate localized "choice
99 separator" (for example, "and" or "or") before the final item in an inline
102 To indicate that you want a choice separator generated for a particular
103 list, you need to put a processing instruction (PI) of the form
104 <?dbchoice choice="foo"?> as a child of the list. For example:
107 ONE and ONLY ONE of the following:
108 <simplelist type="inline">
109 <?dbchoice choice="or" ?>
112 <member>C</member>.</simplelist></para>
114 Output (for English):
116 Choose from ONE and only ONE of the following choices: A, B, or C.
118 As a temporary workaround for the fact that most of the DocBook
119 non-English locale files don't have a localization for the word "or", you
120 can put in a literal string to be used; example for French:
121 <?dbchoice choice="ou">. That is, use "ou" instead of "or".
125 * Added content-type property to external-graphic element, based on
126 imagedata format attribute.
128 * Added support for generating <rx:meta-field creator="$VERSION"/> field for
129 XEP output. This makes the DocBook XSL stylesheet version information
130 available through the Document Properties menu in Acrobat Reader and other
133 * Trademark symbol handling made consistent with handling of same in HTML
134 stylesheets. Prior to this change, if you processed a document that
135 contained no value for the class attribute on the trademark element, the
136 HTML stylesheets would default to rendering a superscript TM symbol after
137 the trademark contents, but the FO stylesheets would render nothing.
139 * Added support for generating XEP bookmarks for refentry.
141 * Added support for HTML markup table border attribute, applied to each
144 * The table.width template can now sum column specs if none use % or *.
146 * Added fox:destination extension inside fox:outline to support linking to
147 internal destinations.
149 * Added support for customizing abstract with property sets. Controlled with
150 the abstract.properties and abstract.title.properties parameters.
152 * Add footnotes in table title to table footnote set, and add support for
153 table footnotes to HTML table markup.
155 * Added support for title in glosslist.
157 * Added support for itemizedlist symbol none.
159 * Implemented the new graphical.admonition.properties and
160 nongraphical.admonition.properties attribute sets.
162 * Added id to formalpara and some other blocks that were missing it.
164 * Changed the anchor template to output fo:inline instead of fo:wrapper.
166 * Added support for toc.max.depth parameter.
170 * Eclipse Help: Added support for generating olink database.
174 * Added a first cut at support in HTML output for DocBook 5 style
175 annotations. Controlled using the annotation.support parameter, and
176 implemented using JavaScript and CSS styling. For more details, see the
177 documentation for the annotation.js, annotation.css,
178 annotation.graphic.open, and annotation.graphic.close parameters.
180 * Generate client-side image map for imageobjectco with areas using calspair
183 * Added support for <?img.src.path?> PI.
185 * Added support for passing img.src.path to DocBook Java XSLT image
186 extensions when appropriate. Controlled using the
187 graphicsize.use.img.src.path parameter.
189 * Added support for (not valid for DocBook 4) xlink:href on area and (not
190 valid for DocBook 4) alt in area.
192 * Added new parameter default.table.frame to control table framing if there
193 is no frame attribute on a table.
195 * Added initial, experimental support for generating content for the HTML
196 title attribute from content of the alt element. This change adds support
197 for the following inline elements only (none of them are block elements):
198 abbrev, accel, acronym, action, application, authorinitials, beginpage,
199 citation, citerefentry, citetitle, city, classname, code, command,
200 computeroutput, constant, country, database, email, envar, errorcode,
201 errorname, errortext, errortype, exceptionname, fax, filename, firstname,
202 firstterm, foreignphrase, function, glossterm, guibutton, guiicon,
203 guilabel, guimenu, guimenuitem, guisubmenu, hardware, honorific, interface
204 , interfacename, keycap, keycode, keysym, lineage, lineannotation, literal
205 , markup, medialabel, methodname, mousebutton, option, optional, otheraddr
206 , othername, package, parameter, personname, phone, pob, postcode,
207 productname, productnumber, prompt, property, quote, refentrytitle, remark
208 , replaceable, returnvalue, sgmltag, shortcut, state, street, structfield,
209 structname, subscript, superscript, surname, symbol, systemitem, tag,
210 termdef, token, trademark, type, uri, userinput, varname, and wordasword
212 * Added support for chunking revhistory into separate file (similar to the
213 support for doing same with legalnotice). Patch from Thomas Schraitle.
214 Controlled through new generate.revhistory.link parameter.
216 * l10n.xsl: Made language codes RFC compliant. Added a new boolean config
217 parameter, l10n.lang.value.rfc.compliant. If it is non-zero (the default),
218 any underscore in a language code will be converted to a hyphen in HTML
219 output. If it is zero, the language code will be left as-is.
223 This release closes out 44 manpages stylesheet bug reports and feature
224 requests. It adds more than 35 new configuration parameters for controlling
225 aspects of man-page output -- including hyphenation and justification,
226 handling of links, conversion of Unicode characters, and contents of man-page
229 * New options for globally disabling/enabling hyphenation and justification:
230 man.justify and man.hyphenate.
232 Note that the default for the both of those is zero (off), because
233 justified text looks good only when it is also hyphenated; to quote the
234 "Hyphenation" node from the groff info page:
236 Since the odds are not great for finding a set of words, for every
237 output line, which fit nicely on a line without inserting excessive
238 amounts of space between words, `gtroff' hyphenates words so that it
239 can justify lines without inserting too much space between words.
241 The problem is that groff can end up hyphenating a lot of things that you
242 don't want hyphenated (variable names and command names, for example).
243 Keeping both justification and hyphenation disabled ensures that hyphens
244 won't get inserted where you don't want to them, and you don't end up with
245 lines containing excessive amounts of space between words. These default
246 settings run counter to how most existing man pages are formatted. But
247 there are some notable exceptions, such as the perl man pages.
249 * Added parameters for controlling hyphenation of computer inlines,
250 filenames, and URLs. By default, even when hyphenation is enabled
251 (globally), hyphenation is now suppressed for "computer inlines"
252 (currently, just classname, constant, envar, errorcode, option,
253 replaceable, userinput, type, and varname, and for filenames, and for URLs
254 from link. It can be (re)enabled using the man.hyphenate.computer.inlines,
255 man.hyphenate.filenames, and man.hyphenate.urls parameters.
257 * Implemented a new system for replacing Unicode characters. There are two
258 parts to the new system: a "string substitution map" for doing "essential"
259 replacements, and a "character map" that can optionally be disabled and
262 The new system fixes all open bugs that had to do with literal Unicode
263 numbered entities such as “ and ” showing up in output, and
264 greatly expands the ability of the stylesheets to generate "good" roff
265 equivalents for Unicode symbols and special characters.
267 Here are some details...
269 The previous manpages mechanism for replacing Unicode symbols and special
270 characters with roff equivalents (the replace-entities template) was not
271 scalable and not complete. The mechanism handled a somewhat arbitrary
272 selection of less than 20 or so Unicode characters. But there are
273 potentially more than 800 Unicode special characters that have some groff
274 equivalent they can be mapped to. And there are about 34 symbols in the
275 Latin-1 (ISO-8859-1) block alone. Users might reasonably expect that if
276 they include any of those Latin-1 characters in their DocBook source
277 documents, they will get correctly converted to known roff equivalents in
280 In addition to those common symbols, certain users may have a need to use
281 symbols from other Unicode blocks. Say, somebody who is documenting an
282 application related to math might need to use a bunch of symbols from the
283 "Mathematical Operators" Unicode block (there are about 65 characters in
284 that block that have reasonable roff equivalents). Or somebody else might
285 really like Dingbats -- such as the checkmark character -- and so might
286 use a bunch of things from the "Dingbat" block (141 characters in that
287 that have roff equivalents or that can at least be "degraded" somewhat
288 gracefully into roff).
290 So, the old replace-entities mechanism was replaced with a completely
291 different mechanism that is based on use of two "maps": a "substitution
292 map" and a "character map" (the latter in a format compliant with the XSLT
293 2.0 spec and therefore completely "forward compatible" with XSLT 2.0).
295 The substitution map is controlled through the man.string.subst.map
296 parameter, and is used to replace things like the backslash character
297 (which needs special handling to prevent it from being interpreted as a
298 roff escape). The substitution map cannot be disabled, because disabling
299 it will cause the output to be broken. However, you can add to it and
302 The "character map" mechanism, on the other hand, can be completely
303 disabled. It is enabled by default, and, by default, does replacement of
304 all Latin-1 symbols, along with most special spaces, dashes, and quotes
305 (about 75 characters by default). Also, you can optionally enable a "full"
306 character map that provides support for converting all 800 or so of the
307 characters that have some reasonable groff equivalent.
309 The character-map mechanism is controlled through the following
314 turns character-map support on/off
316 man.charmap.use.subset
318 specifies that a subset of the character map is used instead of the
321 man.charmap.subset.profile
323 specifies profile of character-map subset
327 specifies an alternate character map to use instead of the "standard"
328 character map provided in the distribution
330 * Implemented out-of-line handling of display of URLs for links (currently,
331 only for ulink). This gives you three choices for handling of links:
333 1. Number and list links. Each link is numbered inline, with a number in
334 square brackets preceding the link contents, and a numbered list of
335 all links is added to the end of the document.
337 2. Only list links. Links are not numbered, but an (unnumbered) list of
338 links is added to the end of the document.
340 3. Suppress links. Don't number links and don't add any list of links to
341 the end of the document.
343 You can also choose whether links should be underlined. The default is
344 "the works" -- list, number, and underline links. You can use the
345 man.links.list.enabled, man.links.are.numbered, and
346 man.links.are.underlined parameters to change the defaults. The default
347 heading for the link list is REFERENCES. You can be change that using the
348 man.links.list.heading parameter.
350 * Changed default output encoding to UTF-8. This does not mean that man
351 pages are output in raw UTF-8, because the character map is applied before
352 final output, causing all UTF-8 characters covered in the map to be
353 converted to roff equivalents.
355 * Added support for processing refsect3 and formalpara and nested refsection
356 elements, down to any arbitrary level of nesting.
358 * Output of the NAME and SYNOPSIS and AUTHOR headings and the headings for
359 admonitions (note, caution, etc.) are no longer hard-coded for English.
360 Instead, headings are generated for those in the correct locale (just as
361 the FO and HTML stylesheets do).
363 * Re-worked mechanism for assembling page headers/footers (the contents of
364 the .TH macro "title line").
366 Here are some details...
368 All man pages contain a .TH roff macro whose contents are used for
369 rendering the "title line" displayed in the header and footer of each
370 page. Here are a couple of examples of real-world man pages that have
371 useful page headers/footers:
373 gtk-options(7) GTK+ User's Manual gtk-options(7) <-- header
374 GTK+ 1.2 2003-10-20 gtk-options(7) <-- footer
376 svgalib(7) Svgalib User Manual svgalib(7) <-- header
377 Svgalib 1.4.1 16 December 1999 svgalib(7) <-- footer
379 And here are the terms with which the groff_man(7) man page refers to the
380 various parts of the header/footer:
382 title(section) extra3 title(section) <- header
383 extra2 extra1 title(section) <- footer
385 Or, using the names with which the man(7) man page refers to those same
388 title(section) manual title(section) <- page header
389 source date title(section) <- page footer
391 The easiest way to control the contents of those fields is to mark up your
392 refentry content like the following (note that this is a "minimal"
397 <date>2003-10-20</date> 1
400 <refentrytitle>gtk-options</refentrytitle> 2
401 <manvolnum>7</manvolnum> 3
402 <refmiscinfo class="source-name">GTK+</refmiscinfo> 4
403 <refmiscinfo class="version">1.2</refmiscinfo> 5
404 <refmiscinfo class="manual">GTK+ User's Manual</refmiscinfo> 6
407 <refname>gtk-options</refname>
408 <refpurpose>Standard Command Line Options for GTK+ Programs</refpurpose>
411 <title>Description</title>
412 <para>This manual page describes the command line options, which
413 are common to all GTK+ based applications.</para>
417 1 Sets the "date" part of the header/footer.
419 2 Sets the "title" part.
421 3 Sets the "section" part.
423 4 Sets the "source name" part.
425 5 Sets the "version" part.
427 6 Sets the "manual" part.
429 Below are explanations of the steps the stylesheets take to attempt to
430 assemble and display "good" headers and footer. [In the descriptions, note
431 that *info is the refentry "info" child (whatever its name), and
432 parentinfo is the "info" child of its parent (again, whatever its name).]
436 Content of the "extra1" field is what shows up in the center footer
437 position of each page. The man(7) man page describes it as "the date
438 of the last revision".
440 To provide this content, if the refentry.date.profile.enabled is
441 non-zero, the stylesheets check the value of refentry.date.profile.
443 Otherwise, by default, they check for a date or pubdate not only in
444 the *info contents, but also in the parentinfo contents.
446 If a date cannot be found, the stylesheets now automatically generate
447 a localized "long format" date, ensuring that this field always has
450 However, if for some reason you want to suppress this field, you can
451 do so by setting a non-zero value for man.th.extra1.suppress.
453 extra2 field (source)
455 On Linux systems and on systems with a modern groff, the content of
456 the "extra2" field are what shows up in the left footer position of
459 The man(7) man page describes this as "the source of the command", and
460 provides the following examples:
462 o For binaries, use somwething like: GNU, NET-2, SLS Distribution,
465 o For system calls, use the version of the kernel that you are
466 currently looking at: Linux 0.99.11.
468 o For library calls, use the source of the function: GNU, BSD 4.3,
471 In practice, there are many pages that simply have a version number in
472 the "source" field. So, it looks like what we have is a two-part
473 field, Name Version, where:
477 product name (e.g., BSD) or org. name (e.g., GNU)
483 Each part is optional. If the Name is a product name, then the Version
484 is probably the version of the product. Or there may be no Name, in
485 which case, if there is a Version, it is probably the version of the
486 item itself, not the product it is part of. Or, if the Name is an
487 organization name, then there probably will be no Version.
489 To provide this content, if the refentry.source.name.profile.enabled
490 and refentry.version.profile.enabled parameter are non-zero, the
491 stylesheets check the value of refentry.source.name.profile
492 refentry.version.profile.
494 Otherwise, by default, they check the following places, in the
497 1. *info/productnumber
499 2. *info/productnumber
501 3. refmeta/refmiscinfo[@class = 'version']
503 4. parentinfo/productnumber
507 6. parentinfo/productname
509 7. refmeta/refmiscinfo
511 8. [nothing found, so leave it empty]
515 On Linux systems and on systems with a modern groff, the content of
516 the "extra3" field are what shows up in the center header position of
517 each page. Some man pages have "extra2" content, some don't. If a
518 particular man page has it, it is most often "context" data about some
519 larger system the documented item belongs to (for example, the name or
520 description of a group of related applications). The stylesheets now
521 check the following places, in the following order, to look for
522 content to add to the "extra3" field.
528 3. refmeta/refmiscinfo
530 4. [nothing found, so leave it empty]
532 * Reworked *info gathering. For each refentry found, the stylesheets now
533 cache its *info content, then check for any valid parent of it that might
534 have metainfo content and cache that, if found; they then then do all
535 further matches against those node-sets (rather than re-selecting the
536 original *info nodes each time they are needed).
538 * New option for breaking strings after forward slashes. This enables long
539 URLs and pathnames to be broken across lines. Controlled through
540 man.break.after.slash parameter.
542 * Output for servicemark and trademark are now (SM) and (TM). There is a
543 groff "\(tm" escape, but output from that is not acceptable.
545 * New option for controlling the length of the title part of the .TH title
546 line. Controlled through the man.th.title.max.length parameter.
548 * New option for specifying output encoding of each man page; controlled
549 with man.output.encoding (similar to the HTML chunker.output.encoding
552 * New option for suppressing filename messages when generating output;
553 controlled with man.output.quietly (similar to the HTML chunk.quietly
556 * The text of cross-references to first-level refentry (refsect1, top-level
557 refsection, refnamediv, and refsynopsisdiv) are now capitalized.
559 * Cross-references to refnamediv now use the localized NAME title instead of
560 using the first refname child. This makes the output inconsistent with
561 HTML and FO output, but for man-page output, it seems to make better sense
562 to have the NAME. (It may actually make better sense to do it that way in
563 HTML and FO output as well...)
565 * Added support for processing funcparams.
567 * Removed the space that was being output between funcdef and paramdef;
568 example: was: float rand (void); now: float rand(void)
570 * Turned off bold formatting for the type element when it occurs within a
573 * Corrected rendering of simplelist. Any <simplelist type="inline" instance
574 is now rendered as a comma-separated list (also with an optional localized
575 "and" or "or" before the last item -- see description elsewhere in these
576 release notes). Any simplelist instance whose type is not inline is
577 rendered as a one-column vertical list (ignoring the values of the type
578 and columns attributes if present)
580 * Comment added at top of roff source for each page now includes DocBook XSL
581 stylesheets version number (as in the HTML stylesheets)
583 * Made change to prevent "sticky" fonts changes. Now, when the manpages
584 stylesheets encounter node sets that need to be boldfaced or italicized,
585 they put the \fBfoo\fR and \fIbar\fR groff bold/italic instructions
586 separately around each node in the set.
588 * synop.xsl: Boldface everything in funcsynopsis output except parameters
589 (which are in ital). The man(7) man page says:
591 For functions, the arguments are always specified using italics, even
592 in the SYNOPSIS section, where the rest of the function is specified
595 A look through the contents of the man/man2 directory shows that most
596 (all) existing pages do follow this "everything in funcsynopsis bold"
597 rule. That means the type content and any punctuation (parens, semicolons,
598 varargs) also must be bolded.
600 * Removed code for adding backslashes before periods/dots in roff source,
601 because backslashes in front of periods/dots in roff source are needed
602 only in the very rare case where a period is the very first character in a
603 line, without any space in front of it. A better way to deal with that
604 rare case is for you to add a zero-width space in front of the offending
605 dot(s) in your source
607 * Removed special handling of the quote element. That was hard-coded to
608 cause anything marked up with the quote element to be output preceded by
609 two backticks and followed by two apostrophes -- that is, that old-school
610 kludge for generating "curly" quotes in Emacs and in X-Windows fonts.
611 While Emacs still seems to support that, I don't think X-Windows has for a
612 long time now. And, anyway, it looks (and has always looked) like crap
613 when viewed on a normal tty/console. In addition, it breaks localiztion of
614 quote. By default, quote content is output with localized quotation marks,
615 which, depending on the locale, may or may not be left and right double
618 * Changed mappings for left and right single quotation marks. Those had
619 previously been incorrectly mapped to the backtick (`) and apostrophe
620 (&39;) characters (for kludgy reasons -- see above). They are now
621 correctly mapped to the \(oq and \(cq roff escapes. If you want the old
622 (broken) behavior, you need to manually change the mappings for those in
623 the value of the man.string.subst.map parameter.
625 * Removed xref.xsl file. Now, of the various cross-reference elements, only
626 the ulink element is handled differently; the rest are handled exactly as
627 the HTML stylesheets handle them, except that no hypertext links are
628 generated. (Because there is no equivalent hypertext mechanism is man
631 * New option for making "subheading dividers" in generated roff source. The
632 dividers are not visible in the rendered man page; they are just there to
633 make the source readable. Controlled using man.subheading.divider.
635 * Fixed many places where too much space was being added between lines.
639 The release adds localization support for Farsi (thanks to Sina Heshmati) and
640 improved support for the XLink-based DocBook NG db:link element. Other than
641 that, it is a minor bug-fix update to the 1.68.0 release. The main thing it
642 fixes is a build error that caused the XSLT Java extensions to be jarred up
643 with the wrong package structure. Thanks to Jens Stavnstrup for quickly
644 reporting the problem, and to Mauritz Jeanson for investigating and finding
649 This release includes some features changes, particularly for FO/PDF output,
650 and a number of bug fixes.
654 * Moved footnote properties to attribute-sets.
656 * Added support for side floats, margin notes, and custom floats.
658 * Added new parameters body.start.indent and body.end.indent to the
659 set.flow.properties template.
661 * Added support for xml:id
663 * Added support for refdescriptor.
665 * Added support for multiple refnamedivs.
667 * Added index.entry.properties attribute-set to support customization of
670 * Added set.flow.properties template call to each fo:flow to support
671 customizations entry point.
673 * Add support for @floatstyle in figure
675 * Moved hardcoded properties for index division titles to the
676 index.div.title.properties attribute-set.
678 * Added support for table-layout="auto" for XEP.
680 * Added index.div.title.properties attribute-set.
682 * $verbose parameter is now passed to most elements.
684 * Added refentry to toc in part, as it is permitted by the DocBook
687 * Added backmatter elements and article to toc in part, since they are
688 permitted by the DocBook schema/DTD.
690 * Added mode="toc" for simplesect, since it is now permitted in the toc if
691 simplesect.in.toc is set.
693 * Moved hard-coded properties to nongraphical.admonintion.properties and
694 graphical.admonition.properties attribute sets.
696 * Added support for sidebar-width and float-type processing instructions in
699 * For tables with HTML markup elements, added support for dbfo bgcolor PI,
700 the attribute-sets named table.properties, informaltable.properties,
701 table.table.properties, and table.cell.padding. Also added support for the
702 templates named table.cell.properties and table.cell.block.properties so
703 that tabstyles can be implemented. Also added support for tables
704 containing only tr instead of tbody with tr.
706 * Added new paramater hyphenate.verbatim.characters which can specify
707 characters after which a line break can occur in verbatim environments.
708 This parameter can be used to extend the initial set of characters which
709 contain only space and non-breakable space.
711 * Added itemizedlist.label.markup to enable selection of different bullet
712 symbol. Also added several potential bullet characters, commented out by
715 * Enabled all id's in XEP output for external olinking.
719 * Added support for refdescriptor.
721 * Added support for multiple refnamedivs.
723 * Added support for xml:id
725 * refsynopsisdiv as a section for counting section levels
729 * Added new SVG admonition graphics and navigation images.
733 This release fixes a table bug introduced in the 1.67.1 release.
737 This release includes a number of bug fixes; for details, see the WhatsNew
740 The following lists provide details about API and feature changes.
744 * Tables: Inherited cell properties are now passed to the
745 table.cell.properties template so they can be overridden by a
748 * Tables: Added support for bgcolor PI on table row element.
750 * TOCs: Added new parameter simplesect.in.toc; default value of 0 causes
751 simplesect to be omitted from TOCs; to cause simplesect to be included in
752 TOCs, you must set the value of simplesect.in.toc to 1.Comment from Norm:
754 Simplesect elements aren't supposed to appear in the ToC at all... The
755 use case for simplesect is when, for example, every chapter in a book
756 ends with "Exercises" or "For More Information" sections and you don't
757 want those to appear in the ToC.
759 * Sections: Reverted change that caused a variable reference to be used in a
760 template match and rewrote code to preserve intended semantics.
762 * Lists: Added workaround to prevent "* 0.60 + 1em" garbage in list output
765 * Moved the literal attributes from component.title to the
766 component.title.properties attribute-set so they can be customized.
768 * Lists: Added glossdef's first para to special handling in
773 * TOCs: Added new parameter simplesect.in.toc; for details, see the list of
774 FO changes for this release.
776 * Indexing: Added new parameter index.prefer.titleabbrev; when set to 1,
777 index references will use titleabbrev instead of title when available.
781 * Added support for generating windows-1252-encoded output using Saxon; for
782 more details, see the list of XSL Java extensions changes for this
787 * Replaced named/numeric character-entity references for non-breaking space
788 with groff equivalent (backslash-tilde).
792 * Saxon extensions: Added the Windows1252 class. It extends Saxon 6.5.x with
793 the windows-1252 character set, which is particularly useful when
794 generating HTML Help for Western European Languages (code from Pontus
795 Haglund and contributed to the DocBook community by Sectra AB, Sweden).
799 1. Make sure that the Saxon 6.5.x jar file and the jar file for the
800 DocBook XSL Java extensions are in your CLASSPATH
802 2. Create a DocBook XSL customization layer -- a file named
803 mystylesheet.xsl or whatever -- that, at a minimum, contains the
807 xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
809 <xsl:import href="http://docbook.sourceforge.net/release/xsl/current/htmlhelp/htmlhelp.xsl"/>
810 <xsl:output method="html" encoding="WINDOWS-1252" indent="no"/>
811 <xsl:param name="htmlhelp.encoding" select="'WINDOWS-1252'"></xsl:param>
812 <xsl:param name="chunker.output.encoding" select="'WINDOWS-1252'"></xsl:param>
813 <xsl:param name="saxon.character.representation" select="'native'"></xsl:param>
816 Invoke Saxon with the encoding.windows-1252 Java system property set
817 to com.nwalsh.saxon.Windows1252; for example
820 -Dencoding.windows-1252=com.nwalsh.saxon.Windows1252 \
821 com.icl.saxon.StyleSheet \
822 mydoc.xml mystylesheet.xsl
824 Or, for a more complete "real world" case showing other options you'll
825 typically want to use:
828 -Dencoding.windows-1252=com.nwalsh.saxon.Windows1252 \
829 -Djavax.xml.parsers.DocumentBuilderFactory=org.apache.xerces.jaxp.DocumentBuilderFactoryImpl \
830 -Djavax.xml.parsers.SAXParserFactory=org.apache.xerces.jaxp.SAXParserFactoryImpl \
831 -Djavax.xml.transform.TransformerFactory=com.icl.saxon.TransformerFactoryImpl \
832 com.icl.saxon.StyleSheet \
833 -x org.apache.xml.resolver.tools.ResolvingXMLReader \
834 -y org.apache.xml.resolver.tools.ResolvingXMLReader \
835 -r org.apache.xml.resolver.tools.CatalogResolver \
836 mydoc.xml mystylesheet.xsl
838 In both cases, the "mystylesheet.xsl" file should be a DocBook
839 customization layer containing the parameters show in step 2.
841 * Saxon extensions: Removed Saxon 8 extensions from release package
845 * A number of important bug fixes, documented in WhatsNew.
847 * Added Saxon8 extensions
849 * Enabled dbfo table-width on entrytbl in FO output
851 * Added support for role=strong on emphasis in FO output
853 * Added new FO parameter hyphenate.verbatim that can be used to turn on
854 "intelligent" wrapping of verbatim environments.
856 * Replaced all <tt></tt> output with <code></code>
858 * Changed admon.graphic.width template to a mode so that different
859 admonitions can have different graphical widths.
861 * Deprecated the HTML shade.verbatim parameter (use CSS instead)
863 * Wrapped ToC refentrytitle/refname and refpurpose in span with class
864 values. This makes it possible to style them using a CSS stylesheet.
866 * Use strong/em instead of b/i in HTML output
868 * Added support for converting Emphasis to groff italic and Emphasis
869 role='bold' to bold. Controlled by emphasis.propagates.style param, but
870 not documented yet using litprog system. Will do that next (planning to
871 add some other parameter-controllable options for hyphenation and handling
874 * callout.graphics.number.limit.xml param: Changed the default from 10 to
877 * verbatim.properties: Added hyphenate=false
879 * Saxon and Xalan Text.java extensions: Added support for URIResolver() on
882 * Added generated RELEASE-NOTES.txt file.
884 * Added INSTALL file (executable file for generating catalog.xml)
886 * Removed obsolete tools directory from package
890 * A number of important bug fixes, documented in WhatsNew.
892 * Now xml:base attributes that are generated by an XInclude processor are
893 resolved for image files.
895 * Rewrote olink templates to support several new features.
897 o Extended full olink support to FO output.
899 o Add support for xrefstyle attribute in olinks.
901 o New parameters to support new olink features: insert.olink.page.number
902 , insert.olink.pdf.frag, olink.debug, olink.lang.fallback.sequence,
903 olink.properties, prefer.internal.olink. See the reference page for
904 each parameter for more information.
906 * Added index.on.type parameter for new type attribute introduced in DocBook
907 4.3 for indexterms and index. This allows you to create multiple indices
908 containing different categories of entries. For users of 4.2 and earlier,
909 you can use the new parameter index.on.role instead.
911 * Added new section.autolabel.max.depth parameter to turn off section
912 numbering below a certain depth. This permits you to number major section
913 levels and leave minor section levels unnumbered.
915 * Added footnote.sep.leader.properties attribute set to format the line
916 separating footnotes in printed output.
918 * Added parameter img.src.path as a prefix to HTML img src attributes. The
919 prefix is added to whatever path is already generated by the stylesheet
922 * Added new attribute-sets informalequation.properties,
923 informalexample.properties, informalfigure.properties, and
924 informaltable.properties, so each such element type can be formatted
925 individually if needed.
927 * Add component.label.includes.part.label parameter to add any part number
928 to chapter, appendix and other component labels when the label.from.part
929 parameter is nonzero. This permits you to distinguish multiple chapters
930 with the same chapter number in cross references and the TOC.
932 * Added chunk.separate.lots parameter for HTML output. This parameter lets
933 you generate separate chunk files for each LOT (list of tables, list of
936 * Added several table features:
938 o Added table.table.properties attribute set to add properties to the
941 o Added placeholder templates named table.cell.properties and
942 table.cell.block.properties to enable adding properties to any
943 fo:table-cell or the cell's fo:block, respectively. These templates
944 are a start for implementing table styles.
946 * Added new attribute set component.title.properties for easy modifications
947 of component's title formatting in FO output.
949 * Added Saxon support for an encoding attribute on the textdata element.
950 Added new parameter textdata.default.encoding which specifies encoding
951 when encoding attribute on textdata is missing.
953 * Template label.this.section now controls whole section label, not only
954 sub-label which corresponds to particular label. Former behaviour was IMHO
955 bug as it was not usable.
957 * Formatting in titleabbrev for TOC and headers is preserved when there are
958 no hotlink elements in the title. Formerly the title showed only the text
959 of the title, no font changes or other markup.
961 * Added intial.page.number template to set the initial-page-number property
962 for page sequences in print output. Customizing this template lets you
963 change when page numbering restarts. This is similar to the
964 format.page.number template that lets you change how the page number
965 formatting changes in the output.
967 * Added force.page.count template to set the force-page-count property for
968 page sequences in print output. This is similar to the format.page.number
971 * Sort language for localized index sorting in autoidx-ng.xsl is now taken
972 from document lang, not from system environment.
974 * Numbering and formatting of normal and ulink footnotes (if turned on) has
975 been unified. Now ulink footnotes are mixed in with any other footnotes.
977 * Added support for renderas attribute in section and sect1 et al. This
978 permits you to render a given section title as if it were a different
981 * Added support for label attribute in footnote to manually supply the
984 * Added support for DocBook 4.3 corpcredit element.
986 * Added support for a dbfo keep-together PI for formal objects (table,
987 figure, example, equation, programlisting). That permits a formal object
988 to be kept together if it is not already, or to be broken if it is very
989 long and the default keep-together is not appropriate.
991 * For graphics files, made file extension matching case insensitive, and
992 updated the list of graphics extensions.
994 * Allow calloutlist to have block content before the first callout
996 * Added dbfo-need processing instruction to provide soft page breaks.
998 * Added implementation of existing but unused default.image.width parameter
1001 * Support DocBook NG tag inline element.
1003 * It appears that XEP now supports Unicode characters in bookmarks. There is
1004 no further need to strip accents from characters.
1006 * Make segmentedlist HTML markup more semantic and available to CSS styles.
1008 * Added user.preroot placeholder template to permit xsl-stylesheet and other
1009 PIs and comments to be output before the HTML root element.
1011 * Non-chunked legalnotice now gets an <a name="id"> element in HTML output
1012 so it can be referenced with xref or link.
1014 * In chunked HTML output, changed link rel="home" to rel="start", and link
1015 rel="previous" to rel="prev", per W3C HTML 4.01 spec.
1017 * Added several patches to htmlhelp from W. Borgert
1019 * Added Bosnian locale file as common/bs.xml.
1023 * A number of important bug fixes, documented in WhatsNew.
1025 * Added a workaround to allow these stylesheets to process DocBook NG
1026 documents. (Its a hack that pre-processes the document to strip off the
1027 namespace and then uses exsl:node-set to process the result.)
1029 * Added alternative indexing mechanism which has better internationalization
1030 support. New indexing method allows grouping of accented letters like e,
1031 , into the same group under letter "e". It can also treat special
1032 letters (e.g. "ch") as one character and place them in the correct
1033 position (e.g. between "h" and "i" in Czech language).
1035 In order to use this mechanism you must create customization layer which
1036 imports some base stylesheet (like fo/docbook.xsl, html/chunk.xsl) and
1037 then includes appropriate stylesheet with new indexing code
1038 (fo/autoidx-ng.xsl or html/autoidx-ng.xsl). For example:
1040 <xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
1043 <xsl:import href="http://docbook.sourceforge.net/release/xsl/current/fo/docbook.xsl"/>
1044 <xsl:include href="http://docbook.sourceforge.net/release/xsl/current/fo/autoidx-ng.xsl"/>
1048 New method is known to work with Saxon and it should also work with
1049 xsltproc 1.1.1 and later. Currently supported languages are English,
1050 Czech, German, French, Spanish and Danish.
1054 General bug fixes and improvements. Sorry about the failure to produce an
1055 updated release notes file for 1.62.01.63.2
1057 * In the course of fixing bug #849787, wrapping Unicode callouts with an
1058 appropriate font change in the Xalan extensions, I discovered that the
1059 Xalan APIs have changed a bit. So xalan2.jar will work with older Xalan 2
1060 implementations, xalan25.jar works with Xalan 2.5.
1064 Lots of bug fixes and improvements.
1066 * Initial support for timestamp PI. From now you can use <?dbtimestamp
1067 format="Y-m-d H:M:S"?> to get current datetime in your document. Added
1068 localization support for datetime PI
1070 * Added level 6 to test for section depth in section.level template so that
1071 section.title.level6.properties will be used for sections that are 6 deep
1072 or deeper. This should also cause a h6 to be created in html output.
1074 * Don't use SVG graphics if use.svg=0
1076 * Now uses number-and-title-template for sections only if section.autolabel
1079 * Added missing 'english-language-name' attribute to the l10n element, and
1080 the missing 'style' attribute to the template element so the current
1081 gentext documents will validate.
1083 * Corrected several references to parameter qanda.defaultlabel that were
1086 * Now accepts admon.textlabel parameter to turn off Note, Warning, etc.
1089 * FeatReq #684561: support more XEP metadata
1091 * Added hyphenation support. Added support for coref. Added beginpage
1092 support. (does nothing; see TDG).
1094 * Added support for hyphenation-character, hyphenation-push-character-count,
1095 and hyphenation-remain-character-count
1097 * Added root.properties, ebnf.assignment, and ebnf.statement.terminator
1099 * Support bgcolor PI in table cells; make sure rowsep and colsep don't have
1100 any effect on the last row or column
1102 * Handle othercredit on titlepage a little better
1104 * Applied fix from Jeff Beal that fixed the bug that put secondary page
1105 numbers on primary entries. Same with tertiary page numbers on secondary
1108 * Added definition of missing variable collection.
1110 * Make footnote formatting 'normal' even when it occurs in a context that
1111 has special formatting
1113 * Added warning when glossary.collection is not blank, but it cannot open
1116 * Pick up the frame attribute on table and informaltable.
1118 * indexdiv/title in non-autogenerated indexes are now picked up.
1120 * Removed (unused) component.title.properties
1122 * Move IDs from page-sequences down to titlepage blocks
1124 * Use proportional-column-width(1) on more tables.
1126 Use proportional-column-width() for header/footer tables; suppress
1127 relative-align when when using FOP
1129 * Check for glossterm.auto.link when linking firstterms; don't output gl.
1130 prefix on glossterm links
1132 * Generate Part ToCs
1134 * Support glossary, bibliography, and index in component ToCs.
1136 * Refactored chunking code so that customization of chunk algorithm and
1137 chunk elements is more practical
1139 * Support textobject/phrase on inlinemediaobject.
1141 * Support 'start' PI on ordered lists
1143 * Fixed test of $toc PI to turn on qandaset TOC.
1145 * Added process.chunk.footnotes to sect2 through 5 to fix bug of missing
1146 footnotes when chunk level greater than 1.
1148 * Added paramater toc.max.depth which controls maximal depth of ToC as
1149 requested by PHP-DOC group.
1151 * Exempted titleabbrev from preamble processing in lists, and fixed
1152 variablelist preamble code to use the same syntax as the other lists.
1154 * Added support for elements between variablelist and first varlistentry
1155 since DocBook 4.2 supports that now.
1161 * The format of the titlepage.templates.xml files and the stylesheet that
1162 transforms them have been significantly changed. All of the attributes
1163 used to control the templates are now namespace qualified. So what used to
1166 <t:titlepage element="article" wrapper="fo:block">
1170 <t:titlepage t:element="article" t:wrapper="fo:block">
1172 Attributes from other namespaces (including those that are unqualified)
1173 are now copied directly through. In practice, this means that the names
1174 that used to be "fo:" qualified:
1176 <title named-template="component.title"
1177 param:node="ancestor-or-self::article[1]"
1178 fo:text-align="center"
1179 fo:keep-with-next="always"
1180 fo:font-size="&hsize5;"
1181 fo:font-weight="bold"
1182 fo:font-family="{$title.font.family}"/>
1184 are now unqualified:
1186 <title t:named-template="component.title"
1187 param:node="ancestor-or-self::article[1]"
1189 keep-with-next="always"
1190 font-size="&hsize5;"
1192 font-family="{$title.font.family}"/>
1194 The t:titlepage and t:titlepage-content elements both generate wrappers
1195 now. And unqualified attributes on those elements are passed through. This
1196 means that you can now make the title font apply to ane entire titlepage
1197 and make the entire "recto" titlepage centered by specifying the font and
1198 alignment on the those elements:
1200 <t:titlepage t:element="article" t:wrapper="fo:block"
1201 font-family="{$title.font.family}">
1203 <t:titlepage-content t:side="recto"
1204 text-align="center">
1206 * Support use of titleabbrev in running headers and footers.
1208 * Added (experimental) xref.with.number.and.title parameter to enable
1209 number/title cross references even when the default would be just the
1212 * Generate part ToCs if they're requested.
1214 * Use proportional-column-width() in header/footer tables.
1216 * Handle alignment correctly when screenshot wraps a graphic in a figure.
1218 * Format chapter and appendix cross references consistently.
1220 * Attempt to support tables with multiple tgroups in FO.
1222 * Output fo:table-columns in simplelist tables.
1224 * Use titlepage.templates.xml for indexdiv and glossdiv formatting.
1226 * Improve support for new bibliography elements.
1228 * Added footnote.number.format, table.footnote.number.format,
1229 footnote.number.symbols, and table.footnote.number.symbols for better
1230 control of footnote markers.
1232 * Added glossentry.show.acronyms.
1234 * Suppress the draft-mode page masters when draft-mode is "no".
1236 * Make blank pages verso not recto. D'Oh!
1238 * Improved formatting of ulink footnotes.
1240 * Fixed bugs in graphic width/height calculations.
1242 * Added class attributes to inline elements.
1244 * Don't add ".html" to the filenames identified with the "dbhtml" PI.
1246 * Don't force a ToC when sections contain refentrys.
1248 * Make section title sizes a function of the body.master.size.
1252 The 1.59.2 fixes an FO bug in the page masters that causes FOP to fail.
1254 * Removed the region-name from the region-body of blank pages. There's no
1255 reason to give the body of blank pages a unique name and doing so causes a
1256 mismatch that FOP detects.
1258 * Output IDs for the first paragraphs in listitems.
1260 * Fixed some small bugs in the handling of page numbers in double-sided
1263 * Attempt to prevent duplicated IDs from being produced when endterm on xref
1264 points to something with nested structure.
1266 * Fix aligment problems in equations.
1268 * Output the type attribute on unordered lists (UL) in HTML only if the
1269 css.decoration parameter is true.
1271 * Calculate the font size in formal.title.properties so that it's 1.2 times
1272 the base font size, not a fixed "12pt".
1276 The 1.59.1 fixes a few bugs.
1278 * Added Bulgarian localization.
1280 * Indexing improvements; localize book indexes to books but allow setindex
1281 to index an entire set.
1283 * The default value for rowsep and colsep is now "1" as per CALS.
1285 * Added support for titleabbrev (use them for cross references).
1287 * Improvements to mediaobject for selecting print vs. online images.
1289 * Added seperate property sets for figures, examples, equations, tabless,
1292 * Make lineannotations italic.
1294 * Support xrefstyle attribute.
1296 * Make endterm on xref higher priority than xreflabel target.
1298 * Glossary formatting improvements.
1302 The 1.58.0 adds some initial support for extensions in xsltproc, adds a few
1303 features, and fixes bugs.
1305 * This release contains the first attempt at extension support for xsltproc.
1306 The only extension available to date is the one that adjusts table column
1307 widths. Run extensions/xsltproc/python/xslt.py.
1309 * Fixed bugs in calculation of adjusted column widths to correct for
1312 * Support nested refsection elements correctly.
1314 * Reworked gentext.template to take context into consideration. The name of
1315 elements in localization files is now an xpath-like context list, not just
1318 * Made some improvements to bibliography formatting.
1320 * Improved graphical formatting of admonitions.
1322 * Added support for entrytbl.
1324 * Support spanning index terms.
1326 * Support bibliosource.
1330 * The 1.57.0 release wasn't documented here. Oops.
1334 The 1.56.0 release fixes bugs.
1336 * Reworked chunking. This will break all existing customizations layers that
1337 change the chunking algorithm. If you're customizing chunking, look at the
1338 new "content" parameter that's passed to process-chunk-element and
1341 * Support continued and inherited numeration in orderedlist formatting for
1344 * Added Thai localization.
1346 * Tweaked stylesheet documentation stylesheets to link to TDG and the
1347 parameter references.
1349 * Allow title on tables of contents ("Table of Contents") to be optional.
1350 Added new keyword to generate.toc. Support tables of contents on sections.
1352 * Made separate parameters for table borders and table cell borders:
1353 table.frame.border.color, table.frame.border.style,
1354 table.frame.border.thickness, table.cell.border.color,
1355 table.cell.border.style, and table.cell.border.thickness.
1357 * Suppress formatting of "endofrange" indexterms. This is only half-right.
1358 They should generate a range, but I haven't figured out how to do that
1361 * Support revdescription. (Bug #582192)
1363 * Added default.float.class and fixed figure floats. (Bug #497603)
1365 * Fixed formatting of sbr in FOs.
1367 * Added context to the "missing template" error message.
1369 * Process arg correctly in a group. (Bug #605150)
1371 * Removed 'keep-with-next' from formal.title.properties attribute set now
1372 that the stylesheets support the option of putting such titles below the
1373 object. Now the $placement value determines if 'keep-with-next' or
1374 'keep-with-previous' is used in the title block.
1376 * Wrap "url()" around external-destinations when appropriate.
1378 * Fixed typo in compact list spacing. (Bug #615464)
1380 * Removed spurious hash in anchor name. (Bug #617717)
1382 * Address is now displayed verbatim on title pages. (Bug #618600)
1384 * The bridgehead.in.toc parameter is now properly supported.
1386 * Improved effectiveness of HTML cleanup by increasing the number of places
1387 where it is used. Improve use of HTML cleanup in XHTML stylesheets.
1389 * Support table of contents for appendix in article. (Bug #596599)
1391 * Don't duplicate footnotes in bibliographys and glossarys. (Bug #583282)
1393 * Added default.image.width. (Bug #516859)
1395 * Totally reworked funcsynopsis code; it now supports a 'tabular'
1396 presentation style for 'wide' prototypes; see
1397 funcsynopsis.tabular.threshold. (HTML only right now, I think, FO support,
1400 * Reworked support for difference marking; toned down the colors a bit and
1401 added a "system.head.content" template so that the diff CSS wasn't
1402 overriding "user.head.content". (Bug #610660)
1404 * Added call to the "*.head.content" elements when writing out long
1407 * Make sure legalnotice link is correct even when chunking to a different
1410 * Use CSS to set viewport characteristics if css.decoration is non-zero, use
1411 div instead of p for making graphic a block element; make figure titles
1412 the default alt text for images in a figure.
1414 * Added space-after to list.block.spacing.
1416 * Reworked section.level template to give "correct" answer instead of being
1419 * When processing tables, use the tabstyle attribute as the division class.
1421 * Fixed bug in html2xhtml.xsl that was causing the XHTML chunker to output
1422 HTML instead of XHTML.
1426 To view the release notes for older releases, see
1427 http://cvs.sourceforge.net/viewcvs.py/docbook/xsl/RELEASE-NOTES.xml. Be aware
1428 that there were no release notes for releases prior to the 1.50.0 release.
1430 About dot-zero releases
1432 DocBook Project "dot zero" releases should be considered experimental and are
1433 always followed by stable "dot one" releases, usually within two or three
1434 weeks. Please help to ensure the stability of "dot one" releases by carefully
1435 testing each "dot zero" release and reporting back about any problems you
1438 It is not recommended that you use a "dot zero" release in a production
1439 system, or package it for an OS distro. Instead, you should wait for the "dot
projects / apps / madmutt.git / blob