The Modular DocBook Stylesheets | ||
---|---|---|
Change Log: Print Stylesheet |
This document summarizes the changes made to the Modular DocBook Print Stylesheet:
Moved common localization functions into the common directory.
Fixed a problem with the bottom-margin/footer-margin that caused page numbers to get chopped off.
Created a public identifier for the print stylesheet:
-//Norman Walsh//DOCUMENT DocBook Print Stylesheet//ENand added a CATALOG file to the distribution.
Changed plain.dsl to refer to docbook.dsl by public identifier.
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. They appear on the title page verso.
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.
Changed default formatting of Emphasis and FirstTerm to italic rather than bold.
Restored support for PGWIDE on Table. It was lost accidentally.
Fixed a bug in the support for graphics if fileref is unspecified.
Fixed bug that prevented processing instructions from being allowed between table rows and entries.
Added use: para-style to the simple-page-sequence construction rules so that environments that inherit from them will have the correct %bf-size%, etc.
Added %chapter-autolabel% to control enumeration of Chapters. Fixed a bug which caused the running header of a Chapter with a DocInfo to be wrong.
Made automatic TOC formatting obey %section-autolabel%.
Made LegalNotice and SideBar $semiformal-object$s.
Fixed handling of section Titles and SubTitles. The previous handling was very poor.
Changes to the print stylesheet:
Happy New Year!
Added some additional space below subtitles in components.
Added fairly extensive documentation to dbparam.dsl. See dbparam.sgm.
Added %refentry-keep% parameter.
Moved table footnote code and the 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.
Added a new parameter, %table-element-list% to specify what element names are CALS tables.
Fixed indentation in Steps in Procedures.
Fixed bug in dbverb.dsl where inheriting first-line-start-indent sometimes caused the first line of a verbatim environment to indent incorrectly.
Added common/dbtable.dsl to the DocBook stylesheet.
Changes to the print stylesheet:
Added %block-start-indent% to add an extra indent to block elements (tables, figures, lists, verbatim environments, etc.).
Fixed small formatting bug in Bibliographies, where a comma (%biblsep%) was output after the [abbrev].
Fixed size of endnote-title in RefEntrys.
Handle Title on Sidebar.
Set Callout numbers as white numerals in a black circle. (If %callout-fancy-bug% is #t.)
Handle IDREFS on Callouts.
Fixed bug in formatting of running headers and footers. Now properly obeys %chap-app-running-head-autolabel%.
Added %graphic-default-extension% to allow stylesheets to select the appropriate format of graphics in print vs. HTML stylesheets.
Changed %verbatim-font-size% parameter to %verbatim-size-factor% so that it works reasonably well with different %visual-acuity%s.
Added %simplelist-column-width% to set width of columns in SimpleLists.
Improved handling of RefMeta.
Improved handling of sections so that RefSect1, etc., could be $section$s instead of $block-container$s.
Added %cals-frame-default% and changed default for column and row rules to depend on the setting of the frame.
Added version.dsl to contain the change log and the version.
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 print 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.
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. ;-)
Added a period to the end of titles in $runinhead$s. (e.g., on FORMALPARA.)
Added, but left commented out, the ability to set $runinhead$s in small caps.
Fixed bug that caused table footnotes to be enumerated incorrectly.
Added endnotes to REFENTRYs; removed endnotes from REFERENCES (so they aren't repeated).
Support for CALLOUTs to multiple AREAs is broken. The stylesheet now outputs “??” to indicate this.
Added support for TITLEABBREV in running headers and footers.
Added %division-title-quadding%, %division-subtitle-quadding%, %component-title-quadding%, and %section-title-quadding%.
Suppress ACRONYM and ABBREV in the direct content model of GLOSSENTRY.
Fixed bug, made GRAPHIC graphics “display” rather than “inline”.
Added a %guilabel-font-family% so that GUI type things can be printed in an alternate font. Fixed KEYCOMBO so that a “+” is printed between its children.
Fixed a couple of typos in dbl1dege.dsl and added support for $lot-title$s.
Improved dbl1ru.dsl.
Added DEDICATION and “Pgs.” to dbl1usen.dsl.
Fixed numeration bug in ORDEREDLISTs.
Removed errant reference to %cals-cell-content-end-indent% in dblists.dsl.
Improved support for INFORMALEQUATION and INLINEEQUATION. Note that inline graphics don't seem to work in the RTF backend.
Suppress MSGREL.
Made default setting of %verbatim-font-size% dependent on %visual-acuity%.
Use of a monospaced font in inlines now respects %verbatim-font-size%.
The changes between 0.94 and 0.95 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 print stylesheet:
Completely rewrote table support. (Note: the RCS version number for dbtable.dsl is out-of-whack.)
Added support for table footnotes.
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.
Rewrote support for alternating page headers/footers. They actually work now. You can also specify headers and footers (and page number formats) for automatically generated TOCs and LOTs.
Added support for a DEDICATION in the front matter of a BOOK.
Added support for EQUATIONs.
Made most links and XREFs into hot links in RTF.
Added %verbatim-font-size%. If not #f, it is used as the font size for verbatim text, regardless of line length. When it is #f, the font size of each verbatim chunk varies with the length of the longest line and the current start indent.
Added support for callouts that use CO.
Improved support for CMDSYNOPSIS
Improved support for FUNCSYNOPSIS
Added support for CLASS on SGMLTAG.
Force LINEANNOTATIONs to be in italic body font, not the verbatim font.
Changed handling of bullets, numbers and callouts on lists so that list items containing elements other than PARA are handled correctly.
The changes between 0.93 and 0.94 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.94.
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.
Made most cross-references into “links” in the RTF.
Christian Wallgren contributed support for horizontal alignment in table cells.
Lots of other little bug fixes.
Added support for FOOTNOTEs as endnotes. (Thanks to Lassi A. Tuura for the idea.)
Replaced all the occurances of (process-children-trim) with (process-children) in inlines (I suspect this is needed elsewhere too). Consider: "this <emphasis>is </emphasis>a test". (Thanks to Eduardo Gutentag for pointing out this error.)
Added optional sosofo to $ss-seq$ (for use in footnotes). Maybe the other character-sequence functions ought to be done this way too?
LINK text should now be a "clickable" cross reference in Word. (Thanks again to Lassi A. Tuura.)
Fixed line-fields in lists so that the indent is done correctly. (I've thought for a while that this was broken and finally tracked it down.)
Added TODO to the distribution. Feel free to contribute to it ;-).
Fixed bug where TABLEs, FIGUREs, and EXAMPLESs that occured inside PARAs didn't get properly added to the automatically generated TOC.
Added %generate-titlepage% test in BOOK where it was accidentally left out.
Changed FILENAME inline to be monospace font instead of regular text font.
Added style-specification and style-specification-body tags to docbook.dsl, plain.dsl, notoc.dsl, and dbl1*.dsl so that OMITTAG YES is no longer required in the SGML declaration used by Jade.
Completely rewrote the automatic TOC code. Now supports lists of other formal objects, see %generate-lot-list%.
Added book-start? to restart page numbering on the first component or division.
Reorganized the code so that the title page and book TOC/LOT code isn't duplicated in BOOK and BOOKINFO. See the BOOK element.
Made CITETITLE italic.
Added BIBLIOGRAPHY, GLOSSARY, and INDEX to gentext-element-name and $lot-title$ in dbl1usen.dsl. These are used to produce the titles of the respective elements.
Added an optional force-label? parameter to the automatic labeling functions. This allows the TOC generating code to produce labels even if automatic labels are suppressed in the document.
Added component-child-number so that block-level elements would be numbered correctly. (Simple child-number doesn't work because it restarts at each wrapper and block numbering restarts only at each component-level wrapper.)
Fixed indenting of verbatim environments.
Added %gentext-and% to localizations to replace literal “and” in dbbibl.dsl.
Use (element-label) to calculate labels in dbblock.dsl, dbcompon.dsl, and dbsect.dsl.
Simplified title page generation in dbdivis.dsl.
Updated localization layers.
Made several improvements to the code in dblink.dsl: added xref sosofo mode to allow other sections of the style sheet to to use the element-title functions without italics, added -sosofo functions for use in sosofo contexts. Etc.
Totally changed how XREF works. See below. NOTE: international versions of dbl1* are now broken.
Changed numbering of STEPs within PROCEDUREs so that they work for more than two levels. (suggested by James Bostock)
Support XREF to STEPs in a PROCEDURE.
Added $hierarch-number-format$ to control number format (1, a, I, etc.) in nested steps.
Added ARTICLEs to the auto TOC.
Tinkered with the appearance of ABSTRACTs
Made printing of BOOKs of ARTICLEs possible. May not be pretty yet.
Added dblib.dsl, a library of functions that my have more general utility.
Added %body-start-indent% to verbatim environments.
Added declaration for (debug) to docbook.dsl
Added "test" directory to the distribution, for test files. Please supply your favorites.
This description of linking is adapted from comments in dblink.dsl
From the DocBook V3.0 Reference entry for element XREF: Description Cross reference link to another part of the document. XRef is empty, and has common, Linkend, and Endterm attributes. Processing Expectations XRef must have a Linkend, but the Endterm is optional. If it is used, the content of the element it points to is displayed as the text of the cross reference; if it is absent, the XRefLabel of the cross-referenced object is displayed. |
If neither the ENDTERM nor the XREFLABEL is present, then the cross reference text is taken from the (gentext-xref-strings) function in the localization file, like this
A cross reference to an element, the target, begins with the text returned by (gentext-xref-strings (gi target)). Within that text, the following substitutions are made:
is replaced by the number of the page on which target occurs
is replaced by the (gentext-element-name)
is replaced by the label
is replaced by the title
Where "x" is either absent, in which case the target is used, or one of the following:
the ancestral book
the ancestral component
the ancestral division
the ancestral block
the ancestral section
So, %cn is replaced by the label (number) of the chapter that contains target. %st is replaced by the title of the section that contains target, %g is replaced by the (gentext-element-name) of the target, etc.
What elements constitute a book, component, division, block, and section are defined by the lists *-element-list.
As if this wasn't confusing enough, _one_ additional level of indirection is available. If one of the special symbols, #b, #c, #d, #k, or #s occurs in the (gentext-xref-strings) text, then it will be replaced by the appropriate (gentext-xref-strings-indirect) text depending on whether or not the target and the reference occur in the same element.
Here's a concrete example:
Given
(define (gentext-xref-strings-indirect key) (case key (("k") '(" in %kg %kn" "")) (("s") '(" in %cg %cn" " in this %cg"))))and
(define (gentext-xref-strings giname) (case giname (("STEP") "step %n#k") (("SECT1") "the section called %t#s")))
A cross reference to a step in the same procedure as the reference will use the string "step %n" as the gentext-xref-strings text. A cross reference to a step in another procedure will use the string "step %n in %kg %kn".
So, a reference from step 5 to step 3 in the same procedure will appear as "step 3". A reference to step 6 in the third procedure in the fourth chapter from some other place will appear as "step 6 in procedure 4.3".
Likewise a reference to another section in the current chapter will appear like this "the section called target-title in this Chapter", and a reference to a section in an appendix will appear like this "the section called target-title in Appendix B".
Removed the forced page break after the automatically generated TOC
Added gentext-xref-element-name, the string that should be used in printed cross references to an element.
Put %writingmode% back into dbparam.dsl so that the page header/footer code can test for writing mode
Change default font size for verbatim displays so that 80 character lines will fit by default
Added $side-header$, $center-header$, $side-footer$, and $center-footer$. These functions allow a stylesheet to easily override the use and placement of headers and footers on the left, center, and right side of pages.
Changed method for configuring generated text; this changed a bunch of definitions in the localization module and rippled through many other files. (See below)
Localization is now done by pointing to the complete style sheet containing localization, rather than by entity reference. This allows the localization layer to include parameter entities (e.g., ISO entity sets).
Use gentext for labels and label seperators in dbsect.dsl
Added localization for start and end quotation marks
Fixed bug where admonitions with titles got formatted oddly
Support APPENDIXes, GLOSSARYs, BIBLIOGRAPHYs, and INDEXes occuring after PARTs in the autotoc
Changed a whole slew of inlines from (empty-sosofo) to ($charseq$)
Added limited support for REVHISTORY
Consolidated table-caption-mode (in dbtable.dsl) and figure-caption-mode into a single block-caption mode.
Support TITLE on EXAMPLE with block-caption-mode
Added %two-side% to configure running heads appropriately (James Bostock)
Redefined several page-attributes (is attributes the right word?) as (declare-initial-value) instad of using a (define)d variable everywhere. This method was suggested by Paul Prescod on dssslist. In the future, more attributes may be initialized this way; I did the easy ones this time.
Made ARTHEADER (process-children) instead of (empty-sosofo) so that (ARTHEADER TITLE) fires. (Ulrich Drepper)
Pass FORMAT notation on graphics to the back end (for TeX) (Ulrich Drepper)
Added support for GLOSSTERM as an inline
Tried to make INLINEGRAPHIC actually inline. Doesn't work in RTF, but looks like it should, IMHO ;-)
Added support for XREF. Works for many TITLE'd components. Supports both lableled (enumerated) sections and unlabeled. Some generated text in dblink.dsl will have to be changed for non-English styles using unlabled sections, but it's not simply a text question, it's a grammar question, so I haven't tried to extract it out into the localization files. In the non-labeled style, XREFs produce text like this "the section called [section title] in Chapter [#]".
Added support for NUMERATION on ORDEREDLIST
Incorporated patch for VARLISTENTRY LISTITEM spacing: in VARLISTENTRY there was a problem with the way indentation was calculated when a VARLISTENTRY included an ITEMIZEDLIST. (Ulrich Drepper)
Procedure STEPs are no longer bold.
Modularized title code in dbtitle.dsl, use that code to generate REFNAMEs so they appear the same as other titles (James Bostock)
Made SYNOPSIS a $verbatim-display$, made CMDSYNOPSIS a $paragraph$ (for proper vertical spacing).
Added support ARG in CMDSYNOPSIS (James Bostock)
Made FUNCSYNOPSIS a $verbatim-display$. This is an inadequate solution, but it looks a little better than (process-children)
Replaced %gentext-authored-by% and %gentext-copyright-by% with %gentext-by%
Fixed bug: use of the word "Page" in the page number was erroneously dependent on the use of %page-number-restarts%
Notes on generated text:
Using a different definition for each piece of generated text was rapidly becoming unmanagable. Most generated text is keyed of the type of element (the word "Chapter" for a CHAPTER, etc.) so one function takes the name of the element and returns the appropriate string. Other functions were added to configure things like the characters that occur in and between labels. In a few cases I've stretched the rules a bit (gentext abuse, I suppose, to missquote a colleage ;-), but the principle is to use a function keyed off the element name (or pseudo-element name). There's some potential for this to get unmanagable as well. Suggestions welcome.
Added support for QUOTE
Added support for CORPAUTHOR
Added %refentry-name-font-family%, the font family used for the refentry name. It's mono by default if %refentry-function% is true, body otherwise
Added %refentry-new-page%; controls whether or not each RefEntry begins on a new page
Changed auto toc code to put References and RefEntrys in the TOC (it seems to work, but I'm not real confident about it)
Made BOOK TITLE test for BOOKINFO and %generate-titlepage% (in other words, BOOK TITLE will generate a title page if there is no BOOKINFO)
Hacked REFERENCE TITLE to make it a $divtitlepage$ if each RefEntry starts on its own page anyway
Changed the quadding on $divtitlepage$ to 'center
Made the "--" between RefName and RefPurpose a proper em-dash
Added %default-simplesect-level% and adjusted the definition of SECTLEVEL in dbsect.dsl so that simplesects would always appear at the level below the section level that contains them. %default-simplesect-level% is used for SimpleSects contained directly within chapter-level elements
Added ldquo, rdquo, em-space, and en-space to the list of dingbats (would it be better to include the appropriate ISO entity set instead?)
Fixed bug: if %gentext-chap-or-app% is "", don't output a space after it
Added %gentext-title-label-sep%, the character sequence inserted between generated title numbers and the actual title, ". " by default
Added %section-autolabel%, if true, all unlabeled sections behave as though they are labeled AUTO. (Except that SimpleSects are never auto numbered.)
Fixed bug in $sectitle$, it was looking for the RENDERAS and LABEL attributes on the TITLE, not the containing section element.
Added a comment to dbtable.dsl, you can make rules in tables by setting %cals-rule-default% to 1.
Added %chap-app-running-heads% to control use of running heads in components.
Added %chap-app-running-head-autolabel% to control LABEL attributes. If chap-app-running-head-autolabel is #t, Chapters and Appendixes that do not specify a LABEL attribute will be treated as if they specified LABEL=AUTO. If this is #f, Chapters and Appendixes without a LABEL attribute will have only the title in the running head. Based on a suggestion from James Bostock.
Fixed bug in dbcompon.dsl where "Chapter" was compared to "CHAPTER" and consequently all chapters and appendixes were labelled with "A", "B", etc.
Added BUGS to the distribution. (yeah, yeah, har har har. ;-)
Modularity achieved with entities rather than separate style specifications.
Combined dbfeatr.dsl, dbmswin.dsl, and dbparam.dsl---customization is easy with a style-specification so keeping these units separate no longer seems necessary. See plain.dsl and notoc.dsl in the distribution.
Added support for SegmentedList (not for any particular reason; after fiddling with modularity for several days, I just wanted to make something new work ;-)
Use multiple style-specifications for customization. They should otherwise be the same.
Fixed bug in dbcompon.dsl, HEAD-CHAP-APP-LABEL didn't handle l10n correctly. Thanks to Alexander Taranov.
Reordered use declarations in dbmain.dsl; I think this fixes the problems of which element declarations are being used, but I'm far from certain. (I'm working on a little tool that will report these problems.)
Some of the files still have internal version numbers that are misleading.
Added dbl10n.dsl, localization of generated text and placement of TOC. Current version only contains us-english; send me your updates.
Changed functions that create bullets and other marks to use Unicode names, making them font/platform independent
Some of the files have internal version numbers of 0.81...that's an error and I expect to get them back in sync for the next version...
Includes several changes supplied by James Bostock (%default-quadding%, %paper-type%, %page-number-restarts%, ande support for PROMPT).
A modular version of db070.dsl. No other changes are intentional.
This summary is fairly terse. If you have more detailed questions, ask the maintainer ;-).
Home |
Copyright © 1997, 1998 Norman Walsh