Evergreen Documentation Style Guide (Draft .01)

This is the style guide for documentation produced for the Evergreen open-source library software project. This manual is intended to help everyone involved in the documentation "supply chain" by providing guidance wherever a decision about documentation formats needs to be made, from image size to file-naming conventions and the approved lists of tags and XSL stylesheets.

This is a living document in a fairly new endeavor, so your feedback on areas that need correction or expansion is encouraged and warmly appreciated.

In May, 2009, the Evergreen Documentation Interest Group committed to single-source, XML, using the DocBook 5.0 documentation standard, for all Evergreen-wide documentation, and committed to working as a group.

The rationales for this approach were as follows:

DocBook 5.0 is the authoring language for Evergreen documentation. DocBook 5.0 provides a structured XML-based grammar for writing complex technical documentation. It is also an OASIS standard. The remainder of this style guide discusses how Evergreen uses DocBook.

(Note: this primarily applies to documentation that is making its way into the Evergreen documentation XML toolchain for the first time. We have not yet developed a production model for revising XML documents.)

Documentation writers who author in XML generally fall into two camps: those who prefer a full-featured WYSIWYG editor with built-in validation tools, and those who prefer to code XML "by hand."

DIG is neutral on this issue, but can recommend software for those interested in authoring, editing, revising, updating, or validating XML files. Documentation editors higher up in the XML chain will ultimately reformat all XML so it has appropriate indenting and wrapping. If you are using an editor such as oXygen, most of this formatting is already done for you by the software. If you are coding XML by hand, you are encouraged but not required to keep lines under 80 characters long, and to avoid leaving white space between elements.

More crucially than indenting and white space, the DIG would appreciate it if authors producing XML would attempt to validate their files prior to submitting them to ensure the markup is valid and well-formed XML that conforms with DocBook 5. However, if you run against insoluble validation problems, please do not let that hold you up; just submit the files and we will fix the problems and advise you of what we found.

For more general references and familiarization with with DocBook, see the following:

There are two central books for Evergreen documentation, organized within a single set. The documentation files are arranged it hierarchically, beginning with docs, followed by the version:

http://evergreen-ils.org/docs/1.6 ...

The following is a common structural pattern for our documentation:

Most authors will be working at the chapter or section level. Chapters are created in separate files and imported into the book file using xinclude elements.

There are many more DocBook elements. The above is only intended to be illustrative of the "tree" that shapes Evergreen documentation. There are also exceptions to the "chapter" element, such as the glossary element.

The final chapter of this styleguide lists excluded tags for Evergreen documentation.

Evergreen documentation has the following high-level set, books, and chapters. Filenames are in parentheses:

XML based books share a number of common elements. These include:

The root element of an XML book is the book element. The book element provides a wrapper for parts, chapters, appendices, indexes, and glossaries.

The book element needs to include the XML namespace declarations shown in Example 4.1, “XML Namespace Declarations”:

<book xmlns="http://docbook.org/ns/docbook"
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:xl="http://www.w3.org/1999/xlink"
... >

The book element's version attribute must be set to 5.0.

You must also specify a value for the book element's xml:id attribute.

You can also use the book element's status attribute to embed a draft stamp in the book. You do this by setting status attribute to draft.

The first child of the book element is the title element. The contents of the title element is the title of the book.

The production templates fill in the required graphics and other formatting for the front matter of a book. However, the author needs to include the proper legal notices and copyright information. All of the legal notices should be imported from the template folder in the library. This way you do not have to worry about updating your books when the legal notices change.

The front matter also includes the following information:

All of the information in the front matter is boiler plate and should not be updated.

Example 4.2, “Front Matter Imported” shows a book file with the front matter imported.

<?xml version="1.0" encoding="UTF-8"?>
<book xmlns="http://docbook.org/ns/docbook"
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:xl="http://www.w3.org/1999/xlink"
version="5.0"
xml:id="overview">
<title>What is &prodname;?</title>
<info>
<xi:include href="../common/keywords.xml" />
<mediaobject>
  <imageobject role="html">
    <imagedata depth="100" contentwidth="146" contentdepth="55" 
               valign="middle" fileref="./imagesdb/cover_logo.gif"/>
  </imageobject>
