`{Document Title}`

Working Draft 03, {date}

Document identifier:: wd-spectools-docbook-template-03 (XML, HTML, PDF)

Location:: http://www.oasis-open.org/spectools/docs

Editor:: {Jane} {Doe}, {Example Corporation} <{jane.doe@example.com}>

Author:: {John} {Able}, {Other Example Corporation}

Contributor:: {Mary} {Baker} <{mary.baker@example.com}>

Abstract:: {This specification defines...}

Status:

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

If you are on the <{xxx}@lists.oasis-open.org> list for committee members, send comments there. If you are not on that list, subscribe to the <{xxx}-comment@lists.oasis-open.org> list and send comments there. To subscribe, send an email message to <{xxx}-comment-request@lists.oasis-open.org> with the word "subscribe" as the body of the message.

{If a Committee Specification or OASIS Standard:} The errata page for this specification is at http://www.oasis-open.org/committees/{xxx}/{yyy}.

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
3.6. DocBook Metadata

1. Introduction

{Introduction}

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 the DocBook markup for OASIS specifications. It is important to use the markup provided in the template consistently and to avoid adding new elements or using raw formatting.}

{Delete this entire section when using this sample document to begin a new specification.}

3.1. Overall Style

The role of DocBook 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:

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, sgmltag, userinput.

3.6. DocBook Metadata

Within an article, the articleinfo element provides a wrapper for metadata. Each of the required metadata elements should be encoded as follows:

Title

In the title element.

Editorial Status

In the status attribute of the article (or book, etc.) element.

Publication Date

In the pubdate element.

Document Identifier

The document identifier is a combination of several elements. The base identifier (everything except the version) must be stored in the productname element.

The version number must be stored in the productnumber element.

Pointers to releases of the document in different formats must be encoded using ulink in releaseinfo elements with a role attribute of "product", as follows:

<releaseinfo role="product"><ulink url="url">Format</ulink></releaseinfo>

Location

In the releaseinfo element with a role attribute value of "location".

Editor(s), Author(s), and Contributor(s)

These individuals should be stored collectively in the authorgroup element. The editor, author, and othercredit elements must be used for editors, authors, and contributors, respectively.

Markup for an editor with an affiliation and an email address must be encoded this way:

<editor>
  <firstname>Jane</firstname><surname>Doe</surname>
  <affiliation>
    <orgname>Example Corporation</orgname>
    <address><email>jane.doe@example.com</email></address>
  </affiliation>
</editor>

The orgname can be omited if the individuals corporate affiliation is irrelevant. The address and email elements can also be omited if they are irrelevant. The author and othercredit elements are analagous.

Abstract

In the abstract element.

Status

In the legalnotice element with a role attribute value of "status".

Copyright

In the copyright element.

Notices

In an appendix. If a committee wishes to place some or all of the notices on the copyright page, they must be encoded in a legalnotice element.

A. Committee Members (Non-Normative)

The following individuals were members of the committee during the formulation of this document:

Mary Baker
Jane Doe, Example Corporation
John Able, Other Example Corporation

B. Notices

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.

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.

OASIS has been notified of intellectual property rights claimed in regard to some or all of the contents of this specification. For more information consult the online list of claimed rights.

C. Intellectual Property Rights

For information on wether 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/{technical-committee})

D. Revision History

Revision 03	15 Aug 2002	ndw
Changed copyright holder.
Revision 02	28 May 2002	ndw
Added IPR section.
Revision 01	26 Apr 2002	ndw
Reworked after conversations with Eve.
Revision 00	25 Apr 2002	ndw
First draft.

References

Normative

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

tm-pubsubj message