{Document Title}

&name; &version; XML HTML PDF (A4) PDF (US) ZIP TAR/GZ {OASIS Document Number} http://docs.oasis-open.org/templates/ http://docs.oasis-open.org/templates/DocBook/spec-&version;/template/&name;-&version;.html http://www.oasis-open.org/spectools/docs/wd-spectools-docbook-template-03.html OASIS {official name of technical committee} TC {comma-separated keyword listing} {topic area} {Document Title} {Jane}{Doe} {Example Corporation}

{jane.doe@example.com}

{John}{Able} {Other Example Corporation} {Mary}{Baker}

{mary.baker@example.com}

{James}{Butcher}

{james.butcher@example.com}

08 February 2006 2006 OASIS Open, Inc. All Rights Reserved. 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} {This specification defines...} 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.

Introduction This is a pro-forma XML instance of the 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.

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 .

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.

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.

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.

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.

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 ]]> 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 ]]> Alternatively, to create formal figures or examples, with numbers and titles, use figure or example, respectively.

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 .

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. ]]> The following XML Stylesheet Association processing instruction was present during the editing of the instance, but per the OASIS publishing guidelines 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. ]]> 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. 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 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: ]]> 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. &name; &version; ]]> 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. XML HTML PDF (A4) PDF (US) ZIP TAR/GZ ]]> When you have an OASIS document number, use a role of "oasis-id". {OASIS Document Number} ]]> 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. {persistent location} {current location} {previous location} ]]> The committee is indicated using role="committee". OASIS {official name of technical committee} TC ]]> Any subject and keyword information is indicated using role="subject-keywords". {comma-separated keyword listing} ]]> The topic information is indicated using role="topic". {topic area} ]]> The document title is indicated in the title element: {Document 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. {Jane}{Doe} ... {John}{Able} ... {Mary}{Baker} ... {James}{Butcher} ... ]]> The publishing date is constrained by OASIS conventions to the following format: DD Month YYYY ]]> 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. YYYY OASIS Open, Inc. All Rights Reserved. ]]> When you want to relate this document to other works use legalnotice with role="related". Related Work This specification replaces or supersedes: ... ]]> The abstract has its own DocBook element. {This specification defines...} ]]> For the status use legalnotice with role="status". Status {Describe the status and stability ...} ... ]]> For the notices use legalnotice with role="notices" ensuring you use the appropriate version of the legal notices from the markup in this instance. Notices Copyright © OASIS Open 20??. All Rights Reserved. ... ]]> Thus ends the document metadata. The sections and annexes follow.

... ... ]]>

Normative Annex Example A normative annex does not have any role= attribute, whereas a non-normative annex has a role="non-normative" attribute: Normative Annex Example A normative annex does not ... Acknowledgments ]]> Acknowledgments 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 Revision History [optional; should not be included in OASIS standards] 0.4 03 Feb 2006 gkh New IPR and use of revised 0.4 specification publishing environment; mimic latest Word and Open Office templates 03 15 Aug 2002 ndw Changed copyright holder. 02 28 May 2002 ndw Added IPR section. 01 26 Apr 2002 ndw Reworked after conversations with Eve. 00 25 Apr 2002 ndw First draft. References Normative DocBookNorm Walsh DocBook XML, The DocBook 4.4 Document type. OASIS January 27, 2005 RFC 2119S. Bradner. RFC 2119: Key words for use in RFCs to Indicate Requirement Levels. IETF (Internet Engineering Task Force). 1997. Non-normative xml-assocJames Clark Associating Style Sheets with XML documents Version 1.0. W3C Recommendation 29 June 1999. oasis-specG. Ken Holman OASIS Specification Publishing in DocBook XML. February 2006.