========================================= NOTES ON THE SAMPLE DSSSL HTML STYLESHEET ========================================= (Last updated 1996.11.17) These notes accompany files obtainable from ftp://sunsite.unc.edu/pub/sun-info/standards/dsssl/stylesheets/. The files named html32hc.zip and html32hc.tar.gz in this directory contain a DSSSL stylesheet for making hardcopy printouts from documents conforming to the HTML 3.2 DTD. Use of the stylesheet requires a DSSSL engine such as James Clark's Jade. The idea is that you can feed a conformant HTML 3.2 document, the HTML 3.2 DTD, and the html32hc.dsl stylesheet to a DSSSL engine and get out something like RTF or TeX that can be taken into an application that knows how to print it. While designed specifically for print output, the same stylesheet can easily be adapted to driving electronic publishing tools such as Web browsers when DSSSL-capable versions of those tools become available. Jade is available from http://www.jclark.com/jade and also from ftp://sunsite.unc.edu/pub/sun-info/standards/dsssl/jade. The latest files are on www.jclark.com, but the (infrequently updated) sunsite archive includes binaries for platforms other than Windows. To use the HTML stylesheet, install Jade according to the directions included with the Jade distribution and then unzip the HTML stylesheet package into the directory containing the HTML file you wish to format. This will install files named html32hc.dsl, isolat1.ent, html32.dtd, and catalog in the directory containing your files along with a test document named xmlapps.htm. Note that the catalog file assumes that Jade and its support files have been installed in a directory accessible as "..\jade"; you will have to edit the catalog file if you have installed Jade somewhere else. Once you have installed Jade and the HTML stylesheet, you should be able to create an RTF version of the test file with the command ..\jade\jade -t rtf -d html32hc.dsl -o xmlapps.rtf xmlapps.htm Refer to the jade.htm file accompanying the Jade distribution for more instructions on how to use Jade. ------------------------------- Notes about the HTML stylesheet ------------------------------- Current versions of this stylesheet are lacking support for the more complex table extensions in HTML 3.2, though they will produce tables that can very easily be autoformatted in a program like Word to yield pleasing and useful results. On the other hand, the stylesheet supports features missing from HTML 3.2 such as headers, footers, optional autonumbering of heads and table captions, automatic TOC (Table of Contents) generation, and the correct and completely extensible interpretation of named units in size and length attributes. In designing the stylesheet, I've tried to make use of the fact that DSSSL is a real programming language by defining functions that make the stylesheet more compact and using variables that make it easier to customize. I've tried (I hope consistently) to use the following conventions: Names in ALLCAPS are common functions defined for use throughout the stylesheet. Names surrounded with $dollar-signs$ are "construction templates" that define a construction rule applicable to more than one element type. Names surrounded with %percent-signs% are parameters designed to be changed by the user in order to modify the overall look of the formatted document. The default behavior of the stylesheet as supplied is to produce a cover page with an automatically generated Table of Contents followed by printed pages that have a header in italics, set flush left in the default body font-family in a size one point less than the size of the default body type and containing the content of the document's element, and a footer of the same size set flush right and containing the generated string "Page " followed by the page number. Heads H1-H6 are in Arial (the stylesheet was designed for Windows 95, but of course the font families can easily be changed like everything else); H1-H3 in the default configuration hang out into a 4-pica-wide area to the left of the text flow, while H4-H6 are set flush left with the text flow. All the heads are autonumbered, and table captions are both autonumbered and preceded with the generated string "Table ". The body type is Times, set justified. For convenience, three predefined font size treatments are provided: "normal" for the usual case, "presbyopic" for us old folks, and "large-type" for people with impaired vision. The default stylesheet produces pages that look something like ordinary book pages, but the treatment can be altered radically by changing a few of the parameters. For example, a treatment suitable for code documentation containing many programming examples could be created as follows: 1. Change the text quadding (set in the construction rule for the HTML element) from justified to flush left (i.e., "start" in the writing direction of a left-to-right script): ;; quadding: 'justify quadding: 'start 2. Get rid of the text indent in order to use the full width of the text area: ;; (define %body-start-indent% 4pi) (define %body-start-indent% 0pi) 3. Hardwire the monospace font size to 9pt: ;; (define %mf-size% %bf-size%) (define %mf-size% 9pt) Besides providing what I hope will be a useful adjunct to a DSSSL engine for HTML users, the stylesheet should help to clarify the differences between the DSSSL and CSS approaches to formatting specifications. In particular, this example demonstrates the following: 1. A DSSSL stylesheet will typically be more complex than a CSS stylesheet. This is partly because of the syntax, but much more importantly because the DSSSL stylesheet sets up the entire formatting environment, while a CSS stylesheet is just specifying adjustments to the stylesheet presumed to be implicit in a target application. In the CSS approach, if you don't supply a stylesheet, you still get a stylesheet. In the DSSSL approach, you only get what you have specified. 2. CSS is a way to specify formatting characteristics. DSSSL is an actual (side-effect free) programming language, ISO/IEC 10179:1996. 3. CSS is designed as an adjunct to HTML and will not scale to handle arbitrarily complex structures. DSSSL is designed to specify formatting for any language defined in conformance with ISO 8879, including the vastly more complex markup languages used in industrial and commercial publishing. An interesting consequence is that people using this stylesheet to format HTML documents can extend HTML itself by adding tags and attributes at will. As long as the HTML DTD is adjusted accordingly, the resulting language will be conformant with ISO 8879 and usable not only with any DSSSL engine but also with all currently available SGML publishing tools. See "Add-a-Tag" below. 4. The example only uses features of DSSSL's style language. DSSSL also includes a transformation language for performing structural modifications. For example, the transformation language can be used to "reformat" a telephone directory ordered by last name into a directory ordered by first name, or to generate a book's index or table of contents, or to convert documents marked up in one tag language to documents marked up in another. Add-a-Tag(tm) ------------- The fact that Jade is a generic SGML tool means that you can easily extend HTML yourself without getting the approval of Netscape, Microsoft, or the World Wide Web Consortium. Suppose, for example, that you are using HTML 3.2 for technical documentation and need to extend the language to add an element type (a tag) for warnings so that they can be given special processing treatment. First, extend the language by modifying the DTD. "Warning" would be a new kind of block element, so add it to the part of the DTD that defines block elements. Where the HTML 3.2 DTD now has this entity declaration: <!ENTITY % block "P | %list | %preformatted | DL | DIV | CENTER | BLOCKQUOTE | FORM | ISINDEX | HR | TABLE"> Add the new WARNING tag: <!ENTITY % block "P | %list | %preformatted | DL | DIV | CENTER | BLOCKQUOTE | FORM | ISINDEX | HR | TABLE | WARNING"> This says, in effect, "Wherever it was OK to have a P or a DL or a BLOCKQUOTE (etc.), it is now OK to have a WARNING." You also have to say what a WARNING can consist of. It's going to need to have about the same things in it that a P element can have, so the easiest way to make a definition for WARNING is to copy the definition for P. The P definition looks like this: <!ELEMENT P - O (%text)*> <!ATTLIST P align (left|center|right) #IMPLIED > So just add something like that for WARNING (you probably don't need the attributes): <!ELEMENT WARNING - O (%text)*> You have now created your own HTML extension. For example, you can now have the following in your document: <p>The fan blade is removed by loosening the nut holding it onto the shaft. <warning>Turn off the fan before attempting to remove the fan blade. Of course, the DSSSL stylesheet has to be modified to give this new element special treatment in the output. The following addition to the stylesheet will cause the generated word "WARNING" to appear centered at about the size of an H4 above the warning text and will wrap a heavy black box around the whole thing every time a warning element appears in the text of the document: (element WARNING (let ((hs (HSIZE 2))) (make display-group space-before: %block-sep% space-after: %block-sep% (make box display?: #t box-type: 'border line-thickness: 2pt start-indent: %body-start-indent% (make paragraph space-before: %para-sep% space-after: %para-sep% start-indent: 1em end-indent: 1em font-family-name: %title-font-family% font-weight: 'bold font-size: hs line-spacing: (* hs %line-spacing-factor%) quadding: 'center (literal "WARNING")) (process-children-trim))))) While this solves the problem for printed output, a document using the new extension will not be rendered correctly by current HTML browsers, which will ignore the WARNING tag. It is a shortcoming of current HTML browsers that they do not support DSSSL or tag exensions. We hope that the availability of free code will encourage browser vendors to support these essential features. Additional information about DSSSL ---------------------------------- A PostScript copy of the DSSSL standard, ISO/IEC 10179:1996, can be found in ftp://ftp.ornl.gov/pub/sgml/wg8/dsssl/dsssl96f.ps.Z ftp://ftp.ornl.gov/pub/sgml/wg8/dsssl/dsssl96b.ps.Z An earlier and almost identical committee draft of the same document is available online at http://occam.sjf.novell.com:8080/dsssl/dsssl96/ Comments on this example and questions relating to DSSSL and SGML should be posted to the comp.text.sgml newsgroup. Jon --- Jon Bosak, Online Information Technology Architect Sun Microsystems, 2550 Garcia Ave., MPK17-101, Mountain View, CA 94043 Davenport Group::SGML Open::ANSI X3V1::ISO/IEC JTC1/SC18/WG8::W3C SGML ERB