</mediaobject>
<productname>&prodname;?</productname>
<releaseinfo>Version &version;?</releaseinfo>
<date>&reldate?</date>
<xi:include href="../common/legalblurb.xml" />
<xi:include href="../common/copynotice.xml" />
<xi:include href="../common/copydate.xml" />
<pubdate><?dbtimestamp format="d b Y"?></pubdate>
<corpauthor>Evergreen Documentation Interest Group</corpauthor>
</info>
...
</book>

The preface of your book is placed into the XML file just after the info element. It is specified inside of a preface element. The preface should be created in a separate file and imported, using an xinclude element, into the book file.

The preface of your book will have the following sections that are unique to a book:

In addition there are several sections that are common to all of the books in the library. These include:

These common sections should be imported, using xinclude elements, from a common template area. This ensures that any changes are propagated across the entire library.

Writing a preface is identical to writing a chapter. This is discussed in ????.

Example 4.3, “Book Preface” shows a preface that can be imported into a book file.

<?xml version="1.0" encoding="UTF-8"?>
<preface xmlns="http://docbook.org/ns/docbook"
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:xl="http://www.w3.org/1999/xlink"
version="5.0"
xml:id="inferno">
<title>Preface</title>
<section>
<title>What is Covered in This Book</title>
<para>A bunch of technical stuff.</para>
</section>
<section>
<title>Who Should Read This Book</title>
<para>Engineers interested in learning about the stuff discussed.</para>
</section>
<section>
<title>How to Use This Book</title>
<para>Very carefully...</para>
</section>
<xi:include href="../common/library.xml" />
<xi:include href="../common/latest.xml" />
<xi:include href="../common/searching.xml" />
<xi:include href="../common/resources.xml" />
<xi:include href="../common/coventions.xml" />
</preface>

After the preface, you add the chapters to your book. Chapters are created in separate files and imported into the book file using xinclude elements.

You do not need to worry about adding a table of contents, list of figures, or list of tables. These are all created when the book is published.

Adding content to a chapter is discussed in the ????

Chapters are imported into a book using xinclude elements.

The files for Evergreen documentation reside within a public directory on evergreen-ils.org.

Chapters are broken into sections and blocks.

Generally, a chapter should have five or fewer sections. If you need more sections, it may be because the topic for your chapter is too broad or you need to reconsider how you are chunking the information. Top level sections are denoted using section elements.

Top-level sections can be broken down into five or fewer subsections. Subsections are also denoted using section elements.

Block are the smallest structural unit of organization in a chapter. They divide up the information in a section into manageable chunks of information. There should be no more than five block-sections in a section.

Block-sections are denoted using simplesect elements. Blocks cannot be subdivided.

Example 6.2, “Detailed View of a Chapter” shows a more detailed view of a chapter.

<?xml version="1.0" encoding="UTF-8"?>
<chapter xmlns="http://docbook.org/ns/docbook"
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:xl="http://www.w3.org/1999/xlink"
version="5.0"
xml:id="chapter">
  <title>This is a Chapter</title>
  <info>
    <abstract>
      <para>This is a chapter summary.</para>
    </abstract>
  </info>
  <section id="section">
    <title>This is a section</title>
    ...
  </section>
  <section id="...">
    ...
    <section id="subsection">
      <title>Sample Subsection</title>
      ...
      <simplesect id="block">
        <title>Sample Block Section</title>
        ...
      </simplesect>
    </section>
  </section>
</chapter>

DocBook supports two methods for generating an index. One is to explicitly create the index. The other is to generate the index when the book is published based on elements included in the text. We use the second approach.

Authors are not required to mark up index elements; editors will complete any index tagging not accomplished at the authoring stage.

Index entries are specified by adding indexterm elements in the text of the book. An index entry must contain one primary element. The value of the primary element is the top-level entry that will appear in the generated index.

