Using Crane's Universal Business Language (UBL) Stylesheet Library

Author: G. Ken Holman
Date: $Date: 2003/02/14 04:13:31 $(UTC)

Copyright (C) 2003 Crane Softwrights Ltd.
http://www.CraneSoftwrights.com

 Crane Logo

Table of Contents

1 Abstract
2 Status and Download
2.1 Known limitations
3 Approach to using this library
3.1 Advantages
3.2 Disadvantages
4 Formatting Specifications
4.1 Publicly available formatting specifications
4.2 Office-oriented layouts
4.2.1 Office Order
4.2.2 Office Order Response Simple
4.2.3 Office Despatch Advice
4.2.4 Office Invoice
4.3 Joinery-oriented layouts
4.3.1 Joinery Order
4.3.2 Joinery Order Response
4.3.3 Joinery Despatch Advice
4.3.4 Joinery Invoice
4.4 UN Layouts
4.4.1 UN 220 Order
4.4.2 UN 320 Order Response
4.4.3 UN 351 Despatch Advice
4.4.4 UN 380 Invoice
4.4.5 UN X01 Order Response Simple
4.4.6 UN X02 Order Cancellation
4.4.7 UN X03 Receipt Advice
5 Using the stylesheet library
5.1 Library contents
5.2 Managing imported stylesheets
5.3 Using the stylesheets with your UBL instances
5.4 Customizing the UBL stylesheets
5.5 Sample renderings
5.5.1 Reviewing the sample input data renderings
5.5.2 Reviewing the diagnostic key renderings
5.5.2.1 Important warnings regarding diagnostic key files
5.5.3 Rebuilding the test renderings
6 Utility stylesheets
6.1 fo2html.xsl
6.2 fo2htmlk.xsl
6.3 notitle.xsl
7 Licensing
8 Next steps for the stylesheet library
9 Feedback
9.1 Appeal for more test data
9.2 Reference books and training

1: Abstract

The Universal Business Language (UBL) http://www.oasis-open.org/committees/ubl/ project is developing a standard library of XML business documents. This library comprises document models expressing the structure of electronic messages transmitted between systems and programs.

A stylesheet library bridges the gap between the XML electronic message instance and the human reader by rendering the content of the message in a presentation form. This presentation form is not suitable for machine processing, but is designed for the human consumption of the visual layout through a rendering medium such as a web browser, page browser or printed paper.

Crane Softwrights Ltd. has developed a prototype UBL stylesheet library, the latest released version of which is always available through http://www.CraneSoftwrights.com/links/res-ubl.htm for use with XML instances of the UBL document models. This will not be the only stylesheet library or even a reference stylesheet library. Rather, it is just one of what is sure to be many available stylesheet libraries for use with UBL.

This document describes the contents and use of this library, including all business rule and rendering assumptions in the absence of formal formatting specifications.

2: Status and Download

The current stylesheet library is a prototype for experimentation and not meant for production use. It is based on the schema library in UBL LCSC version 0p70 available from the UBL home page noted above. Due to the prototype status of the schema library, only a few of the document types are accommodated properly in this prototype of the stylesheet library. Many of the documents are merely layouts of boxes without acting on live data. The objective of releasing only a prototype is to get feedback from candidate users of stylesheets for UBL documents.

The following downloads are available:

Note that the housekeeping of directories at Crane Softwrights Ltd. often undergoes review and may change. Please refrain from pointing directly to the subdirectories or the downloadable compressed files. If you would like us to create on our site a custom persistent link to our Free Resource Library where the UBL stylesheet library is found, for you to point to this resource directory from your site, please do not hesitate to ask.

2.1: Known limitations

At this time formal continuation pages are not implemented, but for a number of the forms the first-page will be repeated with the items properly grouped on each page. A page number has been added to the top right to indicate the length of the document. Overflowing any other field will produce an overflow error that may be reported by the XSL-FO engine.

3: Approach to using this library

