=========================================
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:
Add the new WARNING tag:
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:
So just add something like that for WARNING (you probably don't need
the attributes):
You have now created your own HTML extension. For example, you can
now have the following in your document:
The fan blade is removed by loosening the nut holding it
onto the shaft.
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