{Document Title}

This is a pro-forma XML instance of the DocBook [DocBook] vocabulary illustrating the components of an OASIS standards-related document. Remove the components that do not apply to your document, and replace the content placeholders with the content that you need to have published.

The key words must, must not, required, shall, shall not, should, should not, recommended, may, and optional in this document are to be interpreted as described in [RFC 2119].

This section is provided to explain and demonstrate only a small fraction of the DocBook markup that can be used for OASIS specifications. There are many publicly-available resources with which one can learn the DocBook vocabulary. It is important to use the markup provided in the template consistently and to avoid adding new elements or using raw formatting.

1234567890123456789012345678901234567890123456789012345678901234567890
         1         2         3         4         5         6
<simpleType name="DecisionType">
    <restriction base="string">
        <enumeration value="Permit"/>
        <enumeration value="Deny"/>
        <enumeration value="Indeterminate"/>
    </restriction>
</simpleType>

A small
code example

1234567890123456789012345678901234567890123456789012345678901234567890
         1         2         3         4         5         6
<simpleType name="DecisionType">
    <restriction base="string">
        <enumeration value="Permit"/>
        <enumeration value="Deny"/>
        <enumeration value="Indeterminate"/>
    </restriction>
</simpleType>

This section describes the instance structure and metadata of the DocBook XML instance of this document. The summarized markup copied from the instance is split into successive programlisting fragments interspersed with a narrative regarding how to use the markup in the fragment. Braces "{}" are used to indicate replaceable information and the braces should not be in the final document. There is no obligation to use the techniques used below, though what is below is successfully producing the result you are reading.

For the purposes of example in the code below, the locally-installed copy of the OASIS publishing environment is in the directory p:/oasis/spec-0.4/, and the locally-installed copy of the DocBook document model is p:/docbook/.

The XML Declaration uses ISO-8859-1 instead of UTF-8 as the content is being typed and remembering the two-byte codes of UTF-8 is sometimes awkward. Alternatively, using US-ASCII limits the typing entirely to 7-bit ASCII characters, requiring accented and other high-bit characters to be entered with entities.

<?xml version="1.0" encoding="ISO-8859-1"?>

The following XML Stylesheet Association [xml-assoc] processing instruction was present during the editing of the instance, but per the OASIS publishing guidelines [oasis-spec] this is not contained in the final version posted of the XML document. Using stylesheet association during the authoring process is a convenience for reviewing the rendered version of the authored XML markup when the XML document is open in a conforming browser supporting the association of XSLT stylesheets. After saving any edits to the XML document it is only necessary to refresh the browser to view the rendered results, without requiring any intervening XSLT process.

<?xml-stylesheet type="text/xsl" 
href="file://p:/oasis/spec-0.4/stylesheets/oasis-specification-html.xsl"?>

The following is an editing convenience keeping in an XML comment the PUBLIC and SYSTEM identifiers for the document type declaration for both the online publishing environment and the local publishing environment. Note how the actual identifiers in this snippet are for the local publishing environment while in the instance you will find the online publishing environment set being used in the document type declaration. When switching back and forth it is a convenience to have the three lines handy for copy/paste.

<!--   
For online publishing use:
<!DOCTYPE article
  PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" 

For offline publishing use:
<!DOCTYPE article
  PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
"file:///p:/docbook/docbookx.dtd" 
-->
<!DOCTYPE article
  PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
"file:///p:/docbook/docbookx.dtd" 

The internal declaration subset uses general entities in order to ensure consistent use of strings throughout the document. The &name; entity has the base name of the document. The &version; entity has the version of the document. The &standard; has the document status which is used in meta data and is often referenced in the prose along the lines of "This &standard; includes the ...".

[
<!--the document properties-->
<!ENTITY name "wd-spectools-docbook-template">
<!ENTITY version "0.4">
<!ENTITY standard "Working Draft">
]>

The document element for OASIS standards is always article. The status must be one of "Working Draft", "Editor's Draft", "Committee Draft", "Committee Specification" or "Standard" to have the HTML rendition of the document pointing to the appropriate CSS stylesheet:

<article status="&standard;">

The metadata is kept in the DocBook articleinfo element, starting with the name and version of the document. The publishing scripts will use the these information items in the synthesis of filenames. Note the use of the entity references for consistency.