This methodology always produces a rendering suitable for either US-letter or A4 page print, but may have localized differences in ordering (but not content) targeted for HTML output. To guarantee consistency of the shared output, the HTML stylesheet imports the A4 page stylesheet and the content rendering is derived from the print rendering. To guarantee consistency of the US-letter rendering from the A4 page rendering, the US-letter stylesheet imports the A4 page stylesheet such that its page dimensions are overridden. According to UN layout rules the form content dimensions do not change and page size differences are accommodated by sacrificing margins on the right and bottom edges. The UN guidelines are used as the margin template for all forms.

The process can be overviewed as follows:

The Crane methodology for UBL instance formatting
Figure 1: The Crane methodology for UBL instance formatting

Instances of UBL document models are transformed to instances of XSL-FO using one of Crane's three UBL stylesheets for each layout for the document's type. The print-ordered XSL-FO instances may be processed by conformant XSL-FO engines to produce a print rendering, such as a PDF file, though this is not mandatory. The browser-ordered XSL-FO instances are input to an XSLT transformation (using the fo2html.xsl stylesheet described below in the utilities descriptions) to produce an HTML page.

All of the results are distinguished uniquely by combining the name of the layout with the name of the instance with the file extension of the result.

3.1: Advantages

The primary advantage of this approach is the guaranteed consistency between both the printed and browsed renderings. The main form content of the browsed rendering is derived directly from the printed rendering. The marginalia is all that is changed for the HTML pages. Note that the two-step process of producing HTML through XSL-FO does not incur very much overhead the instances are small.

3.2: Disadvantages

The primary disadvantage of this approach is the inability to take advantage of powerful print layout facilities for the content of the form in order to restrict oneself to the lowest common denominator acceptable to both the printed rendering and the browsed rendering. Fancy features typical of custom-designed HTML presentation commonly found on web pages are not available in these renditions. An example would be descriptive pop-ups when hovering over fields of the form. The HTML renderings differ from the print renderings only in the location of meta data in the marginalia.

4: Formatting Specifications

At this time of writing the formal UBL formatting specifications are in a nascent stage, as presentational properties are not specified in the libraries in phase one of UBL. Sample requirements are captured and example renderings are provided as part of the UBL project, though these may never become standardized or normative due to the many and varied presentations of business information in documents around the world.

The specifications are mimics without any sanctioned interpretations of the fields of the UBL document models. Help is needed understanding where these libraries fail to meet user expectations. If you can help us in the interpretation of these fields, it will help all UBL users of this library. Please refer to the section below regarding feedback.

4.1: Publicly available formatting specifications

This library was developed following the nascent UBL formatting specifications that mimic the layouts found in the UNECE Document Development Toolkit for Trade Facilitators found at http://www.unece.org/etrades/unedocs/toolset.htm and some conceptual layouts for documents that do not formally exist.

The document rec01_1981_ecetrd137.pdf in the toolset specifies the page and common image area constraints that all printed forms must respect. Paragraph 22 specifies the top (gripper) and left-hand (filing) margins as 10mm and 20mm respectively. Paragraph 20 specifies the common image area as 183mm by 262mm, with US-letter and A4 page size differences accommodated in the bottom and right-hand margins accordingly. These are adopted for portrait presentations, and in the top and left-hand margins for landscape presentations. The print stylesheets attempt to adhere to these rules precisely.

4.2: Office-oriented layouts

These layouts are meant to convey a presentation typical of what might be used in office environments.

4.2.1: Office Order

The implementation for this library's stylesheet for this document type is described in OfficeOrder, with links to example PDF and HTML renderings.

4.2.2: Office Order Response Simple

The implementation for this library's stylesheet for this document type is described in OfficeOrderResponseSimple, with links to example PDF and HTML renderings.

4.2.3: Office Despatch Advice

The implementation for this library's stylesheet for this document type is described in OfficeDespatchAdvice, with links to example PDF and HTML renderings.

4.2.4: Office Invoice

The implementation for this library's stylesheet for this document type is described in OfficeInvoice, with links to example PDF and HTML renderings.

4.3: Joinery-oriented layouts

These layouts are meant to convey a presentation typical of what might be used by a joinery or cabinet-maker.

4.3.1: Joinery Order

The implementation for this library's stylesheet for this document type is described in JoineryOrder, with links to example PDF and HTML renderings.

4.3.2: Joinery Order Response

The implementation for this library's stylesheet for this document type is described in JoineryOrderResponse, with links to example PDF and HTML renderings.

