OASIS document rules Nigel Shaw Eurostep Limited

From Oasis web site: TC Guidelines TC documents should be maintained using appropriate methods of version control, and must use OASIS-suggested style guides and templates; see for the approved OASIS templates and open.org/spectools/docs/chairs-filenaming-02.html for the preliminary document file naming scheme. Versions of the templates are available in HTML, XML, Open Office, and MSWord; the TC may select which version to use. open.org/spectools/docs/chairs-filenaming-02.html Committee Drafts submitted to the OASIS membership for consideration as an OASIS Standard must use the OASIS-approved templates; this is the only point at which OASIS will check for use of the templates by the TCs. While the use of the OASIS templates before this submission is optional it is highly recommended so that the TC does not need to do major formatting work of the document before submission. Regardless of whether the TC uses the OASIS template during the draft stage, the OASIS copyright statement (see the OASIS IPR Policy) must be included in the document.

Document processing possibilities Use DEXlib to generate XML according to DOCBook and then generate html and PDF as done for (some) other OASIS standards –High effort and learning curve –No risk of not conforming Use DEXlib to generate xhtml and then apply OASIS CSS stylesheets –Already generate XHTML but would have to amend current output –Lower effort and little learning –Risk of not conforming is higher Seek advice from OASIS staff

Document naming Have to conform to OASIS rules Need to define strategy –One standard (number) per DEX –One standard (number) for PLCS In theory contributions should follow the naming conventions –DEXlib makes this close to impossible

OASIS Document spec’s Specification Template Instructions (in XML, HTML, and PDF) This document explains how to use the available templates and tools to create OASIS publications. It covers the proposed convention for file naming and other rules for how to fill in document metadata. DocBook Template (in XML, HTML, and PDF) The XML file is the actual template to use. The HTML and PDF files show the results of using the stylesheets found in the stylesheet repository. Word Sample (in.doc)The Word file was prepared in Microsoft Word 2002; it is the actual file to start with in editing a new document, along with the Word template below. The PDF file is a non-revisable version of the sample for viewing. Word Template (in.dot)This Word template does not use revision numbers in the file name, so that it is easy for you to update your templates directory with new versions and have them apply to your existing documents. OpenOffice.org sample document (in.sxw and.pdf) This OpenOffice.org file was prepared in OpenOffice V1.1 and should work for both V1.1 and V1.0. It is the actual file to start with in editing a new document, along with the OpenOffice.org template below. The PDF file is a non-revisable version of the sample for viewing. OpenOffice.org template (in.stw) This OpenOffice.org template does not use revision numbers in the file name, so that it is easy for you to update your templates directory with new versions and have them apply to your existing documents. If you've got an existing document to which you want to apply the styles in this template, first import the template using File>Templates>Organize>Commands>Import Template, and then with your document open, select Format->Styles->Load. To create a new document from the template without using the sample document, select File>New>Templates and Documents. XSLT stylesheet for use with OpenOffice.org documents (in.xsl) This stylesheet allows for the extraction of all OpenOffice.org text that uses a certain paragraph style; the particular style is customizable, but the default is "Code".

Observations Of the various approved OASIS standards, most are given as PDF unless in processible format Such as.xsd –But not all ! Three years ago OASIS realised the problem that there was not enough consistency across their published standards –However seems to have been pursued by very small number of involved people working on one set of standards Emphasis on content and on presentation style Not complete Traditional document viewpoint (cf. DEXlib) –Only late stage enforcement in place Except IPR statements

Observations 2 OASIS less concerned than ISO to differentiate normative and informative elements in text –If follow this lead, it could make use of OASIS documents difficult in contracts –Suggest follow ISO (and W3C) lead in making distinction and separation mandatory Editor and DEXlib controlled? OASIS suggests use of a keywords approach that is different from ISO –[RFC 2119] IETF (Internet Engineering Task Force). RFC 2119: Key words for use in RFCs to Indicate Requirement Levels. S. Bradner. 1997RFC 2119: Key words for use in RFCs to Indicate Requirement Levels –Allows “must” where ISO says “shall” Small risk of clash in content when importing from STEPmod into DEXlib

Observations 3 Documents carry version identifiers and revision history –In contrast to ISO process Documentation form relies on references to the TC web site pages under OASIS –IPR This probably could/should acknowledge PLCS, Inc. –Errata TC Need to address this – create relevant pages