Publishing to the Web is More than Converting Data into HTML   Table of contents   Indexes   Towards an SGML Diff Using Temporal Documents
  Mikula  Norbert H. 
 

PDoS - Pinnacles DSSSL-O Stylesheet

 

Stylesheet design for online and paper-based delivery

 Norbert H. Mikula
 

Abstract:

 
 PCIS DSSSL-O Stylesheet (PDoS)
 PCIS - The Pinnacles Component Information Standard is an ISO 8879 application designed to meet the markup needs of the semiconductors industry.
 DSSSL-O is a subset of ISO/IEC 10179 (DSSSL), designed the address formatting requirements in the area of online-display (rendering) of SGML/XML data using DSSSL.
 PDoS is a first attempt to create a DSSSL stylesheet for the PCIS DTD. This paper discusses a variety of aspects encountered/addressed during the development of this prototype stylesheet, such as modular stylesheet design and user configerable stylesheet architectures.
 Testing and development of the presented concepts has been done using James Clark's DSSSL engine Jade and the authors Java based DSSSL renderer Yade.
 

PCIS SGML and the PDoS

 The Pinnacles Component Information Standard is an SGML application, designed to meet the requirements of the semiconductors industry .
 It was designed under the auspices of the Pinnacles Group, a consortium consisting of major companies in the semiconductors industry. The PCIS tag-set is the de-facto standard in the semiconductors industry.
 The idea for this paper emerged during first experiments with a DSSSL stylesheet for the PCIS DTD which would be suitable for both online and paper based delivery. The working title for this stylesheet is the Pinnacles DSSSL Online Stylesheet.
 Due to its experimental status PDoS is far from being complete and was not designed in the spirit of being so. The primary objective was to experiment with different approaches to stylesheet design. The results are discussed in this paper.
 The author of this paper is not affiliated with the Pinnacles Group or any of its members.
 

DSSSL Stylesheet-Design

 Stylesheet design, using DSSSL, is a pretty new discipline. There is not too much experience with designing effective, but still easy to maintain and readable stylesheets that are powerful enough to exploit the potential of DSSSL to the fullest.
 Techniques and ideas pointed out in this paper contain a summary of state of the art approaches to stylesheet design as well as ideas for the future.
 In order to keep the paper at a reasonable size it is assumed that reader has a fundamental understanding of basic DSSSL concepts like the grove, and flow objects.
 
 

The basics

 It takes only to understand and use two basic techniques to enable oneself to design stylesheets that do not look like the famous "spaghetti"-code that was produced by software engineers not too long ago.
 Although already used by almost all stylesheets designers , they are mentioned here in order the help newcomers to avoid the first traps and pitfalls of DSSSL styles.
 
 

Inheritance

 Inheritance might look familiar to many who use techniques which follow the object oriented paradigm. The basic idea is to have characteristics to entities inherited from other entities. The entities participating are in a hierarchical relation, of some sort, to each other.
 In the DSSSL approach the hierarchical relation is based on the flow-object tree. Characteristics which are defined for a certain flow object are inherited to flow-objects which follow that flow object as children.
 Every characteristic is inherited unless it is explicitly specified not to be in this International Standard. (comp. , page 182)
 Because of inheritance we do not have to specify, for instance the desired font-size for every flow object we want to consider. Let's have a look at a document that, just to show the concept, consists of nothing but paragraphs. In this example we specify once the general font-size for our document. The value for this characteristic is then inherited to all its child elements.
 
;;; our document root is container with the ;;; gi : document  (element document   (make scroll       ;;; scroll is the basic fo for online rendering     font-size: 12pt  ;;; here we set the font-size   ) )  ;;; a paragraph   (element p   (make paragraph                      ;;; no need to specify the font-size                      ;;; it is being inherited (12pt)   ) )
 Let's now augment our stylesheet for documents that contain an element of type "header". Maybe we would like to make the font-size of the "header" element type dependent on the document font-size and increase it with respect to this value by a certain factor.
 In DSSSL you can access the value of an inherited characteristic using a function of the canonical form(inherited-c) whereas "c" is the name of an inherited characteristic. Thus,(inherited-font-size) would return the value offont-size at the location in the hierarchy where you access it.
 For our header example we could now say :
 