4.3.3: Joinery Despatch Advice

The implementation for this library's stylesheet for this document type is described in JoineryDespatchAdvice, with links to example PDF and HTML renderings.

4.3.4: Joinery Invoice

The implementation for this library's stylesheet for this document type is described in JoineryInvoice, with links to example PDF and HTML renderings.

4.4: UN Layouts

Document type descriptions are copied from the United Nations Layout Key for Trade Documents, Guidelines for Application, Informative Annex to Recommendation 1, 2002 rec01_guidlines.pdf found in the UNECE toolset referenced above.

Where UN forms are not available for document types, this library uses an extended number system "X##". Should appropriate standardized forms be identified for a given extended document type, the number will change in a future version of this library.

At this early stage, the layouts give an indication of the shape of the form, but the formal guidelines mapping UBL constructs to UN fields has not been finalized. Most of the stylesheets will not yet act upon live instances of UBL documents, though this will come shortly after the UBL formatting specifications are written.

4.4.1: UN 220 Order

Document by means of which a buyer initiates a transaction with a seller involving the supply of goods as specified, according to conditions set out in an offer, or otherwise known to the buyer.

The implementation for this library's stylesheet for this document type is described in UN220order, with links to example PDF and HTML renderings.

4.4.2: UN 320 Order Response

Document acknowledging an undertaking to fulfill an order and confirming conditions or acceptance of conditions.

The implementation for this library's stylesheet for this document type is described in UN320orderResponse, with links to example PDF and HTML renderings.

4.4.3: UN 351 Despatch Advice

Document by means of which the seller or consignor informs the consignee about the despatch of goods.

The implementation for this library's stylesheet for this document type is described in UN351DespatchAdvice, with links to example PDF and HTML renderings.

4.4.4: UN 380 Invoice

Document claiming payment for goods supplied under conditions agreed between buyer and seller.

The implementation for this library's stylesheet for this document type is described in UN380Invoice, with links to example PDF and HTML renderings.

4.4.5: UN X01 Order Response Simple

The implementation for this library's stylesheet for this document type is described in UNX01OrderResponseSimple, with links to example PDF and HTML renderings.

4.4.6: UN X02 Order Cancellation

The implementation for this library's stylesheet for this document type is described in UNX02OrderCancellation, with links to example PDF and HTML renderings.

4.4.7: UN X03 Receipt Advice

The implementation for this library's stylesheet for this document type is described in UNX03ReceiptAdvice, with links to example PDF and HTML renderings.

5: Using the stylesheet library

5.1: Library contents

The root directory of the stylesheet library contains:

Each document type's subdirectory is named with the base name of "doctype" with no extension suffix, as in "Order", and contains the following subdirectories:

See Figure 1: The Crane methodology for UBL instance formatting for the data flow using these files.

5.2: Managing imported stylesheets

A number of the stylesheets import other stylesheets in order to accomplish their ends. These imported stylesheets are copied into each of the delivered directories so that each directory's stylesheets are self-contained. When you copy any of Crane's UBL Stylesheet Library stylesheets to another directory, please be sure to copy any imported stylesheets that are required.

5.3: Using the stylesheets with your UBL instances

The stylesheets in this library are ready for use without any preparations. Of course you must use the command line invocation specific to your XSLT processor; the examples below assume the input file is the first argument, the stylesheet is the second argument, and the output file is the third argument.

Each document type has a single stylesheet file assuming the A4 page dimensions with the suffix "layout.xsl". An example of running this file to produce an XSL-FO instance is as follows:

To create a result in US-letter page dimensions, utilize the importing stylesheet "layout-us.xsl" that in turn utilizes layout.xsl. An example of running this file to produce an XSL-FO instance is as follows:

The produced XSL-FO instance in both cases can be processed by an XSL-FO engine to produce PDF.

You can also choose to create an HTML rendering of your input file utilizing the importing stylesheet "layout-htmlfo.xsl" to arrange the information accordingly in an XSL-FO instance and then using the fo2html.xsl stylesheet cited in the methodology description above:

Note how it is not necessary to produce the PDF file in order to produce the HTML file. The HTML file is generated from the intermediate XSL-FO file produced by this library's document type stylesheet. A copy of fo2html.xsl is included in the library.

