Transcript OASIS document rules - OASIS Mailing List Directory

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 http://www.oasis-open.org/spectools/ for the
approved OASIS templates and http://www.oasisopen.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.
• 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. 1997
– 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