From: Michael Smith Date: Thu, 30 Jun 2005 13:22:10 +0000 (+0000) Subject: First updates for 1.69.0 release. X-Git-Tag: release/1.79.1~6^2~3351 X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=8cb596c50635ea44d9bed9d978cc4f8dfb0bc74e;p=docbook-dsssl First updates for 1.69.0 release. So far, only includes descriptions of the manpages changes. Sorry, that is all I could managed to get done so far. If anybody else has time to add descriptions for the HTML and FO stylesheets, please do. Otherwise, I will get back to work on them later tonight my time. --- diff --git a/xsl/RELEASE-NOTES.xml b/xsl/RELEASE-NOTES.xml index 2ad02c6fe..bea8a0509 100644 --- a/xsl/RELEASE-NOTES.xml +++ b/xsl/RELEASE-NOTES.xml @@ -7,18 +7,469 @@ $Id$ DocBook Project Development Team + These are the release notes for the DocBook XSL Stylesheets. At a minimum, this file attempts to document changes to the public - APIs. What, exactly, counts as a public API is still somewhat in - question, but it includes at least the global parameters. This file - also provides a high-level overview of the features added in each + 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 file, which is auto-generated from the checkin + url="NEWS"/> file, which is auto-generated from the checkin descriptions for changes in the project CVS repository. +
+ Release 1.69.0 + The release includes some major feature changes, + particularly in the manpages + stylesheets, as well as a large number of bug fixes. + +
+ man + + + New options for globablly 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 + "Hypenation" 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 is not particularly smart about how + it does hyphenation; it can end up hyphenating a lot of things + that you don't want hyphenated (variable names and command + names, for example), and it is difficult and tiresome work to + prevent it from doing that. So, disabling both justification + and hyphenation 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. Yes, + 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. + + + Implemented a new "character map" system for replacing + Unicode characters. This fixes all problems 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. + + The previous manpages mechanism for replacing Unicode + symbols and special characters with roff equivalents 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 convered 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 Unicode character-substitution mechanism was + replaced with a completely different character-substitution + mechanism that is based on use of a "character map" (in a + format compliant with the XSLT 2.0 spec and therefore + completely "forward compatible" with XSLT 2.0). By default, + the new "character map" mechanism does replacement of all + Latin-1 symbols, along with most special spaces, dashes, and + quotes (about 75 characters by default). And the "full" + character map included in the distribution provides support + for converting all 800 or so of the characters that have some + reasonable groff equivalent. + + The 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 + + + + + + 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 construction of .TH title + line. + + 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: + GIMP(1) GIMP Manual Pages GIMP(1) <-- header + Version 2.2.6 March 23 2004 GIMP(1) <-- footer + + QT2KDOC(1) KDOC Documentation System QT2KDOC(1) <-- header + 2.0a54 2002-03-18 QT2KDOC(1) <-- footer + + Notice that headers contain short descriptions of the + "context" for the item documented in the page ("GIMP Manual + Pages" and "KDOC Documentation System"), while the footers + contain application version information ("Version 2.2.6"), + along with a date in some from. + + Below are explanations of the steps the stylesheets + take to attempt to construct a "good" .TH + title line similar to the ones above. [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 + + Content of the "extra1" field is what shows up + in the center footer + position of each page. Almost all man pages have + content for this, and, almost universally, it is a + date. To provide this content, the stylesheets check + for a date or pubdate not only + in the *info contents, but + also in the parentinfo + contents. If a date cannot be found in the source, the + stylesheets now automatically generate a localized + "long format" date, ensuring that this field always + has content in output. + + + + "extra2" field + + 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. Some man + pages have "extra2" content, some don't. If a + particular man page has it, it is most often a version + number or product/application name. The stylesheets + now check the following places, in the following + order, to look for content to add to the "extra2" + field. + + + *info/productnumber + + + refmeta/refmiscinfo[@class = 'version'] + + + parentinfo/productnumber + + + *info/productname + + + parentinfo/productname + + + refmeta/refmiscinfo + + + [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. + + + parentinfo/title + + + parent's title + + + refmeta/refmiscinfo + + + [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 .THtitle 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 + <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 elswhere 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. + + + 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 + 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" ?> + <member>A</member> + <member>B</member> + <member>C</member>.</simplelist></para> + + 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". + + + 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. In output, that was causing anything marked up with + the quote element to be preceded by two backticks + and followed by two apostrophes -- that is, that old-school + hack 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 complete crap when viewed on a normal + tty/console. + + + 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 pages.) + + + New option for specifying "essential" character + replacements. Controlled through the + man.string.subst.map parameter. In + contast to the character-substitutions done via the optional + character-map mechanism, these are substitutions that are + always performed, because not performing + them will cause roff output to be broken or sub-optimal. An + example is replacement of backslashes, which must be doubled + to prevent them from being interpreted as roff escapes. + + + 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. + + + +
+
+ +
Release 1.68.1 The release adds localization support for Farsi (thanks to