In addition, an indexterm element can contain the following optional elements:

If you want to mark an indexterm and you aren't sure what elements to assign it, use the primary element.

The Open Scalable Request Framework (, pronounced 'open surf'), is a stateful, decentralized service architecture that allows developers to create applications for Evergreen with a minimum of knowledge of its structure.

Indexed-field weighting, which controls relevance ranking in Evergreen, is configured in the 'weight' column of the table of the Evergreen database.

In order for the index to auto-generate, every Evergreen book has an <index/> element. The index will be generated in the position that corresponds to the element's location in the book file. The <index/> element follows all other chapters and appendices.

Simple lists are like a grocery list. They are a simple list of words or phrases without any delimiter. Their elements can only consist of simple, in-line tags, and therefore cannot contain sublists, examples, code listings or multiple paragraphs. Simple lists are rarely used in Evergreen' documentation.

A simple list is specified by a simplelist element. simplelist has two optional attributes:

The elements of a simple list are specified using a member element. The contents of each member element can only contain character data and in-line elements.

Example 1 shows the markup for a simple list.

<simplelist>
  <member>Swedish Fish</member>
  <member>Mike & Ike</member>
  <member>Sour Patch Kids</member>
  <member>Gummy Bears</member>
</simplelist>

An itemized list is used for lists where the order of the items in the list does not matter. They are like bulleted lists or the lists that are created by the ul tag in HTML.

An itemized list is specified by an itemizedlist element. You can specify an xml:id attribute for itemized lists. If the list is going to referenced by an xref element, you should also specify a value for the xreflabel attribute.

Each item in an itemized list is specified by a listitem element. The listitem element is a wrapper element and can contain any container elements such as a para element. All content within a listitem element will be indented to the same level. You can also specify sub-lists within a listitem element.

Example 2 shows the markup for an itemized list.

<itemizedlist>
  <listitem>
    <para>This is the first item in my list</para>
  </listitem>
  <listitem>
    <para>This is the second item in my list.</para>
    <para>It has two paragraphs.</para>
  </listitem>
  <listitem>
    <para>This item has a sublist.</para>
    <itemizedlist>
      <listitem><para>first</para></listitem>
      <listitem><para>second</para></listitem>
    </itemizedlist>
  </listitem>
</itemizedlist>

An ordered list is a list where the order of the elements is important and made explicit. They are like numbered lists and lists that are created using the ol tag in HTML.

Ordered lists are specified by an orderedlist element. In addition to the xml:id attribute and xreflabel attribute, orderedlist elements have three optional elements.

Items in an ordered list are specified using a listitem element. The listitem element is a wrapper element and can contain any container elements such as a para element. All content within a listitem element will be indented to the same level. You can also specify sub-lists within a listitem element.

A variable list looks similar to a glossary. It consists of a word, or phrase, and some text describing the word, or phrase. List of Rooms shows a variable list.

Variable lists are specified by a variablelist element. The variablelist element can have the optional xml:id attribute and xreflabel attribute specified. You can also supply a title for a variable list by adding a title element as the variablelist element's first child.

The items in a variable list are specified using a varlistentry element. The varlistentry element has two children elements that specify the contents of the item:

You can specify one or more term elements in a varlistentry element. Each term element can contain text and in-line markup elements. Each term element should contain a single term or phrase that the list item describes.

You describe the term, or terms, defined by the term elements using a single listitem element. The listitem element is a wrapper element and can contain any container elements such as a para element. All content within a listitem element will be indented to the same level. You can also specify sub-lists within a listitem element.

Example 9.3, “Variable List Markup” shows the markup representing List of Rooms.

<variablelist xml:id="varexample">
  <title>List of Rooms</title>
  <varlistentry>
    <term>Kitchen</term>
    <listitem>
      <para>The room where food is stored and prepared.</para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>Garage</term>
    <listitem>
      <para>Where the cars are parked.</para>
      <note>
        <para>Bikes are also here.</para>
      </note>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>Living room</term>
    <term>Family room</term>
    <listitem>
      <para>This is where we watch TV.</para>
    </listitem>
  </varlistentry>
