OASIS Specification Publishing in DocBook XML Version 0.8

This document details an environment [Spec-0.8-ZIP] and methodology for writing an OASIS specification or an OASIS note document using DocBook XML markup, and publishing the resulting document to HTML and PDF results conforming to OASIS layout conventions.

These stylesheets use XSLT [XSLT] as the transformation expression language to produce the final HTML result. XSLT is also used to produce the intermediate XSL-FO [XSL-FO] pagination semantics, which in turn are available to be processed to produce printable results as a PDF file using an appropriate processor (not included).

These stylesheets are zipped [Spec-0.8-ZIP] in a turnkey environment ready to unpack for offline use. The environment is used to validate DocBook XML, render HTML and create XSL-FO suitable for processing with an XSL-FO engine (which is not included). Of course one is not obliged to use the processors referenced as one can use any XML DTD validation tool and any XSLT processor.

The package can be downloaded from https://docs.oasis-open.org/templates/DocBook/spec-0.8/oasis-specification-0.8-wd05.zip and is expected to be unzipped into a local directory for offline use. The examples in this documentation assume the package is unzipped in a Windows environment into the c:\ directory, and in a Linux environment in one’s home directory. For example purposes, it is assumed that the ZIP file contents (all files starting with spec-0.8/) are installed in the c:\oasis\spec-0.8\ directory or ~/oasis/spec-0.8/.

See Appendix C, Publishing choreography and orchestration (Non-Normative) for details on a set of invocations for validating OASIS specification documents and producing an HTML rendering suitable for web browsers and an XSL-FO result suitable for an XSL-FO engine. Neither a browser nor an XSL-FO engine are themselves included in the package.

The DocBook Document Type Definition (DTD) expresses the constraints of using elements and attributes, but not necessarily the conventions imposed by the OASIS TC Administration. Just having your specification validate with the DTD does not guarantee that you’ve used the correct or appropriate DocBook constructs to produce the required output. This package includes Section 3.5, “ Pro forma templates” illustrating the conventional use of the DocBook constructs.

To assert in the online OASIS environment that your XML document satisfies the constraints of DocBook, point to the posted copy of the DTD:

<!DOCTYPE article
  PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
         "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"

To assert in an embedded environment that your XML document satisfies the constraints of DocBook, point to the embedded copy of the DTD:

<!DOCTYPE article
  PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" 
         "htmlruntime/spec-0.8/docbook/docbookx.dtd"

To assert in an offline local environment that your XML document satisfies the constraints of DocBook, point to the installation copy of the DTD:

<!DOCTYPE article
  PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
         "file:///c:/oasis/spec-0.8/docbook/docbookx.dtd"

or

<!DOCTYPE article
  PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
         "file:///Users/admin/z/oasis/spec-0.8/docbook/docbookx.dtd"

There are four HTML stylesheets in the package:

For each type of OASIS document (specification and note) there are two stylesheets you must choose from in order to create one of two versions of the rendering based on how that rendering will be used: online or offline.

The online stylesheets (without a suffix) are used to create final online versions to send to OASIS TC Administration (this will use embedded references to online CSS stylesheets and the online base URI in accordance with OASIS TC Administration requirements). Please review the results with TC Administration in case any rules or procedures have changed.

The offline stylesheets are used for creating artefacts that work self-contained within the publishing environment, without making any references to the OASIS web site. By default, these self-contained results will use absolute URI references to the CSS stylesheet and the OASIS logo, which work fine in the publishing environment but are not portable offline to other environments that do not support the absolute URI values.

To ensure portability across all environments, a top-level processing instruction is added to the specification that directs the creation of relative URI references to the CSS stylesheet and OASIS logo (and must be adjusted to accommodate the target deployment environment):

<?oasis-spec-base-uri htmlruntime/spec-0.8/?>

For an OASIS specification, use this stylesheet during development and local review to create a local instance (this will use the local base URI, either absolute or relative based on the presence of the processing instruction):

c:\oasis\spec-0.8\stylesheets\oasis-specification-html-offline.xsl

For an OASIS specification, use this stylesheet in the offline environment to create the final online version to send to OASIS TC Administration (this will use embedded references to online CSS stylesheets and the online base URI in accordance with OASIS TC Administration requirements):

c:\oasis\spec-0.8\stylesheets\oasis-specification-html.xsl

For an OASIS note, use this stylesheet during development and local review to create a local instance (this will use the local base URI, either absolute or relative based on the presence of the processing instruction):