<articleinfo>
<productname>&name;</productname>
<productnumber>&version;</productnumber>

The links to the various instantiations of the document and supporting materials are summarized using releaseinfo role="product" for as many files as you have. Note again the use of the entity references for consistency. These links are not included in the printed rendering.

<releaseinfo role="product">
  <ulink url="&name;-&version;.xml">XML</ulink>
</releaseinfo>
<releaseinfo role="product">
 <ulink url="&name;-&version;.html">HTML</ulink>
</releaseinfo>
<releaseinfo role="product">
 <ulink url="&name;-&version;.pdf">PDF (A4)</ulink>
</releaseinfo>
<releaseinfo role="product">
 <ulink url="&name;-&version;-us.pdf">PDF (US)</ulink>
</releaseinfo>
<releaseinfo role="product">
 <ulink url="&name;-&version;.zip">ZIP</ulink>
</releaseinfo>
<releaseinfo role="product"> 
<ulink url="&name;-&version;.tar.gz">TAR/GZ</ulink>
</releaseinfo>

When you have an OASIS document number, use a role of "oasis-id".

<releaseinfo role="oasis-id">{OASIS Document Number}</releaseinfo>

There may be a number of different versions of the document. The guidelines provide for a persistent, a current and any number of previous versions. Note that the use of the role= attribute is generic for these information items, in that the text prompt is constructed from the portion of the attribute string following the first hyphen. The first character is capitalized and any underscores are replaced with spaces. While not totally general purpose this should meet most unanticipated requirements for the titling of versions. It does, however, constrain the author to spell the attributes correctly to have them presented correctly in the renderings.

<releaseinfo role="location-persistent_version">
  {persistent location}
</releaseinfo>
<releaseinfo role="location-current_version">
  {current location}
</releaseinfo>
<releaseinfo role="location-previous_version">
  {previous location}
</releaseinfo>

The committee is indicated using role="committee".

<releaseinfo role="committee">
  OASIS {official name of technical committee} TC
</releaseinfo>

Any subject and keyword information is indicated using role="subject-keywords".

<releaseinfo role="subject-keywords">
  {comma-separated keyword listing}
</releaseinfo>

The topic information is indicated using role="topic".

<releaseinfo role="topic">{topic area}</releaseinfo>

The document title is indicated in the title element:

<title>{Document Title}</title>

The various people sited in the document are in the authorgroup element, using editor and author for their respective players, and the othercredit element for the committee chairs.

<authorgroup>
<editor>
  <firstname>{Jane}</firstname><surname>{Doe}</surname>
  ...
</editor>
<author>
  <firstname>{John}</firstname><surname>{Able}</surname>
  ...
</author>
<othercredit>
  <firstname>{Mary}</firstname><surname>{Baker}</surname>
  ...
</othercredit>
<othercredit>
  <firstname>{James}</firstname><surname>{Butcher}</surname>
  ...
</othercredit>
</authorgroup>

The publishing date is constrained by OASIS conventions to the following format:

<pubdate>DD Month YYYY</pubdate>

The copyright information is embedded using the copyright element, but note that this information has to be entered as well in the text of the notices.

<copyright>
  <year>YYYY</year>
  <holder>OASIS Open, Inc. All Rights Reserved.</holder>
</copyright>

When you want to relate this document to other works use legalnotice with role="related".

<legalnotice role="related"><title>Related Work</title>
  <para>This specification replaces or supersedes:</para>
   ...
</legalnotice>

The abstract has its own DocBook element.

<abstract>
  <para>{This specification defines...}</para>
</abstract>

For the status use legalnotice with role="status".

<legalnotice role="status"><title>Status</title>
  <para>{Describe the status and stability ...}</para>
  ...
</legalnotice>

For the notices use legalnotice with role="notices" ensuring you use the appropriate version of the legal notices from the markup in this instance.

<legalnotice role="notices"><title>Notices</title>
  <para>Copyright © OASIS Open 20??. All Rights Reserved.</para>
  ...
</legalnotice>

Thus ends the document metadata. The sections and annexes follow.

</articleinfo>
<section id="s.introduction">
...
<appendix>
...