</variablelist>

A glossary list is a special case of a variable list. It is used specifically for lists that define terms and where you may want to refer the reader back to the definition of a specific term. List of Terms shows a use of a glossary list.

A glossary list is specified using the glosslist element. If you want to refer back to a glossary list, you can provide values for the xml:id attribute and the xreflabel attribute. Like variable lists, glossary lists can have titles.

The entries in a glossary list are specified using a glossentry element. The glossentry element typically has two children: glossterm and glossdef. You can also use the glosssee element to xref with other definitions.

A glossentry element can have only one glossterm element. This element specifies the term being defined by this entry. If you are going to refer back to this term, you can supply a value for the parent glossentry element's xml:id attribute.

You define a term using either one or more glossdef elements or a glosssee element. The glossdef element is a content element that contains markup specifying a definition. If you use more than one glossdef element, they are treated as separate definitions for the same term.

The glosssee element redirects the reader to a term with the same meaning. It acts like a "See" entry in a dictionary. It has one attribute, otherterm, whose value is the id of the term to which the reader is redirected.

Example 4 shows the markup for List of Terms.

<glosslist xml:id="glossexample" xreflabel="List of terms";>
  <glossentry xml:id="consumerdef">
    <glossterm>consumer</glossterm>
    <glossdef>
      <para>The end user of a service, also called a 
         client for that service.</para>
    </glossdef>
  </glossentry>
  <glossentry xml:id="endptdef">
    <glossterm>endpoint</glossterm>
    <glossdef>
      <para>The point of contact that a 
         <glossterm linkend="servicedef">service</glossterm> 
        provides for its 
        <glossterm linkend="consumerdef">consumers</glossterm>.
    </para>
    </glossdef>
  </glossentry>
  <glossentry xml:id="servicedef">
    <glossterm>service</glossterm>
    <glossdef>
      <para>A collection of operations that perform a 
        useful set of functions in a network, access to 
        which is implemented as an
        <glossterm linkend="endptdef">endpoint</glossterm>.
        In a service-oriented network, services are defined          
        by a service contract.</para>
    </glossdef>
  </glossentry>
  <glossentry>
    <glossterm>service consumer</glossterm>
    <glosssee otherterm="consumerdef" />
  </glossentry>
</glosslist>

Warnings are used to call out instances where a serious loss of data could occur. The text of the warning should make it clear what will cause the data loss and what data is at risk. For example, if using a value greater than 1 million will cause a method invocation to return garbage, use a warning to mention this.

Warnings are marked up using a warning element. The warning element should contain a single para element that contains the text for the warning.

The warning element can, however, contain more than one paragraph, a code listing, or a table. These are exceptions that are to be used sparingly.

Notes are used to call out information that the reader should be aware of, but is ancillary to the topic being discussed in the main flow of the text.

Notes are marked up using a note element. Like the warning element, the note element should contain a single para element that contains the text for the warning. The note element can also contain more than one paragraph, a code listing, or a table.

Cautions are intended for use when a warning is too strong. For example, a caution may be used when an action will potentially cause a service to return an exception, but not crash or result in any loss of critical data. In general, it is best to use a warning.

Cautions are marked up using the caution element. As with warnings elements, the caution element should contain only a single para element.

Important notes are used to point out information that is important for the user to know, but that may not be obvious. For example, if you change a value in a context and the new value overrides a transport setting for the service. Or if the new value persists for all future uses of the context.

Important notes are marked up using the important element. The important element should contain only a single para element. However, it is allowable to use other block elements in an important note.

Tips are bits of information that may help a user be more productive, but that are not critical to using the product. In general, this type of information should either be worked directly into the text or placed in a note.

Tips are marked up using the tip element. The tip element should contain only a single para element. However, it is allowable to use other block elements in a tip.

Footnotes are not used in Evergreen documentation.

Internal cross-references link to targets within the same file or book. There are two linking elements that can be used to make an internal cross-reference:

The xref element creates a link to an element in the same file. It requires the use of the linkend attribute to identify the target element.