c:\oasis\spec-0.8\stylesheets\oasis-note-html-offline.xsl

For an OASIS note, use this stylesheet in the offline environment to create the final online version:

c:\oasis\spec-0.8\stylesheets\oasis-note-html.xsl

In each case the resulting file should be suitable for viewing in a web browser.

There are four XSL-FO stylesheets for PDF creation in the package:

To convert a DocBook instance following the conventions used in this specification into an instance of XSL-FO assuming A4 page dimensions or US-letter page dimensions, use one of these stylesheets:

c:\oasis\spec-0.8\stylesheets\oasis-specification-fo-a4.xsl
c:\oasis\spec-0.8\stylesheets\oasis-specification-fo-us.xsl
c:\oasis\spec-0.8\stylesheets\oasis-note-fo-a4.xsl
c:\oasis\spec-0.8\stylesheets\oasis-note-fo-us.xsl

The resulting file should be suitable for an XSL-FO engine to render into a printed format such as a PDF file.

There are four typical invocation parameters with defaults:

An important objective of using XML markup when writing content is to separate what you are writing from how it is formatted and presented. Moreover, describing the individual components of your writing uniquely can allow machine processing of your content. Such machine processing can identify constructs and process them individually as required for the processed result.

The vocabulary of XML markup is the level of granularity used to identify constituent information items, and the collection of element and attribute labels applied to the granules.

Applying styling to documents is an example of machine processing. The processed result is a formatted representation of your document. When many authors use the same vocabulary, or a given author creates many documents with the same vocabulary, a single set of processes will produce consistently formatted results across the document set.

This process is analogous to using styles found in most desktop publishing applications, however by removing from the author the ability to inject arbitrary formatting of information items in their content, two benefits are realized: (a) the author no longer needs to think about formatting, only about appropriately labeling the information items in the content; and (b) authors cannot inadvertently format components of a document with incorrect or inconsistent results.

Many writers do, however, prefer the use of their favorite desktop publishing applications and OASIS has posted at https://docs.oasis-open.org/templates/ a number of templates for widely-adopted word processing programs to be used in the creation of OASIS specifications. Users must be diligent in the use of styles in order to ensure their work conforms to the presentation conventions requested of OASIS. There is an obligation incumbent on the writer to verify their work has not violated the requested conventions, and there are no automated tools with which to validate the constraints have been respected.

When creating OASIS specifications using XML the burden of formatting is placed on the stylesheets, not on the writer. The obligation of the writer is only to be conformant to the DocBook document model for which the included stylesheets have been designed, and there are automated validation tools with which the writer can validate the constraints have not been respected. The writer is also obligated to follow conventions that reflect the requirements of the OASIS TC Administration for specification documents, though these are not validated by the DocBook document models. The conventions are, however, reflected in a template included in this package.

Any resulting violations to the formatting conventions can usually be ascribed to the stylesheets and, when repaired, the authored content usually does not need to change (barring any need to distinguish in the XML an ambiguity that is then being distinguished in the stylesheets).

This environment and methodology is based on using the <article> document type of the DocBook 4.5 [DocBook] vocabulary for authoring the content in XML markup. These explanatory documents do not attempt to teach the DocBook vocabulary, as there are many online and printed references and manuals on the use of DocBook.

Note that there is a layer of additional constraints imposed on top of the DocBook metadata constructs in order to appropriately identify the constituent metadata components of the OASIS requirements for specifications. No validation constraints for this additional metadata layer are included in this environment, so it is the responsibility of the writer to visually confirm these needs have been satisfied in the rendered results. Missing components are typically the result of the writer not having correctly used the metadata indicators within the standard DocBook constructs.

The additional constraints are illustrated and documented in Section 3.5, “ Pro forma templates” and included with these materials.

It is possible to have body content that is specific to the OASIS rendering while not being applicable to another rendering of the XML. This is signaled using:

If a condition= attribute exists and the content does not include the case-sensitive five-character string “oasis”, then the content is not rendered using these stylesheets. An example of this is the content destined for the ISO ITTF rendering only, which has condition="isosts" and so is ignored by these stylesheets.

These OASIS specification stylesheets recognize the following additional facilities or interpretations when using the DocBook vocabulary:

This environment includes pro forma templates of a DocBook XML instance for each of a specification and a note. These have placeholders for all the OASIS specification metadata found in the word processing templates. Each XML template has one of every item of metadata and can be used as a guideline when creating the metadata for a new document. The prose of the document includes a detailed narrative of the declaration and use of each of the metadata components.