(element header   (make paragraph     ;;; increase the current inherited font-size by a factor of 1.2     font-size: (* 1.2 (inherited-font-size))    ) )
 But now, if we think about larger style-sheets, we want to change the factor 1.2 and/or want to reuse it at other places. Wouldn't it make more sense to put the value into a variable that can be accessed at any point in our style-sheet ? We could introduce a declaration section in our stylesheet, where we put together variables we need.
 
;;; ===================================================== ;;; = Configure general layout characteristics  ;;; our general document font-size  (define %document-font-size% 12pt)  ;;; factor that we use to size up the font ;;; in case of headings  (define %scaling-factor% 1.2)  ;;; ===================================================== ;;; = Element section  ;;; our document root  (element document   (make scroll     font-size: %document-font-size%     ) )  ;;; a paragraph   (element p   (make paragraph   ) )  ;;; a heading element  (element header   (make paragraph     font-size: (* %scaling-factor% (%inherited-font-size%))    ) )
 Please note the % (percent) signs at the beginning and the end of variable names. These are not required syntactically. However, since variables in DSSSL are sometimes hard to distinguish from (user defined) functions or other symbols, it makes DSSSL stylesheets easier to read.
 
 

Function declarations

 One of the big advantages of DSSSL over other stylesheet mechanisms is its relation to a very popular programming language. A - side-effect free - subset of Scheme, R4RS . compliant, is being used as the host for the so called expression language.
 This fact allows us to add our own functions to stylesheets. During stylesheet design one comes across re-occurring tasks that program descriptions have to be written for. By using a very simple example, I want to show the basic idea.
 Let's say, we have two element types. For both element types, apart from their individual rendering characteristics, we want to add some kind of ruler underneath them. Hence, we could say :
 
(element chaptertitle   ;;; here we have individual characteristics   (sosofo-append     (make rule       color: red3   ;;; color has been defined before     )   ) )  (element sectiontitle   ;;; here we have individual characteristics   (sosofo-append     (make rule       color: blue3 ;;; color has been defined before     )   ) )
 A more efficient approach to the same problem would be to define a function that takes care of adding a ruler to our flow-object. We could even extend the function, so that the desired color is a parameter to the function. Of course this could be extended to pass along other parameters like length, for instance, as well.
 
;;; append a ruler to the sosofo  (define ($add_ruler$ col_ruler) ;;; give the function a name and                                 ;;; declare the parameters   (make rule     color: col_ruler            ;;; use the color that was supplied   ) )  (element chaptertitle   (make paragraph                                 ;;; here we have individual characteristics     ($add_ruler$ blue3)         ;;; and create the ruler   ) )  (element sectiontitle   (make paragraph                               ;;; here we have individual characteristics     ($add_ruler$ blue3)       ;;; and create the ruler   ) )
 The same principle can be applied for more complex functions. A typical scenario would be the definition of a function which is used to create a paragraphs with certain values for characteristics likespace-before andspace-after . This function can then be re-used within a variety of construction rules.
 
;;; define a simple function for creating a ;;; paragraph flow object  (define $para$   (make paragraph     space-before: %normal-para-sep%     space-after: %normal-para-sep%   ) )  (element p ($para$))       ;;; and re-use it  (element intro ($para$))   ;;; and re-use it
 The same technique, of course, can also be applied to inline elements like sequences of bold-characters etc.
 A very good example for such a collection of functions can be found in Jon Bosak's stylesheet for the DOCBOOK DTD. He calls these functions "Common Style Templates". .
 Use of such templates helps a lot to keep the stylesheet at a reasonable size and ehances maintainability, since changes need to be made only for one function declaration.
 

