NOTES ON THE MAIL EXAMPLES

The file mail.sgm contains an SGML document instance marked up
according to the grammatical rules specified in mail.dtd.  Each of the
stylesheets mail-<n>.dsl is applied to the document in turn to produce
the Jade output files mail-<n>.rtf and then (using a word processing
program) into the PostScript printer files mail-<n>.ps.


mail.sgm
--------

This document type definition (DTD) specifies a simple markup language
for electronic mail messages.

   <!element mail - - (to, from, date, subj, body) >
   <!element to   - - (#PCDATA)                    >
   <!element from - - (#PCDATA)                    >
   <!element date - - (#PCDATA)                    >
   <!element subj - - (#PCDATA)                    >
   <!element body - - (para|code)+                 >
   <!element para - - (#PCDATA)                    >
   <!element code - - (#PCDATA)                    >

In English, this says: A mail message consists of a single MAIL
element.  A MAIL element consists of one TO element, one FROM element,
one DATE element, one SUBJ element, and one BODY element, in that
order.  TO, FROM, DATE, and SUBJ elements consist merely of
characters; they contain no further subelements.  The BODY element, on
the other hand, consists of any number of PARA and/or CODE elements in
any order; there must be at least one PARA or CODE element.  PARA and
CODE elements consist only of characters and contain no further
subelements.


mail.sgm
--------

This file contains a mail message marked up in the language defined by
mail.dtd.

   <!doctype mail system "mail.dtd">
   <mail>
   <to>bosak@boethius.eng</to>
   <from>Information Services</from>
   <date>Fri, 6 Dec 1996 21:27:55 -0800</date>
   <subj>perfset1-14400</subj>
   <body>
   <para>I killed your process running on jurassic:</para>
   <code>
   USER       PID %CPU %MEM   SZ  RSS TT       S    START  TIME COMMAND
   bosak    20109 21.6  0.2  952  656 ?        O 15:11:39 246:26 perfset1-14400
   </code>
   <para>It had been running for 6 hours and was consuming almost 100% of
   a cpu.</para>
   <para>You really should run this sort of program on a machine
   other than the mpk17 building server.</para>
   </body>
   </mail>


mail-1.dsl
----------

A basic stylesheet for hard copy.

The construction rule for the root element MAIL produces a
simple-page-sequence and establishes the basic look of the document.
Most of the characteristics specified for simple-page-sequence are
inherited by its flow children.

   (element MAIL
     (make simple-page-sequence
	   font-family-name: "Arial"
	   font-weight: 'medium
	   font-posture: 'upright
	   font-size: 12pt
	   line-spacing: 14.4pt
	   top-margin: 6pica
	   bottom-margin: 8pica
	   left-margin: 6pica
	   right-margin: 6pica
	   page-width: 8.5in
	   page-height: 11in
	   input-whitespace-treatment: 'collapse
	   quadding: 'start
	   (process-children)))

Note that left justification is specified by giving the value "start"
for the quadding characteristic.  Unlike most stylesheet languages,
DSSSL makes no assumptions about whether the script being displayed is
written from left to right, right to left, or top to bottom.
Consequently, the values "start" and "end" are used for what in
English would ordinarily be specified as "left" and "right" but in
Hebrew or Arabic (for example) would be "right" and "left".  The
absolute values "left", "right", "top", and "bottom" are used only for
script-independent flow objects such as pages themselves.

The construction rules for TO, FROM, DATE, and SUBJ behave almost
identically to one another.  In each case, a paragraph is constructed
that begins with a bold sequence of generated characters (one of the
strings "To: ", "From: ", "Date: ", or "Subject: ") followed by the
contents of the element.  Here is the construction rule for the DATE
heading.

   (element DATE
     (make paragraph
	   (make sequence
		 font-weight: 'bold
		 (literal "Date: "))
	   (process-children)))

This makes a paragraph flow object that begins with a generated
sequence of characters ("Date: ") set in bold.  Then the function
process-children specifies that this sequence will be followed by a
series of characters (the children of the paragraph) that make up the
content of the DATE element.

The construction rule for BODY is used to create a display group
wrapper for the purpose of adding space above and below the contents
of BODY.

   (element BODY
     (make display-group
	   space-before: 18pt
	   space-after: 18pt
	   (process-children)))

Note that this 18pt space is not simply added to the 6pt space of the
first child PARA (see next); rather, the larger of the two spaces is
taken as the space to be applied.  This allows the stylesheet designer
to specify vertical spacing without calculating every possible
combination of adjacent flow objects.

PARA creates a paragraph that inherits most of its characteristics
from simple-page-sequence.  In this example, only space-before and
space-after need be specified.  Internationalization is maintained by
using "space-before" and "space-after" rather than "space-above" and
"space-below".

   (element PARA
     (make paragraph
	   space-before: 6pt
	   space-after: 6pt
	   (process-children)))

Unlike PARA, CODE must override several characteristics that would
otherwise be inherited in order to produce formatting appropriate to
computer output of some kind.

   (element CODE
     (make paragraph
	   space-before: 12pt
	   space-after: 12pt
	   font-family-name: "Courier New"
	   font-size: 10pt
	   line-spacing: 12pt
	   lines: 'asis
	   input-whitespace-treatment: 'preserve
	   (process-children)))


mail-2.dsl
----------

The construction rules for TO, FROM, DATE, and SUBJ in mail-1.dsl
largely duplicate one another.  In the second version of the
stylesheet, the part that is common to each of these four construction
rules is extracted into a single "template" function called
$header-entry$.

   (define ($header-entry$ label)
     (make paragraph
	   (make sequence
		 font-weight: 'bold
		 (literal
		  (string-append
		   label
		   ": ")))
	   (process-children)))

The part that is unique to each construction rule is passed as a
parameter to $header-entry$, as shown in the four lines that follow.
(The name "template function" and the "$" notation are just
conventions of the author, not part of DSSSL.)

   (element TO ($header-entry$ "To"))
   (element FROM ($header-entry$ "From"))
   (element DATE ($header-entry$ "Date"))
   (element SUBJ ($header-entry$ "Subject"))

For example, the construction rule

   (element TO ($header-entry$ "To"))

passes the string "To" to the function $header-entry$.  In that
function, "To" becomes the value of the label variable.  As before, a
paragraph is made that begins with a generated sequence of bold
characters, only in this case the sequence consists partly of the
string passed into the function and partly of the fixed sequence ": ".
The string-append function is used to catenate label and ": ".

The new stylesheet is functionally identical to the old one and
produces the same output.


mail-3.dsl
----------

The third example shows some simple parameterization.  The idea is to
make it easy to apply relatively large changes to a stylesheet by
using parameters rather than hardcoded values.  Nothing magical here,
just the notion of a named variable.

In the example, the size of the CODE font and all of the vertical
spacing has been tied to the size of the body font.  This is set near
the top of the stylesheet by defining the variable %bf-font% to be
12pt.  The monospace-font size %mf-size% is calculated by subtracting
2pt from the body-font size, and line spacing is calculated by
multiplying the font size by the constant factor 1.2.  Vertical
spacing is also calculated from %bf-size%.  (As before, the "%"
notation for parameters is just a private convention of the author,
not a part of DSSSL.)

Since all the calculated values in this case are identical to the
hardcoded values in the previous examples, the output is again
unchanged.


mail-4.dsl
----------

In this example and the next, the setting for %bf-size% is changed
from 12pt to 10pt show the effect of adjusting a parameter on the look
of the document.  Now the output is noticably different from what it
was before.


mail-5.dsl
----------

Changing %bf-size% to 24pt scales everything up instead of down.
Since all the vertical spacing was tied to the body font size, most of
the output looks pretty good despite the large change.  The exception
is the CODE segment, which falls apart when the nonwrapping lines
encounter the fixed page boundary.

Exercise: Rewrite the CODE construction rule so that the size of the
monospaced font is calculated from the available width (equal to the
page width less the left and right margins).  Assume that every CODE
line is 80 characters wide and calculate the font size that will fit
80 characters into the space available.  (You will have to discover an
empirical factor that depends to some extent on the particular type
face used for the monospaced font.)


mail-6.dsl
----------

Returning to mail-3.dsl, we notice that the "To", "From", "Date", and
"Subject" headings have rather a nondescript look.  Let's put the
generated text in a right-justified line field adjacent to the
left-justified contents of each heading:

   (define ($header-entry$ label)
     (make paragraph
	   (make line-field
		 field-width: 6pica
		 field-align: 'end
		 font-weight: 'bold
		 (literal
		  (string-append
		   label
		   ": ")))
	   (process-children)))

This creates a paragraph flow object that begins with a line-field 6
picas wide into which are flowed the characters of the generated
label.  The right justification within the line field is specified by
a field-align value of "end" (i.e., the end of the character
escapement direction in a script that is written from left to right).
The content of the line field ends with the colon and space of the
literal, and the remaining characters of the heading (the children of
the paragraph flow object) immediately follow the line field, aligned
on the starting (i.e., left) edge of the paragraph by default.

If you change the body font to a larger size by setting the %bf-size%
parameter to 24pt (say), you will find that the line field no longer
accommodates all the heading labels.  Exercise: Compute the width of
the line field based on the size of the body font.

J. Bosak 1997.02.28

