{Document Title}

Working Draft 0.4, 08 February 2006

Document identifier:
wd-spectools-docbook-template-0.4 (XML, HTML, PDF (A4), PDF (US), ZIP, TAR/GZ)
OASIS identifier:
{OASIS Document Number}
Locations:
Persistent version: http://docs.oasis-open.org/templates/
Current version: http://docs.oasis-open.org/templates/DocBook/spec-0.4/template/wd-spectools-docbook-template-0.4.html
Previous version: http://www.oasis-open.org/spectools/docs/wd-spectools-docbook-template-03.html
Technical committee:
OASIS {official name of technical committee} TC
Chairs:
{Mary} {Baker} 
{James} {Butcher} 
Editor:
{Jane} {Doe}, {Example Corporation} 
Author:
{John} {Able}, {Other Example Corporation}
Subject / Keywords:
{comma-separated keyword listing}
OASIS Conceptual Model Topic Area:
{topic area}
Abstract:

{This specification defines...}

Related Work:

This specification replaces or supersedes:

  • {specification replaced by this standard}

  • {specification replaced by this standard}

This specification is related to:

  • {related specifications}

  • {related specifications}

Status:

{Describe the status and stability of the specification here.}

This document was last revised or approved by the {TC name | membership of OASIS} on the above date. The level of approval is also listed above. Check the current location noted above for possible later revisions of this document. This document is updated periodically on no particular schedule.

Technical Committee members should send comments on this specification to the Technical Committee's email list. Others should send comments to the Technical Committee by using the "Send A Comment" button on the Technical Committee's web page at http://www.oasis-open.org/committees/{short name}.