Modular stylesheet design

 Using concepts of modular stylesheet design we are able to create easy-to-maintain DSSSL documents whilst providing the user with the powerful concept of views on documents.
 In the semiconductors industry, as well as in all other fields of document processing, people can have different views on the same document, or, at least they would like to have a more selective access to data if they wouldn't be so restricted by traditional paper-based media.
 Purchasing personnel needs different chunks of a document than, let us say an electrical engineer does. People with impaired vision need to have information presented other than those who don't have this problem. To make things even more complicated, looking at the example of an office application, there might be need to change the view at a document, during the course of a document throughout the workflow of an organization.
 Although DSSSL was designed with "built-in" features for such applications, this kind of approaches, so far, have been neglected to a large extend. However, having support for multiple styles which can be applied to one document instance, was common state of the art in many of the "traditional" SGML browsers which use proprietary approaches to "stylish" SGML.
 Using DSSSL, one can provide different stylesheets for one and the same document. The user selects via his user agent, for instance a DSSSL supported online SGML/XML browser, whichever stylesheets he thinks are appropriate for him. Having this possibility to choose from more than one stylesheet provides us with a very powerful way to add style to SGML/XML.
 DSSSL stylesheets are SGML/XML documents whose DTD conform to a HyTime (ISO/IEC 10744) document architecture as defined in Section 7.1. in the DSSSL standard.
 Let's have a closer look at the following section of an instantiation of the meta-DTD as found at : www.jclark.com/dsssl/examples/style/sgml95.scm.txt. (It has been transformed to the XML-DTD format)
 
<?usercomment  ==================================================== > <?usercomment        style-specification                            > <?usercomment  ---------------------------------------------------- > <?usercomment        Contains a style-specification                 > <?usercomment  ==================================================== >  <!element style-specification - O (%decls;, style*)>  <!attlist style-specification     -- A unique identifier to refer to a certain style --   id id #required    -- a human readable description of the specification --   desc CDATA #IMPLIED    -- is the specification complete or only a fragment --   partial (partial | complete) complete    -- what styles to include --   use idrefs #implied>
 For the purpose of modular stylesheet design, especially one section of this DTD is very interesting : the declaration for the element type "style-specification". We come across the following attributes
  Attribute
 id
  We can use more than one style-specification in a DSSSL document. Hence we need to be able to refer to the one we want to be the "active" one via a unique identifier. SGML/XML provides means to do that, via IDs.
 desc
 Ids are meaningful concepts to computers, database systems and SGML/XML parsers. Human beings have problems to deal with constructs that might look likeid="cv23j" . Easy readability is the reason why I recommend to make use of the desc attribute and to provide a description of what is to be expected when one uses this style specification.
  ISO/IEC 10179 does not really say more about the semantics of this attribute than that it should be a human-readable description. I do recommend to use a meaningful keyword to fill this attribute. This string can then be presented to the user via a menu in the user agent or as a switch on the command line.
 partial
 The "partial" attribute allows us to tell our DSSSL engine and furthermore the user agent whether a certain style-spec is a complete one or if is meant to serve as a module in other style-specifications. Like libraries in the world of programming we can use this concept to keep our specifications maintainable and reusable.
  The attribute allows two possible values, "complete" or "partial". "Complete" indicates a top-level style-specification that should be selectable by the user. "Partial" denotes a fragment that is to be included into other stylesheets.
 use
 Use is finally the way to say what (sub) style-specification we want to make use of.
 
Modular Stylesheets
 Modularization does not have to stop with the design of modules as such. To make delivery and maintenance even easier, DSSSL allows us to include modules per reference.
 
<?usercomment  Assign a local ID to a specification in another document. >    <!element external-specification - O EMPTY>    <!attlist external-specification       dsssl NAME external-specification   id ID #REQUIRED       document -- document containing spec --           ENTITY #REQUIRED       specid -- id of spec in document --           NAME #IMPLIED -- Default: first spec in document -- >
 (comp. , p. 21)
 A user agent, like YADE-AWT, does not need to resolve the reference to a stylesheet(-part) until it is needed. This makes it possible to create a stylesheet that provides style information for many possible application scenarios of a class of documents. The stylesheet could still be kept small and simple. Thus, this would also guarantee faster download times.
 

