DocBook Modular Style Sheet 0.89

[Norman Walsh <norm@xxxxxxxxxxxxx>]

DocBook Style Sheet 0.89 is up at http://www.berkshire.net/~norm/dsssl/

I've _TOTALLY_ hacked at the way cross reference text is
generated.  My goal was to extract all of the generated text
from the DSSSL code in dblink.dsl so that someone unfamiliar
with scheme would have half a chance of using alternate cross
reference text.

I think I've succeeded, but was it a good idea?.  The notes
below describe what I've done, and test/xref.sgm in the
distribution will show you how it works.  Comments, pro or con,
on this scheme would be much appreciated.

People who are maintaining localizations, please note that I've
made no effort to fix the dbl1* files other than dbl1usen.dsl so
your current customization layers will not work.

README for DocBook Style Sheet version 0.89

*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. (Does it work?)
Added declaration for (debug) to docbook.dsl
Added "test" directory to the distribution, for test files.  Please supply
  your favorites.

This description of linking comes from 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:
;; 
;; %p is replaced by the number of the page on which target occurs
;; %[x]g is replaced by the (gentext-element-name)
;; %[x]n is replaced by the label
;; %[x]t is replaced by the title
;; 
;; Where "x" is either absent, in which case the target is used, or
;; one of the following:
;; 
;; b = the ancestral book
;; c = the ancestral component
;; d = the ancestral division
;; k = the ancestral block
;; s = 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".


 DSSSList info and archive:  http://www.mulberrytech.com/dsssl/dssslist