5.4: Customizing the UBL stylesheets

The stylesheets in this library are designed at a very high level of granularity in order to provide for easy customization using the XSLT xsl:import facility. Any top-level construct of the imported stylesheet can be overridden with custom behavior and definition by the importing stylesheet. This is a standardized facility of XSLT and is available in all conforming processors.

Two working examples of this overriding are included with every document type. Both layout-us.xsl and layout-htmlfo.xsl are included with every document type stylesheet layout.xsl. The essence of this importing stylesheet demonstrates how one can customize Crane's stylesheet behavior without modifying the stylesheet files themselves: create your own importing stylesheet to override top-level descriptions in Crane's stylesheets. Consider how the page dimensions are changed without changing the stock stylesheet:

5.5: Sample renderings

Two kinds of renderings are supplied in the library: sample input data and key data. We are always on the lookout for more sample data; if you have any to share with us, please see the feedback section below.

Note the PDF in this library is produced using the Antenna House XSL Formatter Version 2.3 http://www.AntennaHouse.com (with their gracious permission) to produce PostScript from XSL-FO and GhostScript AFPL http://www.GhostScript.com to distill PDF from the PostScript.

5.5.1: Reviewing the sample input data renderings

A number of test data files are included in this stylesheet library (more are needed, please see the feedback section below for more details). The list of these files is maintained in the XML instance script.xml found in the base directory of the library.

Nothing needs to be run in order to review the renderings of the test files in the stylesheet library. For each test file in each document type, three renderings are available for immediate review:

5.5.2: Reviewing the diagnostic key renderings

Keyed renderings differ from standard renderings in that a reference to the field is displayed, not the field value. A reference is of the forms "!##!" and "!##.##!" indicating unique values for each element and attribute respectively. Key references are useful of for diagnosing the actual behavior of a stylesheet.

The key values in the HTML rendering are "hot" in that they can be clicked on by the operator. When using Internet Explorer, hovering over the hot area displays the associated XPath address in the status line, while clicking on the hot area this brings up a supplemental browser window and navigates the operator to the key field in the key report HTML document.

If you wish to correlate the information in the sample data renderings to the locations in the input files, there is a keyed version of each sample input file that is rendered in both PDF and HTML with an associated report of the correlations between the key field display values and the input XML data. All these files are in the debug directory that is only found in the debug configuration of the library; this directory is absent in the standard configuration of the library.

5.5.2.1: Important warnings regarding diagnostic key files

PLEASE NOTE THESE IMPORTANT WARNINGS:

5.5.3: Rebuilding the test renderings

You do not need to rebuild the test renderings in order to utilize the stylesheets in this library, though the script to do so is included should you wish to test changes you make to the stylesheets.

A Python http://www.Python.org script named "runos.py" must be customized to your environment for whichever XSLT, XSL-FO and PostScript distiller processors you use. You will find example invocations of a number of applications in the example supplied.

From the root directory of the library, run the Python script "run.py" in order to rebuild the test renderings:

6: Utility stylesheets

These stylesheets are utilized, or available to be utilized, in the processing flow of instances of the document types.

6.1: fo2html.xsl

This stylesheet converts an instance of XSL-FO to an equivalent instance of HTML. This is a critical part of the process flow as the document type stylesheets only produce the XSL-FO vocabulary for the layout result, with one organization of the marginalia for print and a different organization of the marginalia for conversion to HTML using this stylesheet.

This stylesheet is written by RenderX and a copy is included (with their gracious permission) in this library. Please see their web site at http://www.RenderX.com for any possible updates to the copy that is included in this package.

6.2: fo2htmlk.xsl

This stylesheet imports fo2htmlk.xsl overriding the rendering of text fields, looking for key fields as formatted in Crane's UBL stylesheet library. All key fields are hyperlinked to the associated key report file, such that clicking on the rendered key field will navigate the operator to the report document, aligned to the desired key field.

6.3: notitle.xsl

Some XSL-FO engines choose to render a page sequence title on the canvas, while many engines choose not to do so. These stylesheets assume the title is not rendered on the canvas. If you are using an engine that does render the title on the canvas, use this stylesheet after producing the XSL-FO instance with the print organization of marginalia to remove the page sequence title before passing the instance to the XSL-FO engine.