For information on whether any patents have been disclosed that may be essential to implementing this specification, and any offers of patent licensing terms, please refer to the Intellectual Property Rights section of the Technical Committee web page (http://www.oasis-open.org/committees/{TC short name}ipr.php).

The non-normative errata page for this specification is located at http://www.oasis-open.org/committees/{TC short name}.

Notices:

For committees formed after April 15, 2005 and those other committees that have transitioned to the new IPR policy, the notices required for OASIS documents can be found at http://www.oasis-open.org/who/intellectualproperty.php#notices and, as of the time of writing this document read as follows (square-bracketed language need only appear in specification documents) though it is block quoted solely for explanatory reasons and would not be so quoted when used:

Copyright © OASIS Open 20??. All Rights Reserved.

All capitalized terms in the following text have the meanings assigned to them in the OASIS Intellectual Property Rights Policy (the "OASIS IPR Policy"). The full Policy may be found at the OASIS website.

This document and translations of it may be copied and furnished to others, and derivative works that comment on or otherwise explain it or assist in its implementation may be prepared, copied, published, and distributed, in whole or in part, without restriction of any kind, provided that the above copyright notice and this section are included on all such copies and derivative works. However, this document itself may not be modified in any way, including by removing the copyright notice or references to OASIS, except as needed for the purpose of developing any document or deliverable produced by an OASIS Technical Committee (in which case the rules applicable to copyrights, as set forth in the OASIS IPR Policy, must be followed) or as required to translate it into languages other than English.

The limited permissions granted above are perpetual and will not be revoked by OASIS or its successors or assigns.

This document and the information contained herein is provided on an "AS IS" basis and OASIS DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY OWNERSHIP RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.

[OASIS requests that any OASIS Party or any other party that believes it has patent claims that would necessarily be infringed by implementations of this OASIS Committee Specification or OASIS Standard, to notify OASIS TC Administrator and provide an indication of its willingness to grant patent licenses to such patent claims in a manner consistent with the IPR Mode of the OASIS Technical Committee that produced this specification.]

[OASIS invites any party to contact the OASIS TC Administrator if it is aware of a claim of ownership of any patent claims that would necessarily be infringed by implementations of this specification by a patent holder that is not willing to provide a license to such patent claims in a manner consistent with the IPR Mode of the OASIS Technical Committee that produced this specification. OASIS may include such claims on its website, but disclaims any obligation to do so.]

[OASIS takes no position regarding the validity or scope of any intellectual property or other rights that might be claimed to pertain to the implementation or use of the technology described in this document or the extent to which any license under such rights might or might not be available; neither does it represent that it has made any effort to identify any such rights. Information on OASIS' procedures with respect to rights in any document or deliverable produced by an OASIS Technical Committee can be found on the OASIS website. Copies of claims of rights made available for publication and any assurances of licenses to be made available, or the result of an attempt made to obtain a general license or permission for the use of such proprietary rights by implementers or users of this OASIS Committee Specification or OASIS Standard, can be obtained from the OASIS TC Administrator. OASIS makes no representation that any information or list of intellectual property rights will at any time be complete, or that any claims in such list are, in fact, Essential Claims.]

For those committees that have not transitioned to the new IPR policy, the notices read as follows:

OASIS takes no position regarding the validity or scope of any intellectual property or other rights that might be claimed to pertain to the implementation or use of the technology described in this document or the extent to which any license under such rights might or might not be available; neither does it represent that it has made any effort to identify any such rights. Information on OASIS's procedures with respect to rights in OASIS specifications can be found at the OASIS website. Copies of claims of rights made available for publication and any assurances of licenses to be made available, or the result of an attempt made to obtain a general license or permission for the use of such proprietary rights by implementors or users of this specification, can be obtained from the OASIS Executive Director.

OASIS invites any interested party to bring to its attention any copyrights, patents or patent applications, or other proprietary rights which may cover technology that may be required to implement this specification. Please address the information to the OASIS Executive Director.

Copyright © OASIS Open 20??. All Rights Reserved.

This document and translations of it may be copied and furnished to others, and derivative works that comment on or otherwise explain it or assist in its implementation may be prepared, copied, published and distributed, in whole or in part, without restriction of any kind, provided that the above copyright notice and this paragraph are included on all such copies and derivative works. However, this document itself may not be modified in any way, such as by removing the copyright notice or references to OASIS, except as needed for the purpose of developing OASIS specifications, in which case the procedures for copyrights defined in the OASIS Intellectual Property Rights document must be followed, or as required to translate it into languages other than English.

The limited permissions granted above are perpetual and will not be revoked by OASIS or its successors or assigns.

This document and the information contained herein is provided on an "AS IS" basis and OASIS DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.


Table of Contents

1. Introduction
2. Terminology
3. DocBook Markup
3.1. Overall Style
3.2. Sections
3.3. Lists
3.4. Code Examples
3.5. Inline Elements
4. DocBook instance and metadata

Appendixes

A. Normative Annex Example
B. Acknowledgments (Non-Normative)
C. Revision History (Non-Normative)
References

1. Introduction

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.

2. Terminology

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].

3. DocBook Markup

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.

3.1. Overall Style

The role of DocBook, as with many XML vocabularies, is to identify the semantic elements of your document; to say what things are, not how they should be formatted.

When DocBook is transformed to HTML for rendering, CSS is used to provide most of the visual styling information. For transformation to print, the styling is controlled more closely by the XSLT stylesheet.

OASIS specifications are DocBook articles. Each article must have introductory metadata and may contain any number of section elements followed optionally by appendix, glossary, bibliography, and index elements.

3.2. Sections

A specification can be divided into sections with the section element. Sections are recursive. Section numbering is provided by the stylesheet, authors should not insert section numbers manually.

3.3. Lists

DocBook provides several list styles:

  • orderedlist, for numbered lists.

  • itemizedlist, for bulleted lists.

  • variablelist, for definition lists.

  • simplelist, for inline and simple, tabular lists.

  • glosslist, for glossary terms outside of the glossary.

3.4. Code Examples

For schema and other code examples, use the programlisting element, being careful to start the verbatim text on the same line as the start tag in order to prevent a gap at the top of the 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>

For small, non-normative code fragments, screen is appropriate:

A small
code example

To format code examples so that they will be highlighted more distinctly in the presentation, use informalexample:

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

Alternatively, to create formal figures or examples, with numbers and titles, use figure or example, respectively.

3.5. Inline Elements

DocBook provides a whole host of inline elements, many of which may be appropriate for your specification. Consider, in particular, computeroutput, emphasis, literal, markup, phrase, quote, replaceable, sgmltag, userinput.

4. DocBook instance and metadata

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>
...

A. Normative Annex Example

A normative annex does not have any role= attribute, whereas a non-normative annex has a role="non-normative" attribute:

<appendix>
<title>Normative Annex Example</title>
<para>A normative annex does not ...
</appendix>

<appendix id="a.committee" role="non-normative">
<title>Acknowledgments</title>

B. Acknowledgments (Non-Normative)

The following individuals have participated in the creation of this specification and are gratefully acknowledged (note that the itemized list uses spacing="compact" to remove the space between list items in the printed result):

  • Mary Baker

  • Jane Doe, Example Corporation

  • John Able, Other Example Corporation

C. Revision History (Non-Normative)

[optional; should not be included in OASIS standards]

Revision 0.403 Feb 2006gkh
New IPR and use of revised 0.4 specification publishing environment; mimic latest Word and Open Office templates
Revision 0315 Aug 2002ndw
Changed copyright holder.
Revision 0228 May 2002ndw
Added IPR section.
Revision 0126 Apr 2002ndw
Reworked after conversations with Eve.
Revision 0025 Apr 2002ndw
First draft.

References

Normative

[DocBook] Norm Walsh DocBook XML, The DocBook 4.4 Document type. OASIS January 27, 2005

[RFC 2119] S. Bradner. RFC 2119: Key words for use in RFCs to Indicate Requirement Levels. IETF (Internet Engineering Task Force). 1997.

Non-normative

[xml-assoc] James Clark Associating Style Sheets with XML documents Version 1.0. W3C Recommendation 29 June 1999.

[oasis-spec] G. Ken Holman OASIS Specification Publishing in DocBook XML. February 2006.