Viewpoints for PCIS

 The previous section introduced the foundation for having multiple stylesheets for one DTD. These stylesheets can be used to contain different types of rendering of the same document, for instance normal font-size and large font-size, but also to contain stylesheets which create views on documents.
 PDoS, of course, contains one style that looks like most of traditional stylesheets look like. Its primary objective is to resemble, as close as possible, a PCIS instance that would have been send to the printer via the authoring environment.
 But also an alternative approach has been taken. To understand it, we have to take a short look at the PCIS standard.
 The PCIS DTD provides means to keep for almost every chunk of information, the class of information it contains. During the analysis phase for the PCIS standard six classes information have been identified for the information chunks in a document Pinnacles-95, page A-10
 
  • Product Summary Information
    •  
  • Detailed Product Specification Information
    •  
  • Application Information
    •  
  • Safety and Environmental Compatibility Information
    •  
  • Information Concerning Support Tools
    •  
  • Reliability Data
    •  The PCIS DTD allows to preserve the information discussed in the so-called DIV.CLASS attribute which can take one of the six classes of information as its value.
     This DIV.CLASS attribute could be a key candidate for being used as a filter.
     Making use of this attribute as a filter would mean to select elements for rendering depending on the attribute value they possess.
     One of the most powerful, yet still easy to use, pattern-matching techniques are functions that use patterns of a form as required by the DSSSL function(match-element? pattern snl)
     
    (match-element? '("Section" ("DIV.CLASS" "PROD.SUMMARY")) snl )
     Whereassnl is a singleton node-list.
     A matching element for such a pattern would be one which has a certain GI (Section ) and whose attributes have certain values. (In this case only one attribute,DIV.CLASS which should have the value ofPROD.SUMMARY It should be mentioned that even more complex patterns can be constructed by limiting the kind of element types the considered node has as parent(s) and the attribute/value pairs they contain.
     In this described scenario a problem would arise since the DIV.CLASS attribute could occur within many different element types. Hence the basic query would have to be formulated more general.
     
    (match-element? '(() ("DIV.CLASS" "PROD.SUMMARY"))
     Styles for printout and styles for online rendering sometimes require different construction rules. One of the simplest of which is that a stylesheet for printout usually will start with the creation of a simple-page flow object. This flow object requires certain characteristics that only make sense in the area of paper-based delivery (for instancepage-width ).
     A stylesheet that is used solely for online rendering will have , usually, the scroll flow-object as the top-level one.
     Again, modular stylesheet design can save us from having to construct large monolithic stylesheets where no re-use of declarations is possible. The idea is simply to put the core construction rules in a separate module. Then create, two other modules for online, and print-out scenarios respectively. These two modules will then be included in the base module (via theuse attribute). Thus they are able to make use of the routines defined there.
     

    Misc. useful concepts

     
     

    Construction modes

     Construction modes allow the designer to apply different construction rules to grove objects, depending on the context in which the DSSSL engine is, when the relevant part of the tree is traversed.
     In documents, conforming to the PCIS DTD, the author of the document instance has the possibility to put together all kinds of pieces of information about an electrical component. Examples for such chunks are electrical, chemical etc. characteristics.
     These items can then be referred to at various places in the main part of the document. In PCIS terminology the concept is called source (the information item) and reflection (the reference to them).
     One problem that one might come across during stylesheet design is as follows. One might want to apply different characteristics to flow-objects depending on at what location in the document it is referred to. For example we don't want to render "sources" as such, only when we refer to them via reflections. But how to tell the DSSSL engine what rules to use in what context ?
     The DSSSLwith-mode andmode constructs take care of such problems. The canonical form for "mode" is :
     
    (mode mode-name   construction-rule*  ;;; usual DSSSL construction rules )
     In the following example there are two different declarations for element type example. The first one, using the default construction mode will render every character inside the "example" tag with font-weight bold. The section example will make a paragraph out of the "example" content when the construction-mode "mode-a" is being used.
     
    (element example   (make sequence     font-weight: bold   ) )  (mode mode-a   (element example     (make paragraph     )   ) )
     Using "with-mode" we can tell the DSSSL engine what construction mode we want to use.
     
    (with-mode mode-specification   expression* )
     Using our example we can say, knowing that example can be referred to via an ID :
     
    (with-mode mode-a   (process-element-with-id ...)   )
     
     

    Styles

     A style object contains a set of expressions specifying values for inherited characteristics.
     The canonical form is :
     
    (style keyword-argument-list)
     This function returns an object of type "style" that can then be used in construction rules with the help of theuse: keyword. The style function allows
     
    1. to define a group of characteristics that can be reused many times. Making maintenance easy by requiring changes to be made only at one place.
    2. to use an object-oriented approach to the use of characteristics. Theuse: keyword can also be employed inside the style function allowing to built aggregations of styles.
     
     

    Table of Contents

     The basic, automatic, creation of a table of contents in DSSSL is achieved by having two different processing modes, for the actual document and for the table of contents.
     The construction rules in the mode for the table of contents will belong to three different classes.
     
    1. First, a class by itself, is the change from the default construction rules for elements from(process-children) to(empty-sosofo)
    2. Have(process-children) as the construction rule for element types that are parents to elements which are to become entries in the table of contents. (For example aSection beforeTitle )
    3. Apply the entry construction rule to an element which shall become an entry of the table of contents. Here we see yet another example of the advantage of using function declarations. Such a section could look like : 
    (define $add-entry$     ;;; very often creating a cell in a table     ;;; and putting the content of the     ;;; current element into that cell ) (mode toc     (element title   ($add-entry$))        ;;; Class 3                                          ;;; ...    (element section (process-children))   ;;; Class 2                                          ;;; ...    (default         (empty-sosofo))     ;;; Class 1 )
     

    Multi-mode flow objects

     A multi-mode flow object is a flow object with two or more modes of presentation. The flow object can be switched between these modes of presentation in a system-dependent way (comp. , p 291)
     In others words, multi-mode flow objects allow the design, and this is only one of the possible applications of what I want to call "micro-views". Micro-views can help to look at one chunk of information in a multiple way. The default rendering might only provide a summary of the data, the alternative views allow for selective disclosure of more information and/or pointers to other items that are related to the one looked at.
     Note 130 and Note 132 of the DSSSL standard describe one of the possible system-dependent "interpretations" of multi-mode objects. Although, this is a very obvious solution for SGML(XML)/DSSSL based browsers, for traditional print-output it is yet to be seen what the best way to handle this class of flow objects will be.
     In the current implementation of Yade only multi-mode flow-object, with two used ports are supported. One is the default port, the second one is the port for alternative rendering.
     The current RTF backend to Jade doesn't handle the multi-mode fo since there are practical problems associated with it.
     

    Design of (interactively) customizable stylesheets

     The techniques pointed out in the beginning of this report provide sufficient means to design stylesheets that are easy to maintain and customize.
     Especially in the area of online DSSSL systems it will be necessary to provide the user with an interface through which he can customize a stylesheet without having to get down to directly editing it.
     If we look at some of the most mature stylesheets today, for instance the docbook, the TEI or HTML stylespecification, we can see that the overall layout depends mostly on a set of variables which are usually defined at the top of a stylesheet.
     Key candidates for such variables are usually values for the basic document font-size, page characteristics like width (in case of targeted print output) and marginalia. Indentation steps and space after or before flow objects also should be mentioned.
     The user the user does not not need to get the whole stylesheet presented in an editable way. For most cases, having the chance to modify these key characteristics will be sufficient.
     But how to tell the user agent what those mystical variables are and, to make it even easier for user interface design, what values are allowed, what types of values are allowed and in what range must those values be ?
     
     

    A DTD for the definition of user customizable variables

     The following paragraph presents a first sketch of an annotated DTD that could be used to create document fragments which contain the names of key-variables such as outlined above as well as additional information that can be utilized by a user agent to provide a more comfortable interface.
     
    <?usercomment  ====================================================        Customize : Define all elements that should be           presented to the user as customizable variables             ==================================================== >  <!ELEMENT Customize (Variable)* >  <?usercomment  ====================================================        Variable : One customizable variable          If no value specified, then any value will do        ==================================================== >  <!ELEMENT Variable (Description*,Value*) >  <?usercomment  ====================================================        Variable :                                                  ====================================================        Name : The name of the variable as it is used in the         DSSSL style specification                                   ==================================================== >  <!ATTLIST Variable      Name CDATA #REQUIRED>  <?usercomment  ====================================================        Value : One possible value of the variable                   ==================================================== >  <!ELEMENT Value (Description*,(Content|Type)) >  <?usercomment  ====================================================       Type : A valid type       ==================================================== >  <!ELEMENT Type (Description)* >  <?usercomment  ====================================================       Type :       ====================================================       Class : A list of valid types for that variable       (possible values need to be discussed)       ==================================================== >   <!ATTLIST Type       Class (String|Number|Length) #IMPLIED>  <?usercomment  ====================================================       Content : The actual content of the variable                     as it would be delivered to the DSSSL engine       ==================================================== >  <!ELEMENT Content (#PCDATA)* >  <?usercomment  ====================================================       Description : Description of a variable or possible        value       ==================================================== >  <!ELEMENT Description (#PCDATA)* >  <?usercomment  ====================================================       Description :       ====================================================       Language : The language that has been used in the       description       ==================================================== >   <!ATTLIST Description     Language CDATA #IMPLIED>
     Yade already supports these "extensions" in a proof of concept like fashion.
     

    ACKNOWLEDGEMENTS

     Techniques which are pointed are here, comprise and summarize to a large extend the work of many other DSSSL and SGML/XML experts.
     I want to bring to attention the names of Jon Bosak (Sun Microsystems) who is the main author of both the HTML stylesheet as well as the DSSSL style for the DOCBOOK DTD. Richard Light created an equally impressive piece of work, the stylesheet for TEI-Lite print output. Anders Berglund (EBT) saved us from working out a DSSSL style for SGML Open TR 9503:1995 conforming table data. Those who tried it themselves (like the author) can really appreciate how much effort he spared them.
     The current implementation on user customizable variables was discussed on the DSSSL mailing which is maintained by Mulberry Technologies.
     I also want to thank James Clark for giving my idea of user customizable variables an all new direction.
     

    BIBLIOGRAPHY

     
  • [Goldfarb-90] C. Goldfarb, The SGML Handbook, Oxford University Press, 1990
    •  
  • [Pinnacles-95] The Pinnacles Group, Pinnacles Component Information Standard 1.2 - Final Draft, The Pinnacles Group, 1995
    •  
  • [DSSSL-96 ] Joint Technical Committee ISO/IEC JTC1, Information technology, ISO/IEC 10179:1996 Information technology -- Processing languages -- Document Style Semantics and Specification Language (DSSSL), ISO/IEC 1996
    •  
  • [XML-WD-96 ] T. Bray, C. Sperberg-McQueen (Editors) Extensible Markup Language (WD-xml-970331) W3C,1996
    •  
  • [BosakDoc-96] Jon Bosak, DSSSL style sheet for DocBook 2.x and 3.x print output, http://sunsite.unc.edu/pub/sun-info/standards/dsssl/stylesheets/docbook/db068b. .dsl
    •  
  • [BosakHTML-96] Jon Bosak, DSSSL stylesheet for HTML 3.2, http://sunsite.unc.edu/pub/sun-info/standards/dsssl/stylesheets/html32/html32hc c.dsl
    •  
  • [LightTEI-96] Richard Light, DSSSL stylesheet for TEI-Lite, http://sunsite.unc.edu/pub/sun-info/standards/dsssl/stylesheets/tei/tei-dsl.zip p
    •  
  • [R4RS-91] William Clinger and Jonathan Rees (Editors), Revised4 Report on the Algorithmic Language Scheme, http://www.cs.indiana.edu/scheme-repository/doc.standards.html
    • Publishing to the Web is More than Converting Data into HTML   Table of contents   Indexes   Towards an SGML Diff Using Temporal Documents