Changes to the Modular DocBook Stylesheet This document summarizes the changes made to the Modular DocBook HTML Stylesheet prior to version 1.12. Subsequent versions are documented in ChangeLog Version 1.11, 18 Aug 1998 Modified presentation of ClassName, Function, Citation, and Email. I think these are improvements. Set and Part TOCs are now generated by default. Version 1.10, 31 Jul 1998 Renamed %html-meta-tags% to %html-header-tags% and changed the list format. Added %link-mailto-url%. If not #f, a REL="made" LINK will be added to the HEAD of each HTML file with HREF set to %link-mailto-url%. Added %css-decoration%. If true, then the stylesheets will add inline CSS styles where necessary. At the moment, this is only in handling of list items with unsupported MARK attributes (e.g. “none”) or OVERRIDE attributes. Added %css-liststyle-alist% to map the list style names used in the MARK or OVERRIDE attributes on ItemizedList to the appropriate HTML names. For example, bullet maps to disc in HTML. Changed meaning of (nav-home); it now returns the node which is the home page. The old behavior is now provided by (nav-home-link). Fixed bug in CalloutList handling where Area, AreaSpec, and AreaSet incorrectly produced Ps. Fixed bug in handling of CLASS attribute on footnote DIVs. Reworked support for elements in the HEAD. The stylesheets now automatically produce META elements for keywords and LINK elements for navigation. The functions and parameters used to produce information in the head have been renamed. Use the %html-header-tags% list to add elements to the HEAD or redefine ($user-html-header$) . Redefine ($standard-html-header$) to remove/modify the standard header tags. Added better support for OVERRIDE and MARK on ItemizedLists. Some support requires %css-decoration%. Added DIVs around the navigation elements on each page with an appropriate CLASS. In the non-tabular navigation setup, I changed the order of “Next” and “Previous” so that it's a little easier to use with Lynx (“Next” is now the default link, which makes more sense). Fixed bug in formatting of Procedures. Fixed bug in formatting of tables with missing entries at the end of a row. Version 1.09, 19 Jul 1998 Added SPAN wrapper around inlines with a CLASS attribute that indicates the GI of the original element. This makes the resulting HTML documents more amenable to CSS stylesheets. Made output of <sgmltag class="element"> switch to Courier. Fixed bug which caused Footnotes to be lost in CalloutLists Fixed bug in calculation of component names when %use-id-as-filename% is true. Added ($html-body-start$), ($html-body-content-start$) , ($html-body-content-end$), and ($html-body-end$) . These functions can be redefined to add content to the top and bottom of every HTML document generated. Added %html-manifest% parameter. The complete list of files generated by the stylesheet is written to this file. Changed the default doctype to "-//W3C//DTD HTML 4.0 Transitional//EN". The HTML resulting from these stylesheets is not always completely legal because DocBook allows block elements in paragraphs and HTML does not, but the resulting HTML is closer to the transitional 4.0 DTD. Changed the default CSS stylesheet to #f. Fixed bug in %funcsynopsis-decoration% where multiple Parameters were not comma separated. Fixed bug in handling of graphics on title pages. Tinkered with title pages. Version 1.08, 12 Jun 1998 Added support for formatting an Index. Note: This does not include support for building an index from IndexTerm tags; only for formatting an index coded in SGML. And even that support's not great. Added hooks for printing out section-level “titlepages”. Output IDs on informal objects. Fixed bug in processing of Article titlepages. Fixed bug in formatting of SegmentedLists. Fixed bug in construction of HTML filename when an html-basename PI is used. Version 1.08beta8, 13 May 1998 Sweeping changes to make it possible to use these stylesheets with both SGML and XML instances. All element names have been lowercased and most strings are now (normalized "") before comparisons. A number of variables are now functions because normalization can only occur after a (current-node) exists. RefSect*'s are never auto-numbered. Version 1.08beta7, 06 May 1998 Completely rewrote support for title pages. Title pages are now supported on all division— and component-level elements. Title pages are now supported on Articles, for example. Added support for PubDate in BiblioEntrys. If PubDate is present, it will be used. Otherwise the Year in the Copyright will be used. Added French localization. Fixed spacing around footnote references. The system identifier of a graphic file referenced by EntityRef is now subject to the same processing as FileRef. Added %stylesheet% and %stylesheet-type% to support an HTML LINK to a stylesheet. Added $html-header-tags$ to support complete customization of the HTML HEAD elements. Fixed Chapter/Appendix numbering in the navigation context string in headers. I think I had the distinction between ANSI and K&R style function synopsis backwards. So I reversed it. Added %funcsynopsis-decoration% to control whether or not the elements in a FuncSynopsis should be decorated (return types bold, parameters italic, etc.). Removed %generate-titlepage%. Added %generate-element-titlepage% for Set, Book, Part, Reference, and Article. Replaced %generate-toc% with %generate-element-toc% Replaced %generate-lot-list% with %generate-element-lot-list% Added %titlepage-in-info-order%. If true, then the elements on a generated titlepage occur in the order that they appear in the corresponding *Info element. Otherwise, they appear in a fixed (but configurable) order specified by the stylesheet. Added %generate-part-toc-on-titlepage% and %generate-reference-toc-on-titlepage%. If true then the TOC for Parts and References occur on the title page for those elements, otherwise they appear on a page sequence following the title page. Added %generate-partinfo-on-titlepage%. If true then the contents of the PartIntro element occurs on the title page of the containing element (Part or Reference). Added html-filenames to all the REFENTRY comments in the prparam.dsl file so that they can be propagated to the documentation. I'm basically sacraficing any attempt at maintaining 8.3 filenames in the documentation in favor of consistent filenames. Since switching to all-element-number, the filenames for the RefEntrys change completely with every release which is a bit of a maintainance headache. Fixed bug in dbtable.dsl; changed (make paragraph) to (make element gi: "P"). Added semicolons between multiple SubTitles. Changed legalnotice-link-file to a function (rather than a constant) so that multiple legal notice links can be generated (for several Books in a Set, for example). Fixed some table bugs. Missing cells should now be generated at the end of rows. Version 1.08beta6, 08 Apr 1998 Added support for RevHistory in BookBiblio. Put spacing paragraphs below $informal-object$s (as well as above) and around tabular SimpleLists. Added head-title-mode to make sure that markup is suppressed in the TITLE element in the HTML HEAD. Changed the format of automatically generated anchor names. Instead of making an XPointer-like string, simple use the (all-element-number) of the element. It is now legal to have a Graphic element with neither FileRef nor EntityRef. If so, no output is generated. In xref-title-mode, inline markup is no longer suppressed. Added support for cross-references to ListItems in OrderedLists. Added spacing paras around tabular SimpleLists. Overhauled the table processing as per the print version. Construction rules are now used to process elements in table cells again, making inline markup in tables work correctly. Version 1.08beta5, 29 Mar 1998 Update documentation. Version 1.08beta4, 29 Mar 1998 Removed a significant performance bottleneck. It turns out that element-number is fairly expensive, so I have replaced it with all-element-number. The disadvantage of this change is that the straightforward numbering of chunks has been lost. While the third section of the second chapter was formerly named c0203.htm, it is now named c23252.htm where “23252” is the ordinal number of the element from the start of the document and bears no obvious relationship to the logical position of the element in the document. Bummer. But the performance improvement is at least a factor of five. Changed public identifier for the ISO Latin 1 entity set so that it matches the public identifier used by DocBook. Version 1.08beta3, 26 Mar 1998 More changes to support multiple languages simultaneously. Fixed bug in TOC formatting. (HTML tags did not nest properly.) Fixed bug in VariableList formatting. Improved gentext for German and Russian. Fixed bug where elements in chunk-skip-first-element-list were not always being handled correctly. Changed default table width in navigation tables from 515 to 100%. Improved formatting of titles in RefEntrys. Fixed formatting of FuncSynopsis. Version 1.08beta1, 26 Feb 1998 Widespread changes to support multiple languages simultaneously. Version 1.07, 22 Feb 1998 Fixed bug where an unrecognized alignment cause the stylesheet to crash. Version 1.06, 19 Feb 1998 Fixed an insidious bug in the handling of titles. If you put markup in titles (including things like InlineGraphic), it was being ignored. Now it won't be. Added basic support for Sets. Added %generate-set-toc% to control creation of a ToC for Sets. For some inexplicable reason, I chose to render Titles in bibliography entries with leading and trailing underscores rather than properly in italics. I fixed that. Version 1.05, 15 Feb 1998 Fixed some bugs in the way ToCs and chapter ToCs were produced. Moved common localization functions into the common directory. Created a public identifier for the HTML stylesheet: -//Norman Walsh//DOCUMENT DocBook HTML Stylesheet//ENand added a CATALOG file to the distribution. Version 1.04, 08 Feb 1998 Fixed some bugs with admonitions. If a Title is present on an admonition, it is used in place of the automatically generated title. This was the intended behavior in the past, but it was not implemented properly. Admonitions containing SimPara now work. Changed heuristic for finding Title and SubTitle elements in *Info nodes. The stylesheet now unwraps one level of BookBiblio, BiblioMisc , or BiblioSet. Editors are now supported in the book meta. Version 1.03, 06 Feb 1998 Fixed a small problem with RevHistory in BookBiblio; the construction rule in dbinfo.dsl was more specific than the rule in dbbibl.dsl, so the wrong rule was firing. Fixed by making the construction rule in dbinfo.dsl call a function defined in dbbibl.dsl. Version 1.02, 03 Feb 1998 Added support for sending HTML output to a single file instead of making chunks. To use this feature, set nochunks to #t in your stylesheet or pass Jade the option -V nochunks when you format the document. You must use I/O redirection to capture the HTML output if you suppress chunking. Added support for separators between chunks. These are empty by default if chunking is enabled, and a single <HR> if chunking is suppressed. Chapter and Part TOCs are suppressed by default if chunking is suppressed. Added an <A NAME="..."> wrapper to component and division titles. Fixed a bug in the support for graphics if fileref is unspecified. Changed default section level for SimpleSects to 1. Fixed bug that prevented processing instructions from being allowed between table rows and entries. Changed default formatting of Emphasis and FirstTerm to italic rather than bold. Changed the default formatting of Filename to a mono-spaced font. Added %chapter-autolabel% to control enumeration of Chapters. Fixed a small problem in the formatting of RefEntry s. 1.01, 07 Jan 1998 Made SideBar and LegalNotice $semiformal-object$s Fixed formatting of section SubTitles. (The were coming out bigger rather than smaller than the section Titles.) 1.0, 06 Jan 1998 Changes to the HTML stylesheet: Happy New Year! Moved table footnote code to dbfootn.dsl; moved TABLE and INFORMALTABLE element rules to dbblock.dsl. Like the changes to dbcommon.dsl, these changes make it easier to reuse the CALS table handling code in dbtable.dsl with other DTDs. Made substantial changes to next-major-component-chunk-element and prev-major-component-chunk-element. These are supposed to be “next sibling” and “previous sibling” functions. I think these versions work. Added common/dbtable.dsl to the DocBook stylesheet. 0.10, 29 Dec 1997 Changes to the HTML stylesheet: Fixed small formatting bug in Bibliographies, where a comma (%biblsep%) was output after the [abbrev]. Added %graphic-default-extension% to allow stylesheets to select the appropriate format of graphics in print vs. HTML stylesheets. Modified $html-header-meta$ so that a CREATOR Meta tag is always output with the %stylesheet-version%. Handle IDREFS on Callouts. Added %simplelist-column-width% to set width of columns in SimpleLists. Added version.dsl to contain the change log and the version. 0.9, 04 Dec 1997 This release contains support for callouts, a few other enhancements, a number of bug fixes, and a set of test documents. Changes to dblib.dsl; the general function library: Fixed bug in has-ancestor-member?; it returned precisely the opposite condition. Added string->list, list->string , and split. Changes to dbcommon.dsl; the common library: Added REFENTRY to major-component-element-list to fix HTML navigation problems. Added EQUATION to block-element-list so that XREFs are possible. Removed extraneous space in author-list-string. Added bibliodiv-autolabel, glossdiv-autolabel , dedication-title-sosofo, and dedication-title . Changes to the HTML stylesheet: Added more support for CALLOUTs. The support is based on an old posting to the dssslist and is fairly fragile. See dbcallou.dsl. Added support for line numbers in linespecific displays. Like the support for CALLOUTs, it's a bit fragile. Using the same approach, LITERALLAYOUT and ADDRESS elements are no longer set as <PRE> s. Instead, line breaks and spaces are handled by conversion to <BR> and &nbsp; in a normal <P>. Added support for bibliography entries. The result probably doesn't follow any particular, published bibliographic style, and may not suit the needs of anyone, but at least the stylesheet tries now. ;-) Fixed table bug. Overhanging rows were not always accounted for when skipping to a new entry. Support for CALLOUTs to multiple AREAs is broken. The stylesheet now outputs “??” to indicate this. Suppress ACRONYM and ABBREV in the direct content model of GLOSSENTRY. Fixed KEYCOMBO so that a “+” is printed between its children. Improved dbl1ru.dsl. Added DEDICATION and “Pgs.” to dbl1usen.dsl. Improved support for INFORMALEQUATION and INLINEEQUATION. Suppress MSGREL. 0.8, 24 Nov 1997 Minor changes. 0.7, never released The changes between 0.6 and 0.7 are quite extensive. Most dramatically, support for tables has been rewritten from scratch; see dbtable.dsl for more info. Changes to dblib.dsl; the general function library: Added expand-children to replace elements of a node list with the children of those elements. This is used, for example, to make sure that a list of all the chapters of a book can be constructed by expanding the PART elements in the node list returned by (children book) with their children. Moved book-start? to dbcommon.dsl . It's specific to a particular class of DTDs (those with BOOKs ;-). Fixed a serious bug in case conversion; the letter “A” couldn't be shifted to lower case. Added constant-list, returns a list of “n” copies of a specified value. Added list-head, returns the first “n” items from a list. Added list-put, replaces a single value in a list. Added decrement-list-members. Maybe this isn't so useful in general, but it decrements all the members of a list of numbers by a specified value. Added sgml-root-element. Returns the root of the document. There's a better way to do this, right? Added length-string-number-part. Given a string of the form “25pt”, this function returns the “25”. Added length-string-unit-part. Given a string of the form “25pt”, this function returns the “pt”. Changes to dbcommon.dsl; the common library: Moved book-start? from dblib.dsl . Added first-chapter?. Returns true if the node specified is the first CHAPTER of a BOOK . (This includes the first chapter inside a PART.) Added major-component-element-list for the revised “fast forward” code. See dbnavig.dsl. Added a whole bunch of functions for supporting CALS tables that are shared between the HTML and print versions of the stylesheet. Changes to the HTML stylesheet: Completely rewrote table processing code. Replaced admon-title-mode with title-mode in dbtitle.dsl. Moved support for linked-to LEGALNOTICEs into the mode used for book title pages. This means LEGALNOTICEs and COPYRIGHTs elsewhere don't get special treatment. Added $inline-object$, $formal-object$ , and $semiformal-object$. Reorganized code for informal and formal block obects to use these new functions. These functions explicitly handle titles instead of relying on element construction rules for the titles. Added alt-text as a parameter to the code that supports images. This allows the contents of the ALT tag on, for example, EQUATIONs to be passed through. Added support for SUBTITLEs in most places. Added support for titled EQUATIONs. Localized literal text in support for table footnotes. Changed meaning of fast forward and fast backward. These functions now always go to the next or previous chapter-level element. Navigation banner and title banner now sport the book title by default. Up is only present if the parent is not the root of the document. Added support for callouts that use CO. Fixed table/figure enumeration bugs. Improved support for CMDSYNOPSIS Improved support for FUNCSYNOPSIS Added support for CLASS on SGMLTAG . 0.6, 12 Nov 1997 The changes between 0.5 and 0.6 are so extensive that it would be difficult to document them in detail. All of the files in this distribution have been updated to have a version number of 0.6. My primary goal in making these changes was to build a common library of code for both the print and HTML stylesheets. To achieve this goal, a great deal of code was moved around and reorganized. What follows is a short list of the more dramatic changes: This style sheet now relies on the common dblib.dsl and dbcommon.dsl libraries. Changed formatting of division, component, and section titles from “passive” to “active”. Rather than relying on a rule for (element TITLE) to process the titles, the rules that process the actually element wrappers now process the titles. This allows optional titles to be formatted correctly. Added support for Subtitles in many places. Added support for SimpleLists Added support for GlossSee and GlossSeeAlso. Added %spacing-paras% to control whether or not empty <p> tags are inserted before some block-level elements to get the “right” vertical spacing in the browser. Can you say hack? Lots of other little bug fixes. Version 0.5, 27 Oct 1997 Fixed bugs associated with automatically generated TOCs that contain only one element (when %force-chapter-toc% is true). Added %generate-legalnotice-link% and the ability to place LegalNotices in an external file, linked to from the Copyright notice. Generate HTML anchors on Figures. Fixed a bug in Table and Figure enumeration. Replaced (process-children-trim) with (process-children) in many places. (Should be done in all?) Added support for ENTITYREF on Graphic and InlineGraphic Changed DocInfo, Sect1Info, etc. to process children. This will cause backward compatability problems for users that have *Info elements but don't want that content displayed. A future version will fix this problem by making all of the internal containers (empty-sosofo)s. Added wrappers for handling Abstracts in DocInfo. Added %gentext-nav-use-ff% to toggle use of “fast forwarding” in navigation. Fast forwarding adds navigation elements to skip forward to the next sibling element (i.e. the next chapter) instead of the next sequential element (i.e. the first sect1). Added support for fast forward navigation. Changed the functions that insert navigational elements to make insert of graphics easier. Added more hooks in dblink.dsl to make customizing titles easier. First cut at support for horizontal and vertical spanning and alignment in tables. Version 0.4, 18 Sep 1997 Suppress chapter TOC if there's only one element in the TOC. Added %force-chapter-toc% to force one. Changed formatting of REVHISTORY. Made $chapter-toc$ always find the appropriate ancestral component in case it's called from a descendant (such as TITLE). Output NAME on an anchor for VARLISTENTRYs that have IDs. Big changes to dbnavig.dsl to fix a bug where linking was incorrect when chunk-skip-first-element-list was used. I think it works now. See comments in file. Added style-specification and style-specification-body tags to docbook.dsl and dbl1*.dsl so that OMITTAG YES is no longer required in the SGML declaration used by Jade. Version 0.3, 18 Aug 1997 Added %gentext-and% to customization layers. Replaces literal “and” in dbbibl.dsl. The chunking level is now very general. In the distributed style sheet, any element at the division, component, or block level can be a chunk. If the function (chunk? nd) returns true, the chunk nd will be in a seperate file. (Supporting arbitrary chunking would require some additional coding in the style sheet.) Added support for the align attribute on GRAPHIC and INLINEGRAPHIC. Added support for ARTICLEs Element titles can be retrieved with (element-title nd). For xref purposes, these titles will be italic. Changed calculation for filenames. The new names are perhaps not as nice, but they have the necessary generality to support the more arbitrary chunking. Completely reworked the code that calculates previous and next nodes. Added hooks for tailoring the navigation links at the head and foot of each page. Version 0.2, 08 Aug 1997 Version 0.2 never publicly released. Completely rewrote automatic TOC code. Automatic TOCs are now built by traversing elements explicitly. Added ability to set depth of TOC, see (toc-depth). Changed format of SIDEBAR. Now a table. Added support for META in HEAD. Changed ($chapter-toc$) to use new TOC code. Added navigation to BOOK page, BOOK entity filename is no longer a constant. Added support for PARTs. GLOSSARY is now a DL, not a collection of H3's and BLOCKQUOTEs. Rewrote header and footer navigation. Now works correctly for a much wider range of component level elements. Added support for <?html-filename>, <?html-dir> and <?html-basename>. <?html-filename path/name.ext> sets the name of the HTML file for the component in which it occurs (note: if the component contains chunk-level subcomponents without their own <?html-filename> 's, all of them will get the same filename, wreaking havoc). <?html-basename base> sets the base name (upon which sub-component numbers will be appended) for a component. <?html-dir dir> sets the directory in which generated HTML files should be placed. Must be relative, and below, the starting directory. Made CITETITLE italic. Changed to the new method for generating XREF text. See the top of dblink.dsl. Added (dirctory-depth), (copy-string) , and (node-list-filter-by-gi) to library. Added new config parameters: %generate-part-toc% , %html-ext%, %use-id-as-filename%, and %html-meta-tags%. Made REFMETA (empty-sosofo). Need to grab this info elsewhere to get reasonable HTML formatting, IMHO. Changed default TITLE to be a bold string, not an H2. Rearranged code in dblib.dsl, dbhtml.dsl, and dbnavig.dsl (new file). In 0.1 A transmogrification of the print style sheet, so most elements are supported Support for FOOTNOTE and FOOTNOTEREF, even in tables Automatic chunking at the component and SECT1 level A navigation system that I'm fond of, but lacking any real hooks for customization Uses DIV to mark elements so that a browser style sheet could do even more style stuff Optional screened verbatim displays (an idea from Richard Burton's style sheet). This summary is fairly terse. If you have more detailed questions, ask the maintainer ;-). I've gone to considerable lengths to generalize the features of this stylesheet and provide hooks for customization. If you have a need that doesn't seem to have been addressed, feel free to ask me about it.