The xref element does not have any content. The link text is generated based on the contents of the target element. If the target element has a title element, such as a section element or an example element, the contents of the title element is used as the link text. Alternatively, the value of the target element's xreflabel attribute will be used as the link text.

Example 12.1, “Cross Reference to a Titled Element” shows an example of a cross reference whose text is derived from the title element of the referenced element. The resulting link text would be the section called "Coco Crisp" shows.

<para><xref linkend="topsect" /> shows ...</para>
...
<section id="topsect">
  <title>Coco Crisp</title>
...
</section>

Example 12.2, “Cross Reference to an Element with an xreflabel” shows an example of a cross reference whose text is derived from the xreflabel attribute of the targeted element. The resulting link text would be outfielder shows.

<para><xref linkend="example1" /> shows ...</para>
...
<example id="example1" xreflabel="outfielder">
  <title>Catching Coco Crisp</title>
  ...
</example>

Internal links are created using the link element. The link element has one required attribute, linkend, whose value is the id of element anchoring the link. The anchoring element can be any valid DocBook element that uses the xml:id attribute. For example if you wanted to create a link to an image in your document, you would use the id of the figure element that wraps the image.

The text used for the link is the content of the link element. Example 12.3, “Example of an Internal Link” shows the mark up for this link to the top of this section.

<section xml:id="link">
  ...
  <para>... this <link linkend="link">link to the top</link> of ...</para>
  ...
</section>

The olink element facilitates cross-linking among DocBook files (just as xref and link elements enable linking within files).

You create a link to another book using the olink element.

Two attributes associated with the olink element are used to specify the link target:

For simplicity's sake, use the document's xml:id attribute as the document identifier; it will then function as both the targetdoc and targetptr element. So the olink reference for this file would be filenames, as in this example:

See the chapter on <olink targetdoc="lists" targetpr="lists">creating lists</olink>

Authors can create cross-references to a different book in a set using the olink element. When linking to a different book, an author needs to use an additional attribute to specify the book in which the target element is located. The external linking mechanism relies on a site map and a number of target databases.

DocBook provides two methods for specifying link text for olink elements: author-supplied and auto-generated. Evergreen documentation uses author-supplied link text.

Creating an olink between books

adfasfsda

Stayton notes in DocBook XSL, "To form cross references between documents in HTML, their relative locations must be known." The olink site map defines how the published documentation set will be laid out and allows the publication system to resolve the links between all of the documents in the set.

The site map for a documentation set is placed at the root of the documentation source tree and is always called site.xml. Example 12.4, “Document Set Site Map” shows a sample site map.

<?xml version="1.0" encoding="utf-8"?> 
<targetset>
  <targetsetinfo>
    <title>Library Title</tite> 
    <desc>Site map for the Evergreen XML Style Guide</desc> 
  </targetsetinfo>
  <sitemap>
    <dir name="docs_rls_inferno">
      <dir name="fluff">
        <dir name="overview">
          <document targetdoc="InfernoOverview"> 
           <xi:include href="overview/target.db" xmlns:xi="http://www.w3.org/2001/XInclude" /> 
          </document>
        </dir>
      </dir>
      <dir name="install_guide">
        <document targetdoc="InfernoInstall">
        <xi:include href="install_guide/target.db" xmlns:xi="http://www.w3.org/2001/XInclude" />
        </document>
      </dir>
      <dir name="getting_started">
        <document targetdoc="InfernoGetStarted">
        <xi:include href="get_started/target.db" xmlns:xi="http://www.w3.org/2001/XInclude" />
        </document>
      </dir>
    </dir>
  </sitemap>
</targetset>

Links to Web pages are created using the link element. You identify the target Web site using the xl:href attribute. The value must be a valid URL.

The link text can be specified in one of two ways. You can specified the desired link text as the value of the link element. If you leave the link element empty, the value of the xl:href attribute will be used as the link text.

Example 12.5, “External Link with Link Text” shows an example of an external link with supplied link text.

<link xl:href="http://www.cxf.org">CXF Home</link>

