OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.


Help: OASIS Mailing Lists Help | MarkMail Help

docbook-apps message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]

Subject: DocBook XSL 1.69.0 released

Version 1.69.0 of the DocBook XSL stylesheets is now available for
download from the DocBook Project site:


Note that the documentation is now packaged separately, in the
"docbook-xsl-doc" package.

The release notes are included below. HTML and PDF versions of the
release notes are also available:


This 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


  * 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:


  * 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

    To indicate that you want a choice separator generated for a particular
    list, you need to put a processing instruction (PI) of the form
    <?dbchoice choice="foo"?> as a child of the list. For example:

      <para>Choose from
      ONE and ONLY ONE of the following:
      <simplelist type="inline">
      <?dbchoice choice="or" ?>

    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:
    <?dbchoice choice="ou">. That is, use "ou" instead of "or".


  * Added content-type property to external-graphic element, based on
    imagedata format attribute.

  * Added support for generating <rx:meta-field creator="$VERSION"/> 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.


  * Eclipse Help: Added support for generating olink database.


  * 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

  * Added support for <?img.src.path?> 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.


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

    The new system fixes all open bugs that had to do with literal Unicode
    numbered entities such as &#8220; and &#8221; 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

    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


        turns character-map support on/off


        specifies that a subset of the character map is used instead of the
        full map


        specifies profile of character-map subset


        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

      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"

          <date>2003-10-20</date> 1
          <refentrytitle>gtk-options</refentrytitle> 2
          <manvolnum>7</manvolnum> 3
          <refmiscinfo class="source-name">GTK+</refmiscinfo> 4
          <refmiscinfo class="version">1.2</refmiscinfo> 5
          <refmiscinfo class="manual">GTK+ User's Manual</refmiscinfo> 6
          <refpurpose>Standard Command Line Options for GTK+ Programs</refpurpose>
          <para>This manual page describes the command line options, which
          are common to all GTK+ based applications.</para>

    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:


            product name (e.g., BSD) or org. name (e.g., GNU)


            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

        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 

  * New option for suppressing filename messages when generating output;
    controlled with man.output.quietly (similar to the HTML chunk.quietly

  * 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 <simplelist type="inline" instance
    is now rendered as a comma-separated list (also with an optional localized
    "and" or "or" before the last item -- see description elsewhere in these
    release notes). Any simplelist instance whose type is not inline is
    rendered as a one-column vertical list (ignoring the values of the type
    and columns attributes if present)

  * Comment added at top of roff source for each page now includes DocBook XSL
    stylesheets version number (as in the HTML stylesheets)

  * Made change to prevent "sticky" fonts changes. Now, when the manpages
    stylesheets encounter node sets that need to be boldfaced or italicized,
    they put the \fBfoo\fR and \fIbar\fR groff bold/italic instructions
    separately around each node in the set.

  * synop.xsl: Boldface everything in funcsynopsis output except parameters
    (which are in ital). The man(7) man page says:

        For functions, the arguments are always specified using italics, even
        in the SYNOPSIS section, where the rest of the function is specified
        in bold.

    A look through the contents of the man/man2 directory shows that most
    (all) existing pages do follow this "everything in funcsynopsis bold"
    rule. That means the type content and any punctuation (parens, semicolons,
    varargs) also must be bolded.

  * Removed code for adding backslashes before periods/dots in roff source,
    because backslashes in front of periods/dots in roff source are needed
    only in the very rare case where a period is the very first character in a
    line, without any space in front of it. A better way to deal with that
    rare case is for you to add a zero-width space in front of the offending
    dot(s) in your source

  * Removed special handling of the quote element. That was hard-coded to
    cause anything marked up with the quote element to be output preceded by
    two backticks and followed by two apostrophes -- that is, that old-school
    kludge for generating "curly" quotes in Emacs and in X-Windows fonts.
    While Emacs still seems to support that, I don't think X-Windows has for a
    long time now. And, anyway, it looks (and has always looked) like crap
    when viewed on a normal tty/console. In addition, it breaks localiztion of
    quote. By default, quote content is output with localized quotation marks,
    which, depending on the locale, may or may not be left and right double
    quotation marks.

  * Changed mappings for left and right single quotation marks. Those had
    previously been incorrectly mapped to the backtick (&#96;) and apostrophe
    (&39;) characters (for kludgy reasons -- see above). They are now
    correctly mapped to the \(oq and \(cq roff escapes. If you want the old
    (broken) behavior, you need to manually change the mappings for those in
    the value of the man.string.subst.map parameter.

  * Removed xref.xsl file. Now, of the various cross-reference elements, only
    the ulink element is handled differently; the rest are handled exactly as
    the HTML stylesheets handle them, except that no hypertext links are
    generated. (Because there is no equivalent hypertext mechanism is man

  * New option for making "subheading dividers" in generated roff source. The
    dividers are not visible in the rendered man page; they are just there to
    make the source readable. Controlled using man.subheading.divider.

  * Fixed many places where too much space was being added between lines.


[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]