Re: CSS and SGML document formatting

[Gavin Nicol:]

| CSS is small, it's easy. Anybody can work with, or design something
| like it. The one thing is is *not* is suitable as a general-purpose
| stylesheet language for large scale publishing of structured
| documents. 

Part of the problem in trying to explain the limitations of CSS for
generic SGML formatting is the lack of real-world examples.  I am
working (slowly) on a set of typical cases drawn from actual online
publications to show the kind of functionality that has to be in a
stylesheet language that can handle the ordinary run of commercial
typography.

Here are two examples from the stylesheets used for Novell's online
NetWare documentation.  These manuals are the only documentation
supplied to the roughly 40,000,000 NetWare users worldwide, and they
have been distributed in this form since 1993, so this is about as
realistic as it gets.  The manuals are marked up in DocBook, which is
the industry standard for software documentation.

I don't have a DSSSL tool to test against, so unfortunately I don't
have any DSSSL code to show here; instead, I show the actual DynaText
stylesheet language that's used in the published manuals.  While it
will take many more examples to constitute a useful set of normative
scenarios, these two should at least start to indicate why people like
Gavin and me keep saying that the CSS design won't work for generic
SGML.

I would welcome further contributions of real-life formatting examples
to this collection.

Jon


========================================================================

Example: Numbering procedure steps

DocBook uses tags such as PROCEDURE, STEP, and SUBSTEPS for these
specialized structures.

Verbal description:

In procedure steps having more than one paragraph, autonumber the
first paragraph and set it in bold, but don't number or embolden
subsequent paragraphs in that step.  If the step is at the outermost
level of the procedure, make the number an Arabic numeral (1, 2, 3,
etc.), but if the step is within a group of substeps, make the number
the number of the containing step plus a lowercase letter (2a, 2b, 2c,
etc.) designating the order of the substep among its siblings.
Automatically indent everything by the same amount at each nesting
level using a parameter (&ol1in;) that can be set elsewhere for ease
of maintenance.  (The definitions of the style groups "container",
"lowtitle", and "graf" are omitted to save space.)

DynaText stylesheet realization:

   <group name="olitem">
      <break-before>       line </>
      <space-before>       &lead1; </>
      <left-indent>        +=&ol1in; </>
      <first-indent>       -&ol1in; </>
   </group>

   <style name="PROCEDURE,TITLE" group="lowtitle">
      <break-before>       line </>
      <font-weight>        bold </>
      <left-indent>        0 </>
   </style>

   <style name="PROCEDURE,STEP" group="olitem">
      <text-before>cnum().</>
   </style>

   <style name="STEP,#text-before">
      <break-after>        none </>
      <font-weight>        bold </>
   </style>

   <style name="PROCEDURE,STEP,PARA">
      <select>             proc_p1_eq(cnum(),1) </>
   </style>

   <style name="SUBSTEPS" group="container"></style>

   <style name="PROCEDURE,STEP,SUBSTEPS,STEP" group="olitem">
      <text-before>cnum(ancestor(STEP))format(cnum(),letter).</>
   </style>

   <style name="PROCEDURE,STEP,SUBSTEPS,STEP,PARA">
      <select>             proc_p1_eq(cnum(),1) </>
   </style>

   <style name="proc_p1_True">
      <break-before>       none </>
      <space-after>        &lead1; </>
      <font-weight>        bold </>
   </style>

   <style name="proc_p1_False" group="graf"></style>


Example: Figure captions

In DocBook, figure captions, table captions, section titles, chapter
titles, and appendix titles are all marked as TITLE.  The renderer
knows how to interpret each TITLE element based on its parent --
FIGURE, TABLE, SECT1, etc.  This arrangement is quite common in DTDs
other than HTML.  The reader is again reminded that this is not a
made-up example but is drawn from books in actual use and that all of
the functionality described is provided by the stylesheets alone.

Verbal description:

Print a figure caption by printing the word for "Figure" in the
appropriate language (represented by the entity &figwd; drawn from a
resource file that is translated once for all books in the language
version of a collection) followed by the figure number followed by a
period and a space and then the content of the figure's TITLE element.
The figure number (&fignum;) is generated as follows: Check to see
whether the figure happens to be somewhere in an appendix.  (It could
be as deep as a dozen or more layers down into the hierarchical
structure of the appendix.)  If it's not, then it's at some level
within a chapter, so see whether the chapter has a number (1, 2, 3,
etc.) given as a LABEL attribute on the CHAPTER start-tag; if no label
is given, don't print a chapter or figure number, just print the
locale-dependent word for "Figure" followed by a period and a space
and the content of the TITLE element.  If there is a LABEL attribute
on the chapter, print that number followed by a dash followed by the
number of that figure among its sibling figures in the chapter (1-1,
2-5, etc.) unless the value of the LABEL attribute is the reserved
value "auto", in which case calculate the chapter among its sibling
chapters as well as calculating the number of the figure within the
chapter.

If the figure does happen to be in an appendix, then check to see
whether the appendix has a letter (A, B, C, etc.) given as a LABEL
attribute on the APPENDIX start-tag; if no label is given, don't print
an appendix letter or figure number, just print the word for "Figure"
followed by a period and a space and the content of the TITLE element.
If there is a LABEL attribute on the APPENDIX, print that letter
followed by a dash followed by the number of that figure among its
sibling figures in the appendix (A-2, B-5, etc.)  unless the value of
the LABEL attribute is the reserved value "auto", in which case
calculate the letter of the appendix among its sibling appendices as
well as calculating the number of the figure within the appendix.

(This mechanism causes figure numbering to change dynamically
throughout an entire chapter, appendix, or book whenever the book is
edited, even if whole chapters or appendices are inserted, deleted, or
reordered.  This capability is essential for large-scale publishing
efforts.)

DynaText stylesheet realization:

   <!ENTITY     fignum          "if(eq(0,ancestor(APPENDIX)),
        if(isnull(attr(LABEL,ancestor(FIGURE))),&figwd;. ,
        if(eq(attr(LABEL,ancestor(FIGURE)),auto),&figwd; gcnum(ancestor
          (CHAPTER))-gcnum(ancestor(FIGURE)). ,&figwd; attr(LABEL,
          ancestor(FIGURE)). )),
        if(isnull(attr(LABEL,ancestor(FIGURE))),&figwd;. ,
        if(eq(attr(LABEL,ancestor(FIGURE)),auto),&figwd; format
          (gcnum(ancestor(APPENDIX)),LETTER)-gcnum
          (ancestor(FIGURE)). ,&figwd; attr(LABEL,
          ancestor(FIGURE)). )))">

   <style name="FIGURE,TITLE">
      <text-before>&fignum;</>
   </style>
   <style name="FIGURE,TITLE,#text-before">
       <break-after>    none </>
   </style>


---
Jon Bosak, SunSoft, 2550 Garcia Ave., MPK17-101, Mountain View, CA 94043
A Davenport Group Sponsor       http://www.ora.com/davenport/README.html

Received on Thursday, 25 April 1996 01:28:41 UTC