Example 12.6, “External Link Using Default Link Text” shows an example of an external link that uses the default link text.

<link xl:href="http://www.cxf.org" />

Authors can create anchor points in your text using the anchor element. The anchor element does not have any content and does not result in any generated text. It simply marks a place in the content that can be the target of a link.

The anchor element is empty. It has a required xml:id attribute that is the ID used for linking to the anchor. In addition, it can take a xreflabel attribute that provides the generated text for an xref element or an empty olink element.

Example 12.7, “Creating an Anchor” shows the mark-up for placing an anchor in a document.

<section ...>
  ...
  <anchor xml:id="anchorID" xreflabel="here" />
  ...
  <para><xref linkend="anchorID" /> is a link to an anchor.</para>
  ...
</section>

The publication system adds page numbers to all cross-references in PDF books. For cross-references that use generated text, the publication makes choices about what text is appropriate for the cross-reference. In some cases the defaults used by the publication is not appropriate. In these cases, the author can modify the generated link text using the xrefstyle attribute.

The xrefstyle attribute's value is a string pattern. All of the patterns that can be used are described in Bob Stayton's DocBook XSL: The Complete Guide.

The pattern most commonly used in the Evergreen authoring system is the select pattern. This pattern is specified using the syntax shown in Example 12.8, “Syntax for the Select Pattern”.

<xref ... xrefstyle="select: opt1 opt2 ... optN" />

The values for optN select the text generated for the link text.

Authors can turn off the generation of page numbers in the PDF using the nopage option in the select pattern. This option instructs the link generation algorithm to not generate page numbers, however it does not provide any guidance about what to include in the generated text. For link elements and olink elements that provide a value for the link text, the nopage option produces a the supplied link text without a page number. For xref elements and olink elements that rely on the publication system to generate the link text, the nopage is insufficient to create a valid link. The author will need to provide either the label option to the pattern or the title option to the selection pattern.

Example 12.9, “Example of an Internal Link with no Page Number” shows a link element that would not generate a page number.

<section xml:id="link">
  ...
  <para>... this <link linkend="link" xrefstyle="select: nopage">link to the top</link> of ...</para>
  ...
</section>

Figures, tables, and examples have labels that are used to generate the link text. To ensure that an xref element or an olink element that relies on the publication system to generate the link text will produce link text when page numbering is turned off, the author needs to provide the label option to the selection pattern.

Example 12.10, “A Cross-Reference to a Figure with no Page Number” shows an xref element that generates a label without a page number.

<figure xml:id="link">
  ...
</figure>
<para><xref linkend="link" xrefstyle="select: nopage label" /> shows ...</para>
...

Chapters, sections, and blocks have titles that are used to generate the link text. To ensure that an xref element or an olink element that relies on the publication system to generate the link text will produce link text when page numbering is turned off, the author needs to provide the title option to the selection pattern.

Example 12.11, “A Cross-Reference to a Block with no Page Number” shows an xref element that generates a title without a page number.

<simplesect xml:id="link">
  ...
</simplesect>
...
<para>As discussed in <olink targetptr="link" xrefstyle="select: nopage label" /> ...</para>
...

There are many instances where you need to place a code artifact in a block of text such as when you are referring to a Java class or an XML element. DocBook has a number of specialized elements for placing code artifacts in-line. The ones commonly used include:

When placing XML artifacts such as element names or attribute names in your text wrap them in an tag element. To specify the type of XML artifact, the tag element's class attribute is always used. Table 15.2, “Values for the class Attribute” shows the values used for the class attribute.

To specify a Web address or URI you use the uri element.

To specify an E-Mail address use the email element.

DocBook defines a number of in-line tags for specifying programming artifacts. The commonly used tags are listed in Table 15.3, “Elements for In-Line Programming Artifacts”.

In addition to the elements listed in the section called “General programming language artifacts”, DocBook defines a number of elements that are used specifically for object-oriented programming artifacts. They are listed in Table 15.4, “Elements for In-Line OO Programming Artifacts”.