Formatting specifications for UBL document types

$Date: 2004/09/09 01:31:36 $(UTC)

Table of Contents

1. Formatting specifications for UBL document types
1.1. The difference between formatting specifications and stylesheets
1.2. Links to specifications for the document types
2. Documentation conventions
2.1. Example form field information item documentation
3. Example implementations
4. Feedback
5. Documentation production notes
5.1. Reported HTML presentation problems

1.  Formatting specifications for UBL document types

This collection contains examples of formatting specifications that can be followed to display instances of Universal Business Language (UBL) document types in human-readable form. Presentational semantics have not been formalized in this version of the UBL schema library, and they may never be formalized due to differing international requirements and conventions for the presentation of information found in business documents.

These specifications must not be considered as reference implementations of UBL or as normative components of the UBL specification; they are merely examples from one of what will probably be many available UBL stylesheet libraries and transformation products and technologies.

The formatting specifications referenced below point to various layouts for the presentation of the information found in UBL instances. Two sets of layouts are simplified presentations of the example Office and Joinery scenarios. The third set of layouts is intended to conform to the United Nations Layout Key for printed business documents, though no attempt has been made to measure their conformance or completeness.

1.1.  The difference between formatting specifications and stylesheets

A formatting specification is a recipe for a stylesheet, but is not in and of itself a transformation script. Writers of stylesheets, programs, or any other open and proprietary transformation technologies rely on formatting specifications for direction regarding content identification and layout.

These formatting specifications follow the documentation conventions described below to indicate which content in an instance of a UBL document type belongs on the page for the sample layout. PDF files are used to illustrate the sample layouts, though in these non-normative samples there are no detailed specifications of layout dimensions and formatting properties per se.

1.2.  Links to specifications for the document types

The following collection of formatting specifications describes candidate renderings for the following UBL document types:

2.  Documentation conventions

The following is an example of the documentation found in a formatting specification for a given field of a form on the rendered output.

2.1.  Example form field information item documentation

Table 1. XPath information

XPath addresses

The box above includes two XML Path Language (XPath) addresses that document the locations of information found in an XML instance. XPath addresses are used in XSLT stylesheets but can be used as above just for documentation because they are independent of the technology being used for transformation. The path is the route from the document element (the first step in the path) through to the information item actually being displayed.

In the first of the two examples above, the item being addressed is the cbc:InvoicedQuantity element that is a child of the cac:InvoiceLine element that is a child of the document element in:Invoice. In the second of the two examples, the item being addressed is the quantityUnitCode attribute of the cbc:InvoicedQuantity element.

The namespace prefixes are arbitrary but follow the documentary conventions used throughout UBL. Each formatting specification enumerates the prefixes used for that document type and the associated normative namespace URI strings.

The documented sections of the formatting specifications are oriented in the order of the fields found in the rendered result, approximately in the order of left to right from top to bottom (with some differences to accommodate logical groupings).

The formatting specifications are meant to be transformation technology agnostic. The specifications indicate what information goes where in the result, not how it gets there. Different implementations of transformation technologies can meet the need for the information found at the specified XPath address to appear at the indicated location on the page.

3.  Example implementations

A number of example implementations must not be considered as reference implementations of UBL formatting specifications or as normative components of the UBL delivery; they are merely examples from what will probably be many available UBL stylesheet libraries.

See FS-implementations.html for a list of known implementations of UBL Formatting Specifications at the time of publication.

4.  Feedback

The UBL committees welcome your input. We need feedback on the utility of the form layouts themselves and on the choice of XPath addresses for information that belongs in the form.

If you have any comments regarding these formatting specifications, please do not hesitate to contact the UBL committees following the directions on the UBL home page.

5.  Documentation production notes

All of the documentation files in these fs/ directories are produced in HTML by formatting source documents edited in XML. These XML source documents can all be found in the fs/xml/ directory and were all validated using the DocBook 4.2 XML Document Type Definition (DTD).

The enhancement stylesheet fs/xml/fsdb2db.xsl transforms a UBL formatting specification written in DocBook to produce an enhanced DocBook instance with some rearranged information for XPath addresses and committee editorial notes.

Off-the-shelf DocBook stylesheets are then used on the enhanced instance to create the resulting HTML, invoked with only the section.autolabel=1 parameter to engage the section numbering.

See for more information on DocBook and for the stylesheets.

5.1.  Reported HTML presentation problems

Some readers of these specifications have reported display problems with the presentation of the XPath addresses. Reports typically indicate a mystery box-like character is being displayed after every oblique in the XPath address. This is caused by the browser not correctly interpreting the Unicode character entity ​ for a zero-width space. When the browser correctly recognizes this character, it is interpreted as a space for the purposes of line-breaking, but the zero-width of the character gives the appearance of the surrounding characters being adjacent (when it is properly interpreted).

To illustrate, the following is the sequence "A​B": "A​B" (which should appear as "AB").