Do not run this stylesheet on the XSL-FO instance with the HTML organization of marginalia because the page sequence title is used as the title of the HTML page that is rendered in the title bar of the browser window.

7: Licensing

All stylesheet components in this library that are authored by Crane Softwrights Ltd. contain the following copyright and license statements:

Copyright (C) - Crane Softwrights Ltd. 
              - http://www.CraneSoftwrights.com/links/res-ubl.htm

Redistribution and use in source and binary forms, with or without 
modification, are permitted provided that the following conditions are met:

- Redistributions of source code must retain the above copyright notice, 
  this list of conditions and the following disclaimer. 
- Redistributions in binary form must reproduce the above copyright notice, 
  this list of conditions and the following disclaimer in the documentation 
  and/or other materials provided with the distribution. 
- The name of the author may not be used to endorse or promote products 
  derived from this software without specific prior written permission. 

THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR 
IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES 
OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN 
NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 
SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED 
TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR 
PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF 
LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING 
NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, 
EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Note: for your reference, the above is the "Modified BSD license", this text was obtained 2002-12-26 at http://www.xfree86.org/3.3.6/COPYRIGHT2.html#5

Any changes you may make to the stylesheets are not obliged to be forwarded back to Crane, though that courtesy would be very much appreciated in order for any unencumbered modifications to be considered for inclusion in the publicly available library for everyone to use.

8: Next steps for the stylesheet library

The current version of this stylesheet library is geared for version 0p70 of the UBL LCSC schema library, and will be modified on an as-required basis to accommodate changes in and revelations regarding the document models.

No publishing dates are yet scheduled for an update to this prototype stylesheet library. The effort put into this library will be directly proportional to the input, test files and enthusiasm fed back from possible users of the stylesheets.

Please let us know if you wish to be informed of any updates to this stylesheet library.

9: Feedback

Feedback is very important to us from the many kinds of users of our UBL Stylesheet Library. Our formatted output specification assumptions are just that: assumptions. If you are aware of documented rules for the rendering of UBL documents, please help us help you by pointing us where we can find formal rules. We do not want our assumptions propagated around the industry without them being sanctioned by authoritative users and developers.

Feedback can be directed to ubl@CraneSoftwrights.com for consideration.

Please note that our resources are limited and we can only respond with updates to this freely available stylesheet library on a best-effort basis given the circumstances of our work load and travel schedules. We may not be in a position to respond to all feedback that arrives, but please do not let this deter you from contributing, as all contributions will be considered for action. Thank you for your understanding.

We sincerely hope you find this library useful.

9.1: Appeal for more test data

If you are in a position where you can help us by sending us sample conforming UBL data for any of the UBL document models, would you please consider doing so? If you can, then also please tell us if we are allowed to use this test data in a published stylesheet demonstration suite, or if we must keep the data privately to ourselves.

Any help you can be in this regard would be greatly appreciated.

9.2: Reference books and training

If your feedback is "where do I learn more about XSLT and XSL-FO?", please visit http://www.CraneSoftwrights.com/links/info-ubl.htm where we have information on three ways we can help you at Crane Softwrights Ltd.:

Our book sales link on our home page lists electronic publications we have available for sale for either individual use, geographic staff site use, or world-wide staff use. We offer perpetual free updates of any publication for all future editions of that electronic book. Links to paper renditions by Prentice Hall are also given, though free updates of paper books are not being offered.

Our training courses and schedule link on our home page lists where Crane and its world-wide licensees deliver instructor-led training to public audiences. Crane is based in Ottawa Canada and periodically offers public training courses inviting students from around the world to this picturesque city for in-depth hands-on training in XML technologies.

Our past history link on our home pages summarizes when we have be contracted world-wide to deliver training, either to private or public audiences. Consider hiring us to teach your staff at your premises, possibly opening up the delivery to the local public to help defray costs.

We look forward to the opportunity to service your needs in these areas.


Using Crane's Universal Business Language (UBL) Stylesheet Library
G. Ken Holman
Copyright (C) 2003 Crane Softwrights Ltd.
$Date: 2003/02/14 04:13:31 $(UTC)