The template also includes some limited guidelines to the use of the DocBook vocabulary that have been carried over from previous versions of the documentation. With time it is hoped to embellish more in this section for the benefit of the reader.

The pro forma secification ptemplate is included as part of the package of this environment and if the document you are reading is part of a completely installed collection then it can be found at template/spec-docbook-template-0.8-wd05.xml and rendered at template/spec-docbook-template-0.8-wd05.html. Please see Appendix B, Sample specification template for an analysis of the XML document.

Likewise, the pro forma note template also is included and it can be found at template/note-docbook-template-0.8-wd05.xml and rendered at template/note-docbook-template-0.8-wd05.html.

An example of an OASIS Committee Specification that uses this DocBook XML environment is found at http://docs.oasis-open.org/ubl/os-UBL-2.2/.

An example of an OASIS Committee Note that uses this DocBook XML environment is found at http://docs.oasis-open.org/ubl/UBL-2.1-ASN.1/v1.0/cn01/.

In both examples the htmlruntime/ subdirectory is part of the document’s distribution, with the name of that directory changed to be db/.

In both examples the XML version of the document is the authoritative version of the document. At this time of writing, the “latest version” of the XML document is not supported on the OASIS server; navigate to the latest version of the HTML document and use the “this version” of the XML from that page.

Not included in the final published XML source of OASIS specifications are the stylesheet association [xml-assoc] processing instructions that are very handy conveniences to use during the authoring process. This methodology mandates their removal from the final published documents, but encourages their use when writing in order to streamline the writer’s review of the formatted content.

Stylesheet association is not widely employed in the general XML community, typically due to (a) limited awareness by writers of their benefit; and (b) limited conforming support in web browsers.

An XSLT stylesheet association processing instruction is structured with two pseudo attributes as follows, indicating the type of the stylesheet being engaged and the location of the stylesheet file producing the HTML rendition:

<?xml-stylesheet type="text/xsl" href="place-URL-here"?>

The benefits of having embedded a stylesheet association processing instruction at the top of one’s XML document are realized by opening the XML document being written in a web browser that (a) is aware of the processing instruction; (b) has a conforming XML processor with which to process the stylesheet files; and (c) has a conforming XSLT processor with which to engage the stylesheet files. The act of opening the XML document in the browser engages the HTML stylesheet against the XML content producing the HTML rendition on the browser canvas. At any time during the writing process, merely refreshing the web browser canvas re-engages the stylesheet producing the rendition of the revised content. This removes the necessity to engage the standalone invocation of the stylesheet environment to produce a reviewable rendition.

For example, this document was authored in an environment where the locally-installed offline version of the publishing environment is available in the local directory ../spec-0.8/, thus allowing the following stylesheet association processing instruction placed at the top of the XML file before the document type declaration to render the document in an XSLT-aware web browser:

<?xml-stylesheet type="text/xsl" href="file:///Users/admin/z/oasis/
spec-0.8/stylesheets/oasis-specification-html.xsl"?>

When a document is being authored in an environment where a copy of this publishing environment is embedded with the document directories, the following stylesheet association processing instruction would point to the embedded copy of the stylesheet fragment:

<?xml-stylesheet type="text/xsl" 
                 href="htmlruntime/spec-0.8/stylesheets/oasis-specification-html.xsl"?>

When a document is being authored in an environment where the remotely-installed online version of the publishing environment is to be used, the following stylesheet association processing instruction would work (modulo the latency aspects of accessing resources over the Internet):

<?xml-stylesheet type="text/xsl" href="http://docs.oasis-open.org/
templates/DocBook/spec-0.8/stylesheets/oasis-specification-html.xsl"?>

Many people believe that stylesheet association is a transient property of an XML document and should not be included in any “official” normative XML content. This methodology, therefore, mandates that any such processing instruction that might be used by the author during the writing phase be removed from the final published XML instance.

Included in the package is the Schematron file oasis-spec-note.sch with the set of writing rules for OASIS documents used by the UBL TC in the creation of the UBL hub document using the oXygenXML editing tool. Engaged while writing the document, these rules highlight problem areas that need to be addressed, while providing Schematron Quick Fixes for some of them to help automate the edits required.

Users can choose to use all of the rules refined by the UBL TC, or any of them can be commented out if they are considered inapplicable. Some of the rules are employed for consistency checks. Other rules enforce content structuring required by the OASIS Technical Advisory Board. Yet other rules promote quicker transformation to ISO format for ITTF publishing of International Standards.

At the time of writing these rules include: