[open-ils-commits] r14000 - trunk/docs/1.6 (kgs)
svn at svn.open-ils.org
svn at svn.open-ils.org
Wed Sep 9 16:31:25 EDT 2009
Author: kgs
Date: 2009-09-09 16:31:19 -0400 (Wed, 09 Sep 2009)
New Revision: 14000
Added:
trunk/docs/1.6/admon.xml
trunk/docs/1.6/authoring.xml
trunk/docs/1.6/books.xml
trunk/docs/1.6/build.xml
trunk/docs/1.6/chapter.xml
trunk/docs/1.6/conditional.xml
trunk/docs/1.6/exclude.xml
trunk/docs/1.6/figures.xml
trunk/docs/1.6/filenames.xml
trunk/docs/1.6/general.xml
trunk/docs/1.6/glossary.xml
trunk/docs/1.6/indexterms.xml
trunk/docs/1.6/links.xml
trunk/docs/1.6/lists.xml
trunk/docs/1.6/overview.xml
trunk/docs/1.6/programming.xml
trunk/docs/1.6/structure.xml
trunk/docs/1.6/styleguide.xml
trunk/docs/1.6/tables.xml
Log:
Moving styleguide folder into 1.6 docs repository.
Added: trunk/docs/1.6/admon.xml
===================================================================
--- trunk/docs/1.6/admon.xml (rev 0)
+++ trunk/docs/1.6/admon.xml 2009-09-09 20:31:19 UTC (rev 14000)
@@ -0,0 +1,104 @@
+<?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="admonitions">
+ <title>Admonitions</title>
+ <section>
+ <title>Overview</title>
+ <para>Admonitions are pieces of text that are offset from the main flow of text. They include
+ things like warnings, notes, and tips. They should be used sparingly because they interrupt
+ the flow of the text. However, if you think one is needed, use one.</para>
+ <para>As a general rule, warnings and notes are the <emphasis role="bold">preferred</emphasis>
+ admonitions in Evergreen' documentation. That does not mean the use of the other types are
+ prohibited. It only means that they should be used with caution.</para>
+ </section>
+ <section xml:id="warn">
+ <title>Warnings</title>
+ <simplesect>
+ <title>Overview</title>
+ <para>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.</para>
+ </simplesect>
+ <simplesect>
+ <title>Markup</title>
+ <para>Warnings are marked up using a <tag class="element">warning</tag> element. The <tag
+ class="element">warning</tag> element should contain a single <tag class="element"
+ >para</tag> element that contains the text for the warning.</para>
+ <para>The <tag class="element">warning</tag> element can, however, contain more than one
+ paragraph, a code listing, or a table. These are exceptions that are to be used
+ sparingly.</para>
+ </simplesect>
+ </section>
+ <section xml:id="note">
+ <title>Notes</title>
+ <simplesect>
+ <title>Overview</title>
+ <para>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.</para>
+ </simplesect>
+ <simplesect>
+ <title>Markup</title>
+ <para>Notes are marked up using a <tag class="element">note</tag> element. Like the <tag
+ class="element">warning</tag> element, the <tag class="element">note</tag> element should
+ contain a single <tag class="element">para</tag> element that contains the text for the
+ warning. The <tag class="element">note</tag> element can also contain more than one
+ paragraph, a code listing, or a table.</para>
+ </simplesect>
+ </section>
+ <section xml:id="caution">
+ <title>Cautions</title>
+ <simplesect>
+ <title>Overview</title>
+ <para>Cautions are intended for use when a <link linkend="warn">warning</link> 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 <link linkend="warn">warning</link>.</para>
+ </simplesect>
+ <simplesect>
+ <title>Markup</title>
+ <para>Cautions are marked up using the <tag class="element">caution</tag> element. As with
+ warnings elements, the <tag class="element">caution</tag> element should contain only a
+ single <tag class="element">para</tag> element.</para>
+ </simplesect>
+ </section>
+ <section xml:id="important">
+ <title>Important Notes</title>
+ <simplesect>
+ <title>Overview</title>
+ <para>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.</para>
+ </simplesect>
+ <simplesect>
+ <title>Markup</title>
+ <para>Important notes are marked up using the <tag class="element">important</tag> element.
+ The <tag class="element">important</tag> element should contain only a single <tag
+ class="element">para</tag> element. However, it is allowable to use other block elements
+ in an important note.</para>
+ </simplesect>
+ </section>
+ <section xml:id="tip">
+ <title>Tips</title>
+ <simplesect>
+ <title>Overview</title>
+ <para>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 <link linkend="note">note</link>.</para>
+ </simplesect>
+ <simplesect>
+ <title>Markup</title>
+ <para>Tips are marked up using the <tag class="element">tip</tag> element. The <tag
+ class="element">tip</tag> element should contain only a single <tag class="element"
+ >para</tag> element. However, it is allowable to use other block elements in a tip.</para>
+ </simplesect>
+ </section>
+ <section>
+ <title>Footnotes</title>
+ <simplesect>
+ <title>Overview</title>
+ <para>Footnotes are not used in Evergreen documentation. </para>
+ </simplesect>
+ </section>
+</chapter>
Added: trunk/docs/1.6/authoring.xml
===================================================================
--- trunk/docs/1.6/authoring.xml (rev 0)
+++ trunk/docs/1.6/authoring.xml 2009-09-09 20:31:19 UTC (rev 14000)
@@ -0,0 +1,93 @@
+<?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="authoring">
+ <title>Authoring Documentation</title>
+ <info>
+ <abstract>
+ <para>DocBook ....</para>
+ </abstract>
+ </info>
+ <section>
+ <title>Structure: Concept, Task, Reference</title>
+ <para> Every chapter in Evergreen documentation, and in some cases sections, should begin by
+ explaining this chapter's concepts, or core ideas, to the reader. This gives you the
+ opportunity to clarify new or ambiguous terminology for otherwise experienced readers:
+ for example, in a circulation overview you will want to differentiate non-cataloged
+ items vs. pre-cataloged items. Explaining concepts also gives less experienced readers a
+ chance to fill in gaps in their knowledge. </para>
+ <para> For example, in the circulation section of the manual, you may write the following
+ set of tasks: </para>
+ <itemizedlist>
+ <listitem>
+ <para>Checking out an item Checking in an item Renewing items Recording in-house
+ uses</para>
+ </listitem>
+ </itemizedlist>
+ <para> Separating the concepts from the tasks gives your readers the chance to jump directly
+ to the task they want to complete, if they are already familiar with the concepts. </para>
+ <para> When you write your task information, try to organize it as a set of numbered steps
+ that covers the most common cases. Compose each step in two sentences: first, describe
+ the action the reader must complete, followed by a sentence describing the results of
+ successfully performing the action if applicable. Preface optional steps with
+ (Optional):. For example: </para>
+ <para> To check out a cataloged item to a patron: </para>
+ <orderedlist>
+ <listitem>
+ <para>In the staff client, select Circulation→Check Out Items. The Check Out tab
+ appears.</para>
+ </listitem>
+ <listitem>
+ <para>Enter the patron barcode in the Barcode text field. The system retrieves and
+ displays the patron information, with the Check Out button highlighted in the
+ action bar.</para>
+ </listitem>
+ <listitem>
+ <para>Enter the item barcode in the text field beside the Barcode: selection in the
+ drop-down menu.</para>
+ </listitem>
+ </orderedlist>
+ <!-- the following was copied from the wiki and has not been marked up yet. It is wrapped
+ with para elements so that it will not trigger the XML validator -->
+
+ <para>(Optional): Select a different due date from the date selector. 4. Click Submit to
+ check out the item to the patron. The item barcode, due date, and title appear in the
+ transaction summary table. 5. Repeat steps 3 and 4 for each additional item the patron
+ wants to borrow. 6. (Optional): Click Print Receipt to print a receipt summarizing the
+ transactions for the patron. The Print Receipt window opens. Reference Reference
+ information consists of lists of commands, configuration files and settings, software
+ prerequisites, APIs, etc that need to be rigorously documented to support use cases
+ outside the core task documentation. Reference information is typically organized by
+ type, then by alphabetical order. For example, all system commands will be documented in
+ their own section of the manual in alphabetical order, and all APIs will be documented
+ in their own section of the manual in alphabetical order. System commmands: * autogen.sh
+ * import_holdings.pl * marc2bre.pl * osrf_ctl.sh * … APIs: *
+ open-ils.auth.authenticate.complete * open-ils.auth.authenticate.init * … Discuss how
+ each system feature would be used by each scenario institution If applicable, provide an
+ example of how each institutional scenario (Le Grande University vs. Metropolitan Public
+ Library Consortium) would likely put the feature being discussed into use. You will
+ probably want to include this information in the concept topic(s) introducing the
+ feature, or as a separate concept topic or set of topics following the introductory
+ concept topic. The scenarios give you a few different facets to describe when explaining
+ the topic to your reader: * academic vs. public libraries * consortiums vs. standalone
+ libraries * libraries with large collections vs. libraries with small collections Style
+ guidelines Use the active voice Avoid the passive voice. For example: Rather than: The
+ barcode is checked for a valid check digit when it is scanned. Use the active voice:
+ When you scan the barcode, the system checks for a valid check digit. If your sentence
+ contains “is”, be careful: it might be using the passive voice. Write concise sentences
+ Try to keep your sentences brief. Avoiding complex phrases with related clauses helps
+ readers concentrate on a single idea at a time. It also helps translators. Prefix
+ conditional clauses If your sentence is conditional, place the conditional clause at the
+ beginning of the sentence. When your reader skims your text and only sees the first part
+ of the sentence, they might take the wrong action. For example: Rather than: Click the
+ **Cancel** button to prevent the changes from being applied if the results did not match
+ your expectations. Use: If the results did not match your expectations, click the
+ **Cancel** button to prevent the changes from being applied. Contractions,
+ abbreviations, and acronyms Do not use contractions (“you're”, “we've”, “it's”) or Latin
+ abbreviations (e.g., etc., i.e.). These can be hard to translate and hard to read. If
+ you use an acronym, provide the full form of the acronym and include the acronym in
+ parentheses in the first use in your topic. After the acronym has been introduced, you
+ can use the acronym on its own for the remainder of the topic. Highlighting Use bold to
+ highlight the names of GUI elements such as field and button labels, window names, and
+ menu options. </para>
+ </section>
+</chapter>
Added: trunk/docs/1.6/books.xml
===================================================================
--- trunk/docs/1.6/books.xml (rev 0)
+++ trunk/docs/1.6/books.xml 2009-09-09 20:31:19 UTC (rev 14000)
@@ -0,0 +1,256 @@
+<?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="books" status="draft">
+ <title>Creating a Book</title>
+ <info>
+ <abstract>
+ <para>Books are the top level of organization for topics in a library. They are a collection
+ of sub-topics organized into chapters. This chapter describes how to create books in XML. </para>
+ <para>
+ <note>
+ <para>In most cases Evergreen documentation authors will not create books, but will be
+ authoring chapters or sections within books, as described in the chapter on document
+ structure. </para>
+ </note>
+ </para>
+ </abstract>
+ </info>
+ <section>
+ <title>Common Elements</title>
+ <simplesect>
+ <title>Overview</title>
+ <para>XML based books share a number of common elements. These include:</para>
+ <itemizedlist>
+ <listitem>
+ <para>A <tag class="element">XML version and encoding</tag> element</para>
+ </listitem>
+ <listitem>
+ <para>A <tag class="element">root</tag> element</para>
+ </listitem>
+ <listitem>
+ <para>A <tag class="element">title</tag> element</para>
+ </listitem>
+ <listitem>
+ <para>An <tag class="element">info</tag> element describing the book's front matter</para>
+ </listitem>
+ </itemizedlist>
+ </simplesect>
+ <simplesect>
+ <title>Root element</title>
+ <para>The root element of an XML book is the <tag class="element">book</tag> element. The <tag
+ class="element">book</tag> element provides a wrapper for parts, chapters, appendices,
+ indexes, and glossaries.</para>
+ <para>The <tag class="element">book</tag> element needs to include the XML namespace
+ declarations shown in <xref linkend="BookRootXMLNS"/>:</para>
+ <example xml:id="BookRootXMLNS">
+ <title>XML Namespace Declarations</title>
+ <programlisting><book <emphasis role="bold">xmlns="http://docbook.org/ns/docbook"
+xmlns:xi="http://www.w3.org/2001/XInclude"
+xmlns:xl="http://www.w3.org/1999/xlink"</emphasis>
+... ></programlisting>
+ </example>
+ <para>The <tag class="element">book</tag> element's <tag class="attribute">version</tag>
+ attribute must be set to <tag class="attvalue">5.0</tag>.</para>
+ <para>You must also specify a value for the <tag class="element">book</tag> element's <tag
+ class="attribute">xml:id</tag> attribute. </para>
+ <para>You can also use the <tag class="element">book</tag> element's <tag class="attribute"
+ >status</tag> attribute to embed a draft stamp in the book. You do this by setting <tag
+ class="attribute">status</tag> attribute to <tag class="attvalue">draft</tag>.</para>
+ </simplesect>
+ <simplesect>
+ <title>Title</title>
+ <para>The first child of the <tag class="element">book</tag> element is the <tag
+ class="element">title</tag> element. The contents of the <tag class="element">title</tag>
+ element is the title of the book.</para>
+ </simplesect>
+ <simplesect>
+ <title>Front matter</title>
+ <para>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.</para>
+ <para>The front matter also includes the following information:</para>
+ <itemizedlist>
+ <listitem>
+ <para>The release date</para>
+ </listitem>
+ <listitem>
+ <para>The product name and version</para>
+ </listitem>
+ <listitem>
+ <para>The date the document was updated</para>
+ </listitem>
+ <listitem>
+ <para>The common keywords for the book</para>
+ </listitem>
+ <listitem>
+ <para>The graphics for the front page</para>
+ </listitem>
+ </itemizedlist>
+ <para>All of the information in the front matter is boiler plate and should not be
+ updated.</para>
+ <para><xref linkend="legal"/> shows a book file with the front matter imported.</para>
+ <example xml:id="legal" pgwide="1">
+ <?dbfo pgwide="1"?>
+ <title>Front Matter Imported</title>
+ <programlisting><?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></programlisting>
+ </example>
+ </simplesect>
+ </section>
+ <section>
+ <title>Preface</title>
+ <simplesect>
+ <title>Overview</title>
+ <para>The preface of your book is placed into the XML file just after the <tag class="element"
+ >info</tag> element. It is specified inside of a <tag class="element">preface</tag>
+ element. The preface should be created in a separate file and imported, using an <tag
+ class="element">xinclude</tag> element, into the book file.</para>
+ </simplesect>
+ <simplesect>
+ <title>Parts of the preface</title>
+ <para>The preface of your book will have the following sections that are unique to a
+ book:</para>
+ <itemizedlist>
+ <listitem>
+ <para>What is covered in this book?</para>
+ </listitem>
+ <listitem>
+ <para>Who should read this book?</para>
+ </listitem>
+ <listitem>
+ <para>How to use this book?</para>
+ </listitem>
+ </itemizedlist>
+ <para>In addition there are several sections that are common to all of the books in the
+ library. These include:</para>
+ <itemizedlist>
+ <listitem>
+ <para>Library</para>
+ </listitem>
+ <listitem>
+ <para>How to get the latest updates</para>
+ </listitem>
+ <listitem>
+ <para>Additional support resources</para>
+ </listitem>
+ <listitem>
+ <para>Documentation conventions</para>
+ </listitem>
+ </itemizedlist>
+ <para>These common sections should be imported, using <tag class="element">xinclude</tag>
+ elements, from a common template area. This ensures that any changes are propagated across
+ the entire library.</para>
+ </simplesect>
+ <simplesect>
+ <title>Adding content to a preface</title>
+ <para>Writing a preface is identical to writing a chapter. This is discussed in <olink
+ targetdoc="StyleGuide" targetptr="chapter"/>.</para>
+ </simplesect>
+ <simplesect>
+ <title>Example</title>
+ <para><xref linkend="preface"/> shows a preface that can be imported into a book file.</para>
+ <example xml:id="preface" pgwide="1">
+ <?dbfo pgwide="1"?>
+ <title>Book Preface</title>
+ <programlisting><?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></programlisting>
+ </example>
+ </simplesect>
+ </section>
+ <section>
+ <title>Chapters</title>
+ <simplesect>
+ <title>Overview</title>
+ <para>After the preface, you add the chapters to your book. Chapters are created in separate
+ files and imported into the book file using <tag class="element">xinclude</tag> elements. </para>
+ <para>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.</para>
+ </simplesect>
+ <simplesect>
+ <title>Writing chapters</title>
+ <para>Adding content to a chapter is discussed in the <olink targetdoc="chapters"
+ targetptr="chapters"/></para>
+ </simplesect>
+ <simplesect>
+ <title>Importing chapters</title>
+ <para>Chapters are imported into a book using <tag class="element">xinclude</tag>
+ elements.</para>
+ </simplesect>
+ </section>
+ <section>
+ <title>Example Book</title>
+ <para><xref linkend="sectLevel"/> shows a book.</para>
+ <example xml:id="sectLevel" pgwide="1">
+ <?dbfo pgwide="1"?>
+ <title>An XML Book</title>
+ <programlisting><?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>Evergreen Guide to Martian Living</title>
+<info>
+<xi:include href="../common/legalblurb.xml" />
+<xi:include href="../common/copynotice.xml" />
+<xi:include href="../common/copydate.xml" />
+</info>
+<xi:include href="preface.xml" />
+<xi:include href="migration.xml" />
+<xi:include href="housekeeping.xml" />
+<xi:include href="recipes.xml" />
+<xi:include href="shopping.xml" />
+<index />
+</book></programlisting>
+ </example>
+ </section>
+</chapter>
Added: trunk/docs/1.6/build.xml
===================================================================
--- trunk/docs/1.6/build.xml (rev 0)
+++ trunk/docs/1.6/build.xml 2009-09-09 20:31:19 UTC (rev 14000)
@@ -0,0 +1,37 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project name="StyleGuide" default="all" basedir=".">
+ <property environment="env" />
+ <import file="${env.DBCK_HOME}/lib/build_artix_ns_common.xml"/>
+
+ <property name="DOCID" value="StyleGuide" />
+ <property name="LOGO" value="iona" />
+ <property name="ROOT" value="styleguide" />
+ <property name="HTMLSITEMAP" value="../site.xml" />
+ <property name="PDFSITEMAP" value="../sitepdf.xml" />
+
+ <!-- DO NOT MODIFY ANYTHING BELOW THIS LINE -->
+ <target name="all" depends="db,html,pdf" description="Builds everything" />
+ <target name="content" depends="html,pdf" description="Builds just the content" />
+
+ <target name="db" description="Builds the olink databases">
+ <antcall target="docbook.db">
+ <param name="docbook.in" value="${ROOT}.xml" />
+ </antcall>
+ </target>
+
+ <target name="html" description="Builds the html for the book">
+ <antcall target="docbook.html">
+ <param name="docbook.in" value="${ROOT}.xml" />
+ <param name="docbook.docid" value="${DOCID}" />
+ <param name="docbook.logo" value="${LOGO}" />
+ </antcall>
+ </target>
+
+ <target name="pdf" description="Builds the PDF version of the book">
+ <antcall target="docbook.pdf">
+ <param name="docbook.in" value="${ROOT}.xml" />
+ <param name="docbook.docid" value="${DOCID}" />
+ <param name="docbook.pdf" value="${ROOT}.pdf" />
+ </antcall>
+ </target>
+</project>
\ No newline at end of file
Added: trunk/docs/1.6/chapter.xml
===================================================================
--- trunk/docs/1.6/chapter.xml (rev 0)
+++ trunk/docs/1.6/chapter.xml 2009-09-09 20:31:19 UTC (rev 14000)
@@ -0,0 +1,117 @@
+<?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>Chapters and Other Root Elements</title>
+ <section>
+ <title>Guidance for Evergreen Authors</title>
+ <para>The following information is intended to clarify the elements in the documents you are
+ working with. If you use the Evergreen templates, they will at minimum have top-level
+ declarations filled out. </para>
+ <para>In most cases, you will be working with chapters or sections, as described below. However,
+ in some cases you may need to create a document from another root element, such as <tag
+ class="element">glossary</tag>.</para>
+ </section>
+ <section>
+ <title>Top-level Declarations</title>
+ <para>The first few lines of an XML chapter contains boilerplate markup. These lines include the
+ XML encoding statement and an entity declarations for the variables used in the chapter. If
+ you use the Evergreen templates, these will be filled out for you.</para>
+ </section>
+ <section>
+ <title>Root Element</title>
+ <para>The root element of an XML chapter is the <tag class="element">chapter</tag> element. The
+ <tag class="element">chapter</tag> element provides a wrapper for sections and
+ blocks.</para>
+ <para>The <tag class="element">chapter</tag> element needs to include the XML namespace
+ declarations shown in <xref linkend="ChaptRootXMLNS"/>:</para>
+ <example xml:id="ChaptRootXMLNS">
+ <title>XML Namespace Declarations</title>
+ <programlisting><chapter xmlns="http://docbook.org/ns/docbook"
+xmlns:xi="http://www.w3.org/2001/XInclude"
+xmlns:xl="http://www.w3.org/1999/xlink"></programlisting>
+ </example>
+ <para>The <tag class="element">chapter</tag> element's <tag class="attribute">version</tag>
+ attribute must be set to <tag class="attvalue">5.0</tag>.</para>
+ </section>
+ <section>
+ <title>Title</title>
+ <para>The first child of the <tag class="element">chapter</tag> element is the <tag
+ class="element">title</tag> element. The contents of the <tag class="element">title</tag>
+ element is the title of the chapter, such as Evergreen Circulation or Evergreen System
+ Administration.</para>
+ <para>Titles in Evergreen documentation are determined by the DIG, and follow the format:
+ Evergreen [Function]. </para>
+ </section>
+ <section xml:id="ChaptInfo">
+ <title>Chapter Info</title>
+ <para>After the <tag class="element">title</tag> element, a chapter should have an <tag
+ class="element">info</tag> element. This element contains the chapter summary and a list of
+ keywords that will be put into the generated metadata for this chapter.</para>
+ <para>The chapter summary is placed inside an <tag class="element">abstract</tag> element. The
+ <tag class="element">abstract</tag> element requires a nested <tag class="element"
+ >para</tag> element to wrap the text.</para>
+ <para>The keyword list is placed inside of a <tag class="element">keywordset</tag> element. Each
+ keyword in the list must be wrapped in a <tag class="element">keyword</tag> element. (Do we
+ want to use this?)</para>
+ </section>
+ <section xml:id="ChaptStructElements">
+ <title>Structural Elements</title>
+ <simplesect>
+ <title>Overview</title>
+ <para>Chapters are broken into sections and blocks.</para>
+ </simplesect>
+ <simplesect>
+ <title>Sections</title>
+ <para>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 <tag class="element"
+ >section</tag> elements.</para>
+ <para>Top-level sections can be broken down into five or fewer subsections. Subsections are
+ also denoted using <tag class="element">section</tag> elements.</para>
+ </simplesect>
+ <simplesect>
+ <title>Blocks (simplesect)</title>
+ <para>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.</para>
+ <para>Block-sections are denoted using <tag class="element">simplesect</tag> elements. Blocks
+ cannot be subdivided.</para>
+ </simplesect>
+ <simplesect>
+ <title>Example</title>
+ <para><xref linkend="chapter_detailExample"/> shows a more detailed view of a chapter.</para>
+ <example xml:id="chapter_detailExample" pgwide="1">
+ <?dbfo pgwide="1"?>
+ <title>Detailed View of a Chapter</title>
+ <programlisting><?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></programlisting>
+ </example>
+ </simplesect>
+ </section>
+</chapter>
Added: trunk/docs/1.6/conditional.xml
===================================================================
--- trunk/docs/1.6/conditional.xml (rev 0)
+++ trunk/docs/1.6/conditional.xml 2009-09-09 20:31:19 UTC (rev 14000)
@@ -0,0 +1,203 @@
+<?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="conditional">
+ <title>Conditional Text</title>
+ <section xml:id="ConditionalWriting">
+ <title>Writing with Conditional Text</title>
+ <simplesect>
+ <title>Overview</title>
+ <para>The guidelines on using conditional text are based on the <emphasis>Profiling</emphasis>
+ chapter from <link xl:href="http://www.sagehill.net/docbookxsl/index.html">DocBook XSL: The
+ Complete Guide</link>, by Bob Stayton. The current chapter does not describe all of the
+ features supported by DocBook XSL. In particular, this chapter discusses profiling using
+ only the <tag class="attribute">condition</tag> attribute, whereas the <emphasis>DocBook
+ XSL</emphasis> book also describes how to support profiling using other DocBook
+ attributes.</para>
+ </simplesect>
+ <simplesect>
+ <title>Conditionalizing elements</title>
+ <para>To conditionalize an element, set the element's <tag class="attribute">condition</tag>
+ attribute to the name of the condition you want to apply. For example, to conditionalize a
+ text block with the <code>fuse</code> condition:</para>
+ <programlisting><simplesect condition="fuse">
+ ...
+</simplesect></programlisting>
+ <para>When you conditionalize an element, the condition is applied to <emphasis>all of the
+ enclosed text and every sub-element</emphasis> of the conditionalized element. This
+ mechanism is flexible, because every element in DocBook supports the <tag class="attribute"
+ >condition</tag> attribute. For example, you can conditionalize an entire <tag
+ class="element">chapter</tag>, a <tag class="element">section</tag>, a <tag
+ class="element">figure</tag>, an <tag class="element">example</tag>, or even an individual
+ <tag class="element">code</tag> element.</para>
+ </simplesect>
+ <simplesect>
+ <title>Conditionalizing free-standing text</title>
+ <para>There is one special case not covered by the mechanism for conditionalizing elements.
+ What do you do, if you want to conditionalize a fragment of text that does not correspond to
+ an element? For example, you might want to conditionalize a sentence within a paragraph. In
+ this case, you can use the <tag class="element">phrase</tag> element to enclose the text
+ fragment and then apply the requisite condition to the <tag class="element">phrase</tag>
+ element.</para>
+ <para>The following example shows how to conditionalize a sentence so that it appears only in
+ the Artix version of the book:</para>
+ <programlisting><para>&prodname; supports a multitude of integration options.
+<phrase condition="artix">In particular, you can optionally plug in a mainframe integration kit</phrase>
+</para></programlisting>
+ </simplesect>
+ <simplesect>
+ <title>Conditionalizing comments</title>
+ <para>You can also use conditional text to manage draft comments in a book. These are the kind
+ of comments that you would like to make visible in a draft copy of the output: for example,
+ reminders to self and directions to the reviewer. It is recommended that you insert comments
+ using the remark element with the <code>comment</code> condition applied. For
+ example:</para>
+ <programlisting><remark condition="comment">REVISIT - Your comment here!</remark></programlisting>
+ <para>To simplify entering comments, the Evergreen template for the Oxygen editor includes a
+ custom option, <guimenuitem>DocBook4 | Insert Comment</guimenuitem>, which automatically
+ inserts a conditionalized <tag class="element">remark</tag> element.</para>
+ </simplesect>
+ <simplesect>
+ <title>Applying multiple conditions</title>
+ <para>If required, you can apply multiple conditions to a single element, using the semicolon,
+ <literal>;</literal>, as the separator character. For example, to apply both the
+ <code>unix</code> and <code>win</code> conditions to a <tag class="element"
+ >simplesect</tag> element, set the <tag class="attribute">condition</tag> attribute as
+ follows:</para>
+ <programlisting><simplesect condition="unix;win"> ... </simplesect></programlisting>
+ <para>Semantically, the effect of setting both of these conditions is that, at build time, the
+ <tag class="element">simplesect</tag> element will be included in the output if either the
+ <code>unix</code> condition OR the <code>win</code> condition is enabled.</para>
+ </simplesect>
+ </section>
+ <section xml:id="ConditionalBuilding">
+ <title>Building Books with Conditional Text</title>
+ <simplesect>
+ <title>Overview</title>
+ <para>When building a book with conditional text, you need to use a special Ant build file to
+ produce the output. The targets of the conditional build file are the same as a regular
+ build file, but the process for generating the output is slightly different. When building a
+ conditional book, the build system first generates an intermediate file,
+ <filename><replaceable>bookname</replaceable>.prfl</filename>, which contains a version
+ of the <filename><replaceable>bookname</replaceable>.xml</filename> book where all of the
+ conditions have been applied. The
+ <filename><replaceable>bookname</replaceable>.prfl</filename> file is then used as the
+ input for the next stage of book building, using the regular templates for HTML and
+ PDF.</para>
+ </simplesect>
+ <simplesect>
+ <title>Steps for building with conditions</title>
+ <para>To build a book with conditions, perform the following steps:</para>
+ <orderedlist>
+ <listitem>
+ <para><xref linkend="ConditionalBuildingGet"/></para>
+ </listitem>
+ <listitem>
+ <para><xref linkend="ConditionalBuildingSet"/></para>
+ </listitem>
+ <listitem>
+ <para><xref linkend="ConditionalBuildingBuild"/></para>
+ </listitem>
+ </orderedlist>
+ </simplesect>
+ <simplesect xml:id="ConditionalBuildingGet">
+ <title>Get the conditional build.xml file</title>
+ <para>To build a book with conditional text, use the conditional version of the Ant
+ <filename>build.xml</filename> file. In the <filename>docs_tools</filename> SVN
+ repository, look for the following file:
+ <filename>trunk/docbook-output/dcbk/custom/build_book_with_conditions.xml</filename></para>
+ <para>Copy this build file into your book directory and rename it to
+ <filename>build.xml</filename>.</para>
+ </simplesect>
+ <simplesect xml:id="ConditionalBuildingSet">
+ <title>Set conditions in build.xml</title>
+ <para>In addition to the usual book properties that you must set in a
+ <filename>build.xml</filename> file (that is, <code>ROOT</code>, <code>DOCID</code>, and
+ <code>LOGO</code>), you must also set a <code>CONDITIONS</code> property that lists the
+ conditions you want to enable. If you want to enable multiple conditions, separate them
+ using a semicolon character, for example:</para>
+ <programlisting> <property name="CONDITIONS" value="condition1;condition2" /></programlisting>
+ <para>This setting would ensure that any conditions marked with <code>condition1</code> AND
+ any conditions marked with <code>condition2</code> are included in the output. In other
+ words, the more conditions you specify here, the more output text you might get.</para>
+ </simplesect>
+ <simplesect xml:id="ConditionalBuildingBuild">
+ <title>Build the book</title>
+ <para>The conditional <filename>build.xml</filename> file supports the same Ant targets for
+ building a book as the normal <filename>build.xml</filename> file. For example, to build
+ both the HTML and PDF output, you can execute Ant with the default target, as
+ follows:</para>
+ <programlisting>> ant</programlisting>
+ <para>The build file also supports the <code>db</code>, <code>pdf</code>, and
+ <code>html</code> Ant targets. In the course of generating the document output, the build
+ file produces an intermediate file,
+ <filename><replaceable>bookname</replaceable>.prfl</filename>, which is a DocBook XML file
+ to which the conditions have been applied.</para>
+ </simplesect>
+ <simplesect>
+ <title>Example</title>
+ <para><xref linkend="ConditionalBuildingExSSCBF"/> shows the top of the
+ <filename>build.xml</filename> file for the FUSE Mediation Router Programmer's Guide,
+ including conditional settings. This book is shared between the FUSE and Artix product.
+ FUSE-specific parts of the book are marked with the condition, <code>fuse</code>, and
+ Artix-specific parts of the book are marked, <code>artix</code>. <xref
+ linkend="ConditionalBuildingExSSCBF"/> shows the settings for building the FUSE version of
+ the book in draft format.</para>
+ <example xml:id="ConditionalBuildingExSSCBF">
+ <title>Sample Settings in a Conditional build.xml File</title>
+ <programlisting><?xml version="1.0" encoding="UTF-8"?>
+<project name="MRGettingStarted" default="all" basedir=".">
+ <property environment="env" />
+ <!-- Choose one of the following common build files to import:
+ build_artix_common.xml (Artix)
+ build_fuse_common.xml (FUSE)
+ -->
+ <import file="${env.DBCK_HOME}/lib/build_fuse_common.xml"/>
+
+ <!-- Edit the following properties for your book: -->
+ <property name="ROOT" value="prog_guide" />
+ <property name="DOCID" value="FuseMRProg" />
+ <property name="LOGO" value="fmr" />
+ <property name="CONDITIONS" value="fuse;comment" />
+
+ <!-- DO NOT MODIFY ANYTHING BELOW THIS LINE -->
+ ...</programlisting>
+ </example>
+ <para>Where the <code>CONDITIONS</code> property specifies two conditions: <code>fuse</code>
+ and <code>comment</code>. This build file processes the conditions as follows:</para>
+ <itemizedlist>
+ <listitem>
+ <para>Unmarked elements not enclosed by conditionalized elements are included in the
+ output.</para>
+ </listitem>
+ <listitem>
+ <para>Elements marked with the <code>artix</code> condition are
+ <emphasis>excluded</emphasis> from the output.</para>
+ </listitem>
+ <listitem>
+ <para>Elements marked with the <code>fuse</code> condition are
+ <emphasis>included</emphasis> in the output.</para>
+ </listitem>
+ <listitem>
+ <para>Elements marked with the <code>comment</code> condition are
+ <emphasis>included</emphasis> in the output.</para>
+ </listitem>
+ </itemizedlist>
+ </simplesect>
+ <simplesect>
+ <title>Managing comments</title>
+ <para>Unlike other conditions, which typically remain unchanged for a long time, the
+ <code>comment</code> condition changes relatively frequently, as you switch between
+ producing draft copies and release copies. It is something that you need to keep in mind,
+ when building a release, that you need to disable the <code>comment</code> condition before
+ building the output.</para>
+ </simplesect>
+ <simplesect>
+ <title>Building without conditions</title>
+ <para>It is not possible to build a book with a blank <code>CONDITIONS</code> property. If you
+ want to build a book without conditions, you could either replace the conditional
+ <filename>build.xml</filename> file with a regular <filename>build.xml</filename> file or
+ you could enable every condition in the <code>CONDITIONS</code> property (thereby ensuring
+ that the complete source is processed).</para>
+ </simplesect>
+ </section>
+</chapter>
Added: trunk/docs/1.6/exclude.xml
===================================================================
--- trunk/docs/1.6/exclude.xml (rev 0)
+++ trunk/docs/1.6/exclude.xml 2009-09-09 20:31:19 UTC (rev 14000)
@@ -0,0 +1,370 @@
+<?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="exclusions">
+ <title>Elements Currently Unused in Evergreen Documentation</title>
+ <para>Evergreen documentation uses a subset of elements defined by DocBook. The following elements
+ are not planned to be used. If you believe you need to use one of these tags, contact the
+ Documentation Interest Group for more guidance.</para>
+ <itemizedlist>
+ <listitem>
+ <para><tag class="element">ackno</tag></para>
+ </listitem>
+ <listitem>
+ <para><tag class="element">address</tag></para>
+ </listitem>
+ <listitem>
+ <para><tag class="element">affiliation</tag></para>
+ </listitem>
+ <listitem>
+ <para><tag class="element">artpagenums</tag></para>
+ </listitem>
+ <listitem>
+ <para><tag class="element">audiodata</tag></para>
+ </listitem>
+ <listitem>
+ <para><tag class="element">audioobject</tag></para>
+ </listitem>
+ <listitem>
+ <para><tag class="element">authorblurb</tag></para>
+ </listitem>
+ <listitem>
+ <para><tag class="element">beginpage</tag></para>
+ </listitem>
+ <listitem>
+ <para><tag class="element">bibliocoverage</tag></para>
+ </listitem>
+ <listitem>
+ <para><tag class="element">bibliodiv</tag></para>
+ </listitem>
+ <listitem>
+ <para><tag class="element">biblioentry</tag></para>
+ </listitem>
+ <listitem>
+ <para><tag class="element">bibliography</tag></para>
+ </listitem>
+ <listitem>
+ <para><tag class="element">bibliographyinfo</tag></para>
+ </listitem>
+ <listitem>
+ <para><tag class="element">biblioid</tag></para>
+ </listitem>
+ <listitem>
+ <para><tag class="element">bibliolist</tag></para>
+ </listitem>
+ <listitem>
+ <para><tag class="element">bibliomixed</tag></para>
+ </listitem>
+ <listitem>
+ <para><tag class="element">bibliomset</tag></para>
+ </listitem>
+ <listitem>
+ <para><tag class="element">biblioref</tag></para>
+ </listitem>
+ <listitem>
+ <para><tag class="element">bibliorelation</tag></para>
+ </listitem>
+ <listitem>
+ <para><tag class="element">biblioset</tag></para>
+ </listitem>
+ <listitem>
+ <para><tag class="element">bibliosource</tag></para>
+ </listitem>
+ <listitem>
+ <para><tag class="element">blockinfo</tag></para>
+ </listitem>
+ <listitem>
+ <para><tag class="element">citation</tag></para>
+ </listitem>
+ <listitem>
+ <para><tag class="element">citebiblioid</tag></para>
+ </listitem>
+ <listitem>
+ <para><tag class="element">citerefentry</tag></para>
+ </listitem>
+ <listitem>
+ <para><tag class="element">citetitle</tag></para>
+ </listitem>
+ <listitem>
+ <para><tag class="element">city</tag></para>
+ </listitem>
+ <listitem>
+ <para><tag class="element">collab</tag></para>
+ </listitem>
+ <listitem>
+ <para><tag class="element">collabname</tag></para>
+ </listitem>
+ <listitem>
+ <para><tag class="element">colophone</tag></para>
+ </listitem>
+ <listitem>
+ <para><tag class="element">confdates</tag></para>
+ </listitem>
+ <listitem>
+ <para><tag class="element">confgroup</tag></para>
+ </listitem>
+ <listitem>
+ <para><tag class="element">conftitle</tag></para>
+ </listitem>
+ <listitem>
+ <para><tag class="element">contractnum</tag></para>
+ </listitem>
+ <listitem>
+ <para><tag class="element">contractsponsor</tag></para>
+ </listitem>
+ <listitem>
+ <para><tag class="element">corpname</tag></para>
+ </listitem>
+ <listitem>
+ <para><tag class="element">country</tag></para>
+ </listitem>
+ <listitem>
+ <para><tag class="element">dedication</tag></para>
+ </listitem>
+ <listitem>
+ <para><tag class="element">fax</tag></para>
+ </listitem>
+ <listitem>
+ <para><tag class="element">firstname</tag></para>
+ </listitem>
+ <listitem>
+ <para><tag class="element">glossaryinfo</tag></para>
+ </listitem>
+ <listitem>
+ <para><tag class="element">highlights</tag></para>
+ </listitem>
+ <listitem>
+ <para><tag class="element">honorific</tag></para>
+ </listitem>
+ <listitem>
+ <para><tag class="element">informalequation</tag></para>
+ </listitem>
+ <listitem>
+ <para><tag class="element">inlineequation</tag></para>
+ </listitem>
+ <listitem>
+ <para><tag class="element">invpartnumber</tag></para>
+ </listitem>
+ <listitem>
+ <para><tag class="element">isbn</tag></para>
+ </listitem>
+ <listitem>
+ <para><tag class="element">issn</tag></para>
+ </listitem>
+ <listitem>
+ <para><tag class="element">issuenum</tag></para>
+ </listitem>
+ <listitem>
+ <para><tag class="element">jobtitle</tag></para>
+ </listitem>
+ <listitem>
+ <para><tag class="element">lineage</tag></para>
+ </listitem>
+ <listitem>
+ <para><tag class="element">manvolnum</tag></para>
+ </listitem>
+ <listitem>
+ <para><tag class="element">modespec</tag></para>
+ </listitem>
+ <listitem>
+ <para><tag class="element">orgdiv</tag></para>
+ </listitem>
+ <listitem>
+ <para><tag class="element">otheraddr</tag></para>
+ </listitem>
+ <listitem>
+ <para><tag class="element">pagenums</tag></para>
+ </listitem>
+ <listitem>
+ <para><tag class="element">partintro</tag></para>
+ </listitem>
+ <listitem>
+ <para><tag class="element">personblurb</tag></para>
+ </listitem>
+ <listitem>
+ <para><tag class="element">personname</tag></para>
+ </listitem>
+ <listitem>
+ <para><tag class="element">phone</tag></para>
+ </listitem>
+ <listitem>
+ <para><tag class="element">pob</tag></para>
+ </listitem>
+ <listitem>
+ <para><tag class="element">postcode</tag></para>
+ </listitem>
+ <listitem>
+ <para><tag class="element">prefaceinfo</tag></para>
+ </listitem>
+ <listitem>
+ <para><tag class="element">primaryie</tag></para>
+ </listitem>
+ <listitem>
+ <para><tag class="element">printhistory</tag></para>
+ </listitem>
+ <listitem>
+ <para><tag class="element">productnumber</tag></para>
+ </listitem>
+ <listitem>
+ <para><tag class="element">publisher</tag></para>
+ </listitem>
+ <listitem>
+ <para><tag class="element">publishername</tag></para>
+ </listitem>
+ <listitem>
+ <para><tag class="element">pubsnumber</tag></para>
+ </listitem>
+ <listitem>
+ <para><tag class="element">refsect1</tag></para>
+ </listitem>
+ <listitem>
+ <para><tag class="element">refsect1info</tag></para>
+ </listitem>
+ <listitem>
+ <para><tag class="element">refsect2</tag></para>
+ </listitem>
+ <listitem>
+ <para><tag class="element">refsect2info</tag></para>
+ </listitem>
+ <listitem>
+ <para><tag class="element">refsect3</tag></para>
+ </listitem>
+ <listitem>
+ <para><tag class="element">refsect3info</tag></para>
+ </listitem>
+ <listitem>
+ <para><tag class="element">revdescription</tag></para>
+ </listitem>
+ <listitem>
+ <para><tag class="element">revhistory</tag></para>
+ </listitem>
+ <listitem>
+ <para><tag class="element">revision</tag></para>
+ </listitem>
+ <listitem>
+ <para><tag class="element">screeninfo</tag></para>
+ </listitem>
+ <listitem>
+ <para><tag class="element">secondaryie</tag></para>
+ </listitem>
+ <listitem>
+ <para><tag class="element">sect1</tag></para>
+ </listitem>
+ <listitem>
+ <para><tag class="element">sect1info</tag></para>
+ </listitem>
+ <listitem>
+ <para><tag class="element">sect2</tag></para>
+ </listitem>
+ <listitem>
+ <para><tag class="element">sect2info</tag></para>
+ </listitem>
+ <listitem>
+ <para><tag class="element">sect3</tag></para>
+ </listitem>
+ <listitem>
+ <para><tag class="element">sect3info</tag></para>
+ </listitem>
+ <listitem>
+ <para><tag class="element">sect4</tag></para>
+ </listitem>
+ <listitem>
+ <para><tag class="element">sect4info</tag></para>
+ </listitem>
+ <listitem>
+ <para><tag class="element">sect5</tag></para>
+ </listitem>
+ <listitem>
+ <para><tag class="element">sect5info</tag></para>
+ </listitem>
+ <listitem>
+ <para><tag class="element">seealsoie</tag></para>
+ </listitem>
+ <listitem>
+ <para><tag class="element">seeie</tag></para>
+ </listitem>
+ <listitem>
+ <para><tag class="element">seg</tag></para>
+ </listitem>
+ <listitem>
+ <para><tag class="element">seglistitem</tag></para>
+ </listitem>
+ <listitem>
+ <para><tag class="element">segmentedlist</tag></para>
+ </listitem>
+ <listitem>
+ <para><tag class="element">segtitle</tag></para>
+ </listitem>
+ <listitem>
+ <para><tag class="element">seriesvolnums</tag></para>
+ </listitem>
+ <listitem>
+ <para><tag class="element">shortaffil</tag></para>
+ </listitem>
+ <listitem>
+ <para><tag class="element">sidebar</tag></para>
+ </listitem>
+ <listitem>
+ <para><tag class="element">sidebarinfo</tag></para>
+ </listitem>
+ <listitem>
+ <para><tag class="element">simpara</tag></para>
+ </listitem>
+ <listitem>
+ <para><tag class="element">state</tag></para>
+ </listitem>
+ <listitem>
+ <para><tag class="element">street</tag></para>
+ </listitem>
+ <listitem>
+ <para><tag class="element">surname</tag></para>
+ </listitem>
+ <listitem>
+ <para><tag class="element">tertiaryie</tag></para>
+ </listitem>
+ <listitem>
+ <para><tag class="element">titleabbrev</tag></para>
+ </listitem>
+ <listitem>
+ <para><tag class="element">toc</tag></para>
+ </listitem>
+ <listitem>
+ <para><tag class="element">tocback</tag></para>
+ </listitem>
+ <listitem>
+ <para><tag class="element">tocchap</tag></para>
+ </listitem>
+ <listitem>
+ <para><tag class="element">tocentry</tag></para>
+ </listitem>
+ <listitem>
+ <para><tag class="element">tocfront</tag></para>
+ </listitem>
+ <listitem>
+ <para><tag class="element">toclevel1</tag></para>
+ </listitem>
+ <listitem>
+ <para><tag class="element">toclevel2</tag></para>
+ </listitem>
+ <listitem>
+ <para><tag class="element">toclevel3</tag></para>
+ </listitem>
+ <listitem>
+ <para><tag class="element">toclevel4</tag></para>
+ </listitem>
+ <listitem>
+ <para><tag class="element">toclevel5</tag></para>
+ </listitem>
+ <listitem>
+ <para><tag class="element">tocpart</tag></para>
+ </listitem>
+ <listitem>
+ <para><tag class="element">videodata</tag></para>
+ </listitem>
+ <listitem>
+ <para><tag class="element">videoobject</tag></para>
+ </listitem>
+ <listitem>
+ <para><tag class="element">volumenum</tag></para>
+ </listitem>
+ </itemizedlist>
+</chapter>
Added: trunk/docs/1.6/figures.xml
===================================================================
--- trunk/docs/1.6/figures.xml (rev 0)
+++ trunk/docs/1.6/figures.xml 2009-09-09 20:31:19 UTC (rev 14000)
@@ -0,0 +1,169 @@
+<?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="figures">
+ <title>Figures, Diagrams, Screen Shots, and In-Line Graphics</title>
+ <section>
+ <title>Overview</title>
+ <para>Graphics, such as a diagram or a screen shot of a user interface, make a document more
+ readable. Often, graphics also help clarify abstract concepts.</para>
+ <para>Figures, diagrams, and screen shots contain images stored in external files. They are
+ denoted using one of two elements: <tag class="element">figure</tag> or <tag class="element"
+ >screenshot</tag>. The <tag class="element">figure</tag> element is used to denote a figure
+ or a diagram. The <tag class="element">screenshot</tag> element is used to denote a screen
+ shot.</para>
+ </section>
+ <section>
+ <title>Image Data</title>
+ <para>The preferred data format for images is PNG. However, images can be accepted in the
+ following formats:</para>
+ <itemizedlist>
+ <listitem>
+ <para>JPEG</para>
+ </listitem>
+ <listitem>
+ <para>GIF</para>
+ </listitem>
+ </itemizedlist>
+ <para>Images should be placed in an <filename class="directory">images</filename> folder
+ directly under the folder containing the document source. </para>
+ <para>Image size...</para>
+ </section>
+ <section>
+ <title>Image Size</title>
+ <para>Image files should have a maximum width of 900 pixels.</para>
+ <para>Image scaling should be set to 75%. This is ignored for HTML output and ensures images are
+ optimally sized for PDF files. </para>
+ </section>
+ <section>
+ <title>Figures and Diagrams</title>
+ <para>Figures and diagrams are marked up the same way. They are both placed in a <tag
+ class="element">figure</tag> element. The <tag class="element">figure</tag> element is a
+ container for the caption and data that make up the figure or diagram.</para>
+ <para>The caption is specified by a <tag class="element">title</tag> element. The <tag
+ class="element">title</tag> element is the first child element of the<tag class="element"
+ >figure</tag> element. The contents of the <tag class="element">title</tag> element is the
+ caption used for the figure. It is also the default text used when you cross reference the
+ figure.</para>
+ <para>The image data is specified in a <tag class="element">mediaobject</tag> element. The <tag
+ class="element">mediaobject</tag> element is a wrapper for an <tag class="element"
+ >imageobject</tag> element. The <tag class="element">imageobject</tag> element is also a
+ wrapper element. The <tag class="element">imageobject</tag> element wraps an <tag
+ class="element">imagedata</tag> element that specifies the name of the file containing the
+ image.</para>
+ <para>The <tag class="element">imagedata</tag> element has no content. All of the information is
+ specified using three attributes:</para>
+ <table>
+ <title>Attributes for imagedata Element</title>
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>Attribute</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>
+ <tag class="attribute">align</tag>
+ </entry>
+ <entry>Specifies how the image is aligned on the page. Valid values are <tag
+ class="attvalue">left</tag>, <tag class="attvalue">right</tag>, and <tag
+ class="attvalue">center</tag>.</entry>
+ </row>
+ <row>
+ <entry>
+ <tag class="attribute">fileref</tag>
+ </entry>
+ <entry>Specifies the location of the file containing the image.</entry>
+ </row>
+ <row>
+ <entry>
+ <tag class="attribute">format</tag>
+ </entry>
+ <entry>Specifies the type of data used to specify the image. Valid values are <tag
+ class="attvalue">GIF</tag>, <tag class="attvalue">JPG</tag>, and <tag
+ class="attvalue">PNG</tag>.</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ <para><xref linkend="figure_example"/> shows the mark-up for a figure.</para>
+ <example xml:id="figure_example">
+ <title>Mark-up for a Figure</title>
+ <programlisting><figure xml:id="fig_1">
+ <title>CeltiXfire WAR Structure</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata align="center"
+ fileref="./images/tomcat_war.gif"
+ format="GIF" />
+ </imageobject>
+ </mediaobject>
+ ...
+</figure></programlisting>
+ </example>
+ </section>
+ <section>
+ <title>Screen Shots</title>
+ <para>Screen shots are also marked up using a <tag class="element">figure</tag> element.
+ However, a screen shot uses one additional wrapper element. The <tag class="element"
+ >screenshot</tag> element wraps the <tag class="element">mediaobject</tag> element as shown
+ in <xref linkend="screen_example"/>.</para>
+ <example xml:id="screen_example">
+ <title>Mark-up for a Screen Shot</title>
+ <programlisting><figure xml:id="screen_1">
+ <title>SOA Tools Welcome Screen</title>
+ <screenshot>
+ <mediaobject>
+ <imageobject>
+ <imagedata align="center"
+ fileref="./images/welcome.gif"
+ format="GIF" />
+ </imageobject>
+ </mediaobject>
+ </screenshot>
+ ...
+</figure></programlisting>
+ </example>
+ </section>
+ <section>
+ <title>In-Line Graphics</title>
+ <para>Graphical elements that need to be placed in-line with the text of a paragraph are marked
+ up using the <tag class="element">inlinemediaobject</tag> element. Like the <tag
+ class="element">mediaobject</tag> element, the <tag class="element">inlinemediaobject</tag>
+ element is a wrapper for an <tag class="element">imageobject</tag> element. <xref
+ linkend="inline_example"/> shows the mark-up for an in-line graphic.</para>
+ <example xml:id="inline_example">
+ <title>Mark-up for an In-Line Graphic</title>
+ <programlisting><inlinemediaobject>
+ <imageobject>
+ <imagedata align="center" fileref="./images/larrow.gif"
+ format="GIF" />
+ </imageobject>
+ ...
+</inlinemediaobject></programlisting>
+ </example>
+ </section>
+ <section>
+ <title>Adding Alternative Text</title>
+ <para>For better accessibility and to comply with federal and local accessibility guidelines,
+ all images in DocBook files should include alternative text.</para>
+ <para>To include alternative text with a graphic, add a <tag class="element">textobject</tag>
+ element after the <tag class="element">imageobject</tag> element. The <tag class="element"
+ >textobject</tag> element has a single <tag class="element">phrase</tag> child element. The
+ value of the <tag class="element">phrase</tag> element is the alternative text used when the
+ documentation is generated to HTML.</para>
+ <example xml:id="alttext_example">
+ <title>Mark-up for Alternative Text</title>
+ <programlisting><mediaobject>
+ <imageobject>
+ <imagedata align="center" fileref="./images/config.gif"
+ format="GIF" />
+ </imageobject>
+ <textobject>
+ <phrase>Configuration Hierarchy</phrase>
+ </textobject>
+</mediaobject></programlisting>
+ </example>
+ </section>
+</chapter>
Added: trunk/docs/1.6/filenames.xml
===================================================================
--- trunk/docs/1.6/filenames.xml (rev 0)
+++ trunk/docs/1.6/filenames.xml 2009-09-09 20:31:19 UTC (rev 14000)
@@ -0,0 +1,76 @@
+<?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="filenames">
+ <title>File Structure and Filenames</title>
+
+ <info>
+ <abstract>
+ <para>This chapter describes the physical file structure for Evergreen documentation and file
+ naming conventions, including the <tag class="element">olink</tag> element. </para>
+ </abstract>
+ </info>
+ <section>
+ <title>File Structure for Evergreen Documentation</title>
+ <simplesect>
+ <title>Overview</title>
+ <para>The files for Evergreen documentation reside within a public directory on
+ evergreen-ils.org. </para>
+ </simplesect>
+ <simplesect>
+ <title>File structure for Evergreen documents</title>
+ <itemizedlist>
+ <listitem>
+ <para>The set is represented by set.xml, a single file in the docs subdirectory of
+ evergreen-ils.org</para>
+ </listitem>
+ <listitem>
+ <para>The two book elements are in separate subdirectories under the docs subdirectory,
+ and are labeled book1.xml and book2.xml</para>
+ </listitem>
+ <listitem>
+ <para>Chapter elements are in their own separate subdirectories under their respective
+ book directories</para>
+ </listitem>
+ <listitem>
+ <para>Glossaries and similar chapter-like elements are treated like chapters, and are in
+ separate subdirectories under their respective book directories</para>
+ </listitem>
+ <listitem>
+ <para>Images and similar media files are placed in subdirectories under their respective
+ folders.</para>
+ </listitem>
+ </itemizedlist>
+ </simplesect>
+ </section>
+ <section>
+ <title>Filename conventions</title>
+ <itemizedlist>
+ <listitem>
+ <para>Evergreen filenames are in lower case without underscores or periods.</para>
+ </listitem>
+ <listitem>
+ <para>The folders for images and other multimedia are named media. </para>
+ </listitem>
+ <listitem>
+ <para>The XML id for the chapter is the same as the XML filename, such as sysadmin. </para>
+ </listitem>
+ </itemizedlist>
+ </section>
+
+ <section>
+ <title>Conventions for olinks</title>
+ <itemizedlist>
+ <listitem>
+ <para>To simplify the creation of olinks between between books, every Evergreen file has a
+ <glossterm>document id</glossterm> that parallels the file's filename and xml:id
+ attribute. Therefore, a book-level file called book2.xml has an xml:id of book2 and a
+ document id of book2, while a chapter file called sysadmin.xml has an xml:id of sysadmin
+ and also a document id of sysadmin.</para>
+ </listitem>
+ <listitem>
+ <para>The document id is the first element within the file after the xml declaration, and
+ has the structure element id="name".</para>
+ </listitem>
+ </itemizedlist>
+ </section>
+</chapter>
Added: trunk/docs/1.6/general.xml
===================================================================
--- trunk/docs/1.6/general.xml (rev 0)
+++ trunk/docs/1.6/general.xml 2009-09-09 20:31:19 UTC (rev 14000)
@@ -0,0 +1,208 @@
+<?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="general">
+ <title>General Elements and Other Elements not Discussed Elsewhere</title>
+ <section>
+ <title>Overview</title>
+ <para>Since DocBook was defined to describe a wide range of publishable content, it includes a
+ number of elements that are used to perform common tasks. These elements include ones that
+ specify superscripts and emphasis.</para>
+ </section>
+ <section>
+ <title>Formatting Elements</title>
+ <para>The following are common formatting elements used in DocBook:</para>
+ <segmentedlist>
+ <segtitle>Element</segtitle>
+ <segtitle>Description</segtitle>
+ <seglistitem>
+ <seg>
+ <tag class="element">emphasis</tag>
+ </seg>
+ <seg>Specifies that the content of the element is to be emphasized by either
+ <emphasis>italics</emphasis> or <emphasis role="strong">boldface</emphasis>. The default
+ is to use italics. Specify boldface by setting the <tag class="attribute">role</tag>
+ attribute to <tag class="attvalue">bold</tag>.</seg>
+ </seglistitem><seglistitem>
+ <seg>
+ <tag class="element">literallayout</tag>
+ </seg>
+ <seg>Specifies that the content of the element is to be reproduced with all of the
+ whitespace preserved.</seg>
+ </seglistitem><seglistitem>
+ <seg>
+ <tag class="element">subscript</tag>
+ </seg>
+ <seg>Specifies that the content of the element is a subscript as in
+ H<subscript>2</subscript>O.</seg>
+ </seglistitem><seglistitem>
+ <seg>
+ <tag class="element">superscript</tag>
+ </seg>
+ <seg>Specifies that the content of the element is a superscript as in
+ E=MC<superscript>2</superscript>.</seg>
+ </seglistitem></segmentedlist>
+ </section>
+ <section>
+ <title>General Computing Elements</title>
+ <para>The following are elements used for describing computer technology:</para>
+ <segmentedlist>
+ <segtitle>Element</segtitle>
+ <segtitle>Description</segtitle>
+ <seglistitem>
+ <seg>
+ <tag class="element">action</tag>
+ </seg>
+ <seg>Specifies that content describes a response to some user initiated action.</seg>
+ </seglistitem><seglistitem>
+ <seg>
+ <tag class="element">application</tag>
+ </seg>
+ <seg>Specifies that the content is the name of a piece of software.</seg>
+ </seglistitem><seglistitem>
+ <seg>
+ <tag class="element">computeroutput</tag>
+ </seg>
+ <seg>Specifies that the content is text printed on a computer display.</seg>
+ </seglistitem><seglistitem>
+ <seg>
+ <tag class="element">database</tag>
+ </seg>
+ <seg>Specifies that the content is the name of a database, or part of a database.</seg>
+ </seglistitem><seglistitem>
+ <seg>
+ <tag class="element">email</tag>
+ </seg>
+ <seg>Specifies that the content is an e-mail address.</seg>
+ </seglistitem><seglistitem>
+ <seg>
+ <tag class="element">envar</tag>
+ </seg>
+ <seg>Specifies that the content is the name of an environment variable.</seg>
+ </seglistitem><seglistitem>
+ <seg>
+ <tag class="element">errorcode</tag>
+ </seg>
+ <seg>Specifies that the content is an error code.</seg>
+ </seglistitem><seglistitem>
+ <seg>
+ <tag class="element">errorname</tag>
+ </seg>
+ <seg>Specifies that the content is the name of an error.</seg>
+ </seglistitem><seglistitem>
+ <seg>
+ <tag class="element">errortext</tag>
+ </seg>
+ <seg>Specifies that the content is the text generated when an error occurs.</seg>
+ </seglistitem><seglistitem>
+ <seg>
+ <tag class="element">filename</tag>
+ </seg>
+ <seg>Specifies that the content is the name of a file.</seg>
+ </seglistitem><seglistitem>
+ <seg>
+ <tag class="element">hardware</tag>
+ </seg>
+ <seg>Specifies that the content is a piece of computer hardware.</seg>
+ </seglistitem><seglistitem>
+ <seg>
+ <tag class="element">option</tag>
+ </seg>
+ <seg>Specifies that the content is an option to a command.</seg>
+ </seglistitem><seglistitem>
+ <seg>
+ <tag class="element">prompt</tag>
+ </seg>
+ <seg>Specifies that the content is the string used as a prompt for data on a computer
+ screen.</seg>
+ </seglistitem><seglistitem>
+ <seg>
+ <tag class="element">userinput</tag>
+ </seg>
+ <seg>Specifies that the content is data a user enters into a computer system.</seg>
+ </seglistitem></segmentedlist>
+ </section>
+ <section>
+ <title>Other General Elements</title>
+ <para>The following are other general use elements used in DocBook:</para>
+ <segmentedlist>
+ <segtitle>Element</segtitle>
+ <segtitle>Description</segtitle>
+ <seglistitem>
+ <seg>
+ <tag class="element">abbrev</tag>
+ </seg>
+ <seg>Specifies that the content is an abbreviation.</seg>
+ </seglistitem><seglistitem>
+ <seg>
+ <tag class="element">acronym</tag>
+ </seg>
+ <seg>Specifies that the content is an acronym.</seg>
+ </seglistitem><seglistitem>
+ <seg>
+ <tag class="element">firstterm</tag>
+ </seg>
+ <seg>Specifies that the content is the first occurrence of a new term or is a term that is
+ used a context specific manner.</seg>
+ </seglistitem><seglistitem>
+ <seg>
+ <tag class="element">literal</tag>
+ </seg>
+ <seg>Specifies that the content is a literal value.</seg>
+ </seglistitem><seglistitem>
+ <seg>
+ <tag class="element">optional</tag>
+ </seg>
+ <seg>Specifies that the content is optional information. It is typically used in command
+ synopsis.</seg>
+ </seglistitem><seglistitem>
+ <seg>
+ <tag class="element">replaceable</tag>
+ </seg>
+ <seg>Specifies that the content represents a value that will be replaced by the user in
+ using the product.</seg>
+ </seglistitem></segmentedlist>
+ </section>
+ <section>
+ <title>GUI Elements</title>
+ <para>The following are DocBook elements used in documenting a GUI:</para>
+ <segmentedlist>
+ <segtitle>Element</segtitle>
+ <segtitle>Description</segtitle>
+ <seglistitem>
+ <seg>
+ <tag class="element">accel</tag>
+ </seg>
+ <seg>Specifies that the content is a keyboard shortcut.</seg>
+ </seglistitem><seglistitem>
+ <seg>
+ <tag class="element">guibutton</tag>
+ </seg>
+ <seg>Specifies that the content is the label on a GUI button.</seg>
+ </seglistitem><seglistitem>
+ <seg>
+ <tag class="element">guilabel</tag>
+ </seg>
+ <seg>Specifies that the content is a label on a GUI element other than a button.</seg>
+ </seglistitem><seglistitem>
+ <seg>
+ <tag class="element">guimenu</tag>
+ </seg>
+ <seg>Specifies that the content is the name of a menu.</seg>
+ </seglistitem><seglistitem>
+ <seg>
+ <tag class="element">guimenuitem</tag>
+ </seg>
+ <seg>Specifies that the content is a selectable item on a menu.</seg>
+ </seglistitem><seglistitem>
+ <seg>
+ <tag class="element">guisubmenu</tag>
+ </seg>
+ <seg>Specifies that the content is the name of a sub-menu.</seg>
+ </seglistitem><seglistitem>
+ <seg>
+ <tag class="element">mousebutton</tag>
+ </seg>
+ <seg>Specifies that the content is the name of a mouse button.</seg>
+ </seglistitem></segmentedlist>
+ </section>
+</chapter>
Added: trunk/docs/1.6/glossary.xml
===================================================================
--- trunk/docs/1.6/glossary.xml (rev 0)
+++ trunk/docs/1.6/glossary.xml 2009-09-09 20:31:19 UTC (rev 14000)
@@ -0,0 +1,18 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<glossary version="5.0" xmlns="http://docbook.org/ns/docbook"
+ xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xi="http://www.w3.org/2001/XInclude"
+ role="auto" xml:id="glossary">
+
+ <para>The recommendation here is to build a glossary database (Chapter 17 of Stayton's
+ book) that is writable by any author or editor with commit privileges. Authors can
+ populate it with whatever terms they like, using a simple rule for id
+ disambiguation (such as gloss.term, where gloss is constant and term is the term
+ itself). If we need to disambiguate two forms of the same term, we can add a
+ suffix. The build process described in Stayton's book builds a glossary for each
+ document based on the terms used in that document.</para>
+
+ <para>For authors without commit privileges, this becomes a little more complex. One
+ thought would be to have authors submit their glossary entries in a separate file,
+ which editor-committers can then upload.</para>
+
+</glossary>
Added: trunk/docs/1.6/indexterms.xml
===================================================================
--- trunk/docs/1.6/indexterms.xml (rev 0)
+++ trunk/docs/1.6/indexterms.xml 2009-09-09 20:31:19 UTC (rev 14000)
@@ -0,0 +1,74 @@
+<?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="indexterms">
+ <title>Marking Terms for Dynamic Index Creation</title>
+ <info>
+ <abstract>
+ <para>This chapter describes how to mark up terms for generating a dynamic index of Evergreen
+ documentation. </para>
+ </abstract>
+ </info>
+ <section>
+ <title>Marking Terms for Index Entry</title>
+ <simplesect>
+ <title>Overview</title>
+ <para>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. </para>
+ <para>Authors are not required to mark up index elements; editors will complete any index
+ tagging not accomplished at the authoring stage.</para>
+ </simplesect>
+ <simplesect>
+ <title>Specifying index entries</title>
+ <para>Index entries are specified by adding <tag class="element">indexterm</tag> elements in
+ the text of the book. An index entry must contain one <tag class="element">primary</tag>
+ element. The value of the <tag class="element">primary</tag> element is the top-level entry
+ that will appear in the generated index.</para>
+ <para>In addition, an <tag class="element">indexterm</tag> element can contain the following
+ optional elements:</para>
+ <itemizedlist>
+ <listitem>
+ <para>One <tag class="element">secondary</tag> element that specifies a second level entry
+ in the generated index.</para>
+ </listitem>
+ <listitem>
+ <para>One <tag class="element">tertiary</tag> element that specifies a third level index
+ entry.</para>
+ </listitem>
+ <listitem>
+ <para>One <tag class="element">see</tag> element that specifies an alternate entry to
+ which the reader is redirected.</para>
+ </listitem>
+ <listitem>
+ <para>One <tag class="element">seealso</tag> element that specifies an additional entry
+ with relevant information.</para>
+ </listitem>
+ </itemizedlist>
+ <para>If you want to mark an <tag class="element">indexterm</tag> and you aren't sure what
+ elements to assign it, use the <tag>primary</tag> element.</para>
+ </simplesect>
+ <simplesect>
+ <title>Example: Marking a Primary Index Term</title>
+ <para>The Open Scalable Request Framework (<indexterm>
+ <primary>OpenSRF</primary>
+ </indexterm>, 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.</para>
+ </simplesect>
+ <simplesect>
+ <title>Example: Marking a Secondary Index Term</title>
+ <para> Indexed-field weighting, which controls relevance ranking in Evergreen, is configured
+ in the 'weight' column of the <indexterm>
+ <primary>Evergreen Tables</primary>
+ <secondary>config.metabib_field</secondary>
+ </indexterm> table of the Evergreen database.</para>
+ </simplesect>
+ <simplesect>
+ <title>Specifying where the Index is Generated</title>
+ <para>In order for the index to auto-generate, every Evergreen book has an <tag
+ class="emptytag">index</tag> element. The index will be generated in the position that
+ corresponds to the element's location in the book file. The <tag class="emptytag"
+ >index</tag> element follows all other chapters and appendices.</para>
+ </simplesect>
+ </section>
+</chapter>
Added: trunk/docs/1.6/links.xml
===================================================================
--- trunk/docs/1.6/links.xml (rev 0)
+++ trunk/docs/1.6/links.xml 2009-09-09 20:31:19 UTC (rev 14000)
@@ -0,0 +1,489 @@
+<?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="links">
+ <title>Cross-References and Links</title>
+ <info>
+ <abstract>
+ <para>DocBook has three linking elements that are used to create internal cross-references,
+ external cross-references, and links to locations on the Web. Some of the linking elements
+ perform multiple tasks and some have overlapping functionality. Authors choose the proper
+ element based on the specifics of the task at hand. A portion of the link text is generated
+ by the publication system and the author has some control over it.</para>
+ </abstract>
+ </info>
+ <section xml:id="linksInternal">
+ <title>Cross-References within the Same File or Book</title>
+ <simplesect>
+ <title>Overview</title>
+ <para>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:</para>
+ <itemizedlist>
+ <listitem>
+ <para><link linkend="xref">
+ <tag class="element">xref</tag>
+ </link>-generates a cross-reference whose target is in the same file.</para>
+ </listitem>
+ <listitem>
+ <para><link linkend="link">
+ <tag class="element">link</tag>
+ </link>-generates a cress-reference whose target is in the same file but allows the
+ author to provide the link text.</para>
+ </listitem>
+ <listitem>
+ <para><link linkend="olinkInternal">
+ <tag class="element">olink</tag>
+ </link>-generates a cross-reference whose target is in a different file. The <tag
+ class="element">olink</tag> element allows the author to use either generated link
+ text or author supplied link text.</para>
+ </listitem>
+ </itemizedlist>
+ </simplesect>
+ <simplesect xml:id="xref">
+ <title>Inserting a cross-reference in the same file, using generated text</title>
+ <indexterm>
+ <primary>xref element</primary>
+ </indexterm>
+ <indexterm>
+ <primary>linking</primary>
+ <secondary>using generated text</secondary>
+ </indexterm>
+ <indexterm>
+ <primary>cross referencing</primary>
+ </indexterm>
+ <para>The <tag class="element">xref</tag> element creates a link to an element in the same
+ file. It requires the use of the <tag class="attribute">linkend</tag> attribute to identify
+ the target element.</para>
+ <para>The <tag class="element">xref</tag> element does not have any content. The link text is
+ generated based on the contents of the target element. <anchor xml:id="xreftextgen"/>If the
+ target element has a <tag class="element">title</tag> element, such as a <tag
+ class="element">section</tag> element or an <tag class="element">example</tag> element,
+ the contents of the <tag class="element">title</tag> element is used as the link text.
+ Alternatively, the value of the target element's <tag class="attribute">xreflabel</tag>
+ attribute will be used as the link text.</para>
+ <important>
+ <para>If the referenced element has both a <tag class="element">title</tag> element and a
+ value specified in its <tag class="attribute">xreflabel</tag> attribute, the value of the
+ <tag class="attribute">xreflabel</tag> attribute is used.</para>
+ </important>
+ <tip>
+ <para>The default generated text for a PDF cross-reference includes the page number of the
+ target. The generated text can be changed using the <tag class="attribute">xrefstyle</tag>
+ attribute. See <xref linkend="linkStyling"/>.</para>
+ </tip>
+ <para><xref linkend="xrefexample1"/> shows an example of a cross reference whose text is
+ derived from the <tag class="element">title</tag> element of the referenced element. The
+ resulting link text would be <literal>the section called "Coco Crisp"
+ shows</literal>.</para>
+ <example xml:id="xrefexample1">
+ <title>Cross Reference to a Titled Element</title>
+ <programlisting><para><emphasis role="bold"><xref linkend="topsect" /></emphasis> shows ...</para>
+...
+<section id="topsect">
+ <title>Coco Crisp</title>
+...
+</section></programlisting>
+ </example>
+ <para><xref linkend="xrefexample2"/> shows an example of a cross reference whose text is
+ derived from the <tag class="attribute">xreflabel</tag> attribute of the targeted element.
+ The resulting link text would be <literal>outfielder shows</literal>.</para>
+ <example xml:id="xrefexample2">
+ <title>Cross Reference to an Element with an xreflabel</title>
+ <programlisting><para><xref linkend="example1" /> shows ...</para>
+...
+<example id="example1" xreflabel="outfielder">
+ <title>Catching Coco Crisp</title>
+ ...
+</example></programlisting>
+ </example>
+ </simplesect>
+ <simplesect xml:id="link">
+ <title>Inserting link using author supplied text</title>
+ <indexterm>
+ <primary>link element</primary>
+ </indexterm>
+ <indexterm>
+ <primary>linking</primary>
+ <secondary>using author text</secondary>
+ </indexterm>
+ <para>Internal links are created using the <tag class="element">link</tag> element. The <tag
+ class="element">link</tag> element has one required attribute, <tag class="attribute"
+ >linkend</tag>, whose value is the id of element anchoring the link. The anchoring element
+ can be any valid DocBook element that uses the <tag class="attribute">xml:id</tag>
+ attribute. For example if you wanted to create a link to an image in your document, you
+ would use the id of the <tag class="element">figure</tag> element that wraps the
+ image.</para>
+ <para>The text used for the link is the content of the <tag class="element">link</tag>
+ element. <xref linkend="linkexample"/> shows the mark up for this <link linkend="link">link
+ to the top</link> of this section.</para>
+ <example xml:id="linkexample">
+ <title>Example of an Internal Link</title>
+ <programlisting><section xml:id="link">
+ ...
+ <para>... this <emphasis role="bold"><link linkend="link">link to the top</link></emphasis> of ...</para>
+ ...
+</section></programlisting>
+ </example>
+ <tip>
+ <para>The default generated text for a PDF link includes the page number of the target. The
+ generated text can be changed using the <tag class="attribute">xrefstyle</tag> attribute.
+ See <xref linkend="linkStyling"/>.</para>
+ </tip>
+ </simplesect>
+ <simplesect xml:id="olinkInternal">
+ <title>Inserting a link to a target element in a different source file</title>
+ <indexterm>
+ <primary>olink element</primary>
+ </indexterm>
+ <indexterm>
+ <primary>linking</primary>
+ <secondary>external source file</secondary>
+ </indexterm>
+ <para>The <tag class="element">olink</tag> element facilitates cross-linking among DocBook
+ files (just as <tag class="element">xref</tag> and <tag class="element">link</tag> elements
+ enable linking within files).</para>
+ <indexterm>
+ <primary>olink element</primary>
+ </indexterm>
+ <indexterm>
+ <primary>linking</primary>
+ <secondary>across books</secondary>
+ </indexterm>
+ <indexterm>
+ <primary>site map</primary>
+ </indexterm>
+ <para>You create a link to another book using the <tag class="element">olink</tag>
+ element.</para>
+ <para>Two attributes associated with the <tag class="element">olink</tag> element are used to
+ specify the link target:</para>
+ <variablelist>
+ <varlistentry>
+ <term>
+ <tag class="attribute">targetptr</tag>
+ </term>
+ <listitem>
+ <para>The value of the link target's <tag class="attribute">xml:id</tag>
+ attribute</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <tag class="attribute">targetdoc</tag>
+ </term>
+ <listitem>
+ <para>The value of the <tag class="attribute">targetdoc</tag> attribute of the target
+ document. </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ <para>For simplicity's sake, use the document's xml:id attribute as the document identifier;
+ it will then function as both the <tag class="element">targetdoc</tag> and <tag
+ class="element">targetptr</tag> element. So the <tag class="element">olink</tag> reference
+ for this file would be filenames, as in this example:</para>
+ <para>See the chapter on <olink targetdoc="lists" targetpr="lists">creating
+ lists</olink> </para>
+ </simplesect>
+ </section>
+ <section>
+ <title>Cross-References to Other Books</title>
+ <simplesect>
+ <title>Overview</title>
+ <para>Authors can create cross-references to a different book in a set using the <tag
+ class="element">olink</tag> 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.</para>
+ </simplesect>
+ <simplesect>
+ <title>Specifying the link text</title>
+ <para>DocBook provides two methods for specifying link text for <tag class="element"
+ >olink</tag> elements: author-supplied and auto-generated. Evergreen documentation uses
+ author-supplied link text.</para>
+ <para>Creating an olink between books</para>
+ <para>adfasfsda</para>
+ </simplesect>
+ <simplesect>
+ <title>Setting up the olink site map</title>
+ <indexterm>
+ <primary>site map</primary>
+ </indexterm>
+ <indexterm>
+ <primary>linking</primary>
+ <secondary>external XML source</secondary>
+ <tertiary>making a site map</tertiary>
+ </indexterm>
+ <para>
+ <note>
+ <para>Most Evergreen documentation authors do not have to worry about creating or
+ maintaining the site map for olinks in Evergreen documentation. This is set up in
+ advance by the same team that manages the file commits.</para>
+ </note>
+ </para>
+ <para>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.</para>
+ <para>The site map for a documentation set is placed at the root of the documentation source
+ tree and is always called <filename>site.xml</filename>. <xref linkend="LinksCalloutExample"
+ /> shows a sample site map.</para>
+ <example xml:id="LinksCalloutExample" pgwide="1">
+ <?dbfo pgwide="1"?>
+ <title>Document Set Site Map</title>
+ <programlisting language="xml"><?xml version="1.0" encoding="utf-8"?> <co linkends="sitemapptr0" xml:id="sitemapco0"/>
+<targetset><co linkends="sitemapptr3" xml:id="sitemapco3"/>
+ <targetsetinfo><co linkends="sitemapptr4" xml:id="sitemapco4"/>
+ <title>Library Title</tite> <co linkends="sitemapptr41" xml:id="sitemapco41"/>
+ <desc>Site map for the Evergreen XML Style Guide</desc> <co linkends="sitemapptr42" xml:id="sitemapco42"/>
+ </targetsetinfo>
+ <sitemap><co linkends="sitemapptr5" xml:id="sitemapco5"/>
+ <dir name="docs_rls_inferno"><co linkends="sitemapptr6" xml:id="sitemapco6"/>
+ <dir name="fluff"><co linkends="sitemapptr75" xml:id="sitemapco75"/>
+ <dir name="overview"><co linkends="sitemapptr7" xml:id="sitemapco7"/>
+ <document targetdoc="InfernoOverview"> <co linkends="sitemapptr8" xml:id="sitemapco8"/>
+ <xi:include href="overview/target.db" xmlns:xi="http://www.w3.org/2001/XInclude" /> <co linkends="sitemapptr9" xml:id="sitemapco9"/>
+ </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></programlisting>
+ </example>
+ <calloutlist>
+ <title>Elements of the Site Map</title>
+ <callout arearefs="sitemapco0" xml:id="sitemapptr0">
+ <para>The site map should always be encoded as UTF-8. This ensures that all of the
+ generated target data has the same encodings regardless of the encodings used by the XML
+ source files.</para>
+ </callout>
+ <callout arearefs="sitemapco3" xml:id="sitemapptr3">
+ <para>The <tag class="element">targetset</tag> element is the root of the site map.</para>
+ </callout>
+ <callout arearefs="sitemapco4" xml:id="sitemapptr4">
+ <para>The <tag class="element">targetsetinfo</tag> element allows you to provide a
+ description for the document set or any other information that is relevant to the site
+ map.</para>
+ </callout>
+ <callout arearefs="sitemapco41" xml:id="sitemapptr41">
+ <para>The <tag class="element">title</tag> element allows you to provide a title to be
+ used on the generated index page.</para>
+ </callout>
+ <callout arearefs="sitemapco42" xml:id="sitemapptr42">
+ <para>The <tag class="element">desc</tag> element allows you to provide a description for
+ the document set that will appear at the top of the generated index page.</para>
+ </callout>
+ <callout arearefs="sitemapco5" xml:id="sitemapptr5">
+ <para>The <tag class="element">sitemap</tag> element contains the directory layout of the
+ output files.</para>
+ </callout>
+ <callout arearefs="sitemapco6" xml:id="sitemapptr6">
+ <para>The name of the top-level directory is not important in the generation of the target
+ databases for the links. The links are generated relative to the top-level
+ directory.</para>
+ </callout>
+ <callout arearefs="sitemapco75" xml:id="sitemapptr75">
+ <para>This is a directory that only contains other directories.</para>
+ </callout>
+ <callout arearefs="sitemapco7" xml:id="sitemapptr7">
+ <para>This directory holds a generated book.</para>
+ </callout>
+ <callout arearefs="sitemapco8" xml:id="sitemapptr8">
+ <para>The <tag class="element">document</tag> element's <tag class="attribute"
+ >targetdoc</tag> attribute specifies the identifier used in the <tag class="element"
+ >olink</tag> element's <tag class="attribute">targetdoc</tag> attribute when linking
+ to targets in the document.</para>
+ </callout>
+ <callout arearefs="sitemapco9" xml:id="sitemapptr9">
+ <para>The target database is included in the site map using an <tag class="element"
+ >xi:include</tag> element. The path for each book's target database should be
+ <filename><replaceable>book_src_dir</replaceable>/target.db</filename>.</para>
+ </callout>
+ </calloutlist>
+ </simplesect>
+ </section>
+ <section xml:id="ulink">
+ <title>Linking to Web Pages</title>
+ <simplesect>
+ <title>Creating the link</title>
+ <indexterm>
+ <primary>link element</primary>
+ <secondary>xl:href attribute</secondary>
+ </indexterm>
+ <indexterm>
+ <primary>linking</primary>
+ <secondary>Web pages</secondary>
+ </indexterm>
+ <para>Links to Web pages are created using the <tag class="element">link</tag> element. You
+ identify the target Web site using the <tag class="attribute">xl:href</tag> attribute. The
+ value must be a valid URL.</para>
+ </simplesect>
+ <simplesect>
+ <title>Specifying the link text</title>
+ <para>The link text can be specified in one of two ways. You can specified the desired link
+ text as the value of the <tag class="element">link</tag> element. If you leave the <tag
+ class="element">link</tag> element empty, the value of the <tag class="attribute"
+ >xl:href</tag> attribute will be used as the link text.</para>
+ <tip>
+ <para>The PDF will always show the URL in the generated text.</para>
+ </tip>
+ </simplesect>
+ <simplesect>
+ <title>Examples</title>
+ <para><xref linkend="ulinkexample1"/> shows an example of an external link with supplied link
+ text.</para>
+ <example xml:id="ulinkexample1">
+ <title>External Link with Link Text</title>
+ <programlisting language="xml"><link xl:href="http://www.cxf.org">CXF Home</link></programlisting>
+ </example>
+ <para><xref linkend="ulinkexample2"/> shows an example of an external link that uses the
+ default link text.</para>
+ <example xml:id="ulinkexample2">
+ <title>External Link Using Default Link Text</title>
+ <programlisting><link xl:href="http://www.cxf.org" /></programlisting>
+ </example>
+ </simplesect>
+ </section>
+ <section xml:id="linkAnchor">
+ <title>Creating Anchor Points</title>
+ <indexterm>
+ <primary>anchor element</primary>
+ </indexterm>
+ <indexterm>
+ <primary>linking</primary>
+ <secondary>creating a target</secondary>
+ </indexterm>
+ <simplesect>
+ <title>Overview</title>
+ <para>Authors can create anchor points in your text using the <tag class="element"
+ >anchor</tag> element. The <tag class="element">anchor</tag> 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.</para>
+ </simplesect>
+ <simplesect>
+ <title>Marking an anchor point</title>
+ <para>The <tag class="element">anchor</tag> element is empty. It has a required <tag
+ class="attribute">xml:id</tag> attribute that is the ID used for linking to the anchor. In
+ addition, it can take a <tag class="attribute">xreflabel</tag> attribute that provides the
+ generated text for an <tag class="element">xref</tag> element or an empty <tag
+ class="element">olink</tag> element.</para>
+ </simplesect>
+ <simplesect>
+ <title>Example</title>
+ <para><xref linkend="anchorEx"/> shows the mark-up for placing an anchor in a document.</para>
+ <example xml:id="anchorEx">
+ <title>Creating an Anchor</title>
+ <programlisting language="docbook"><section ...>
+ ...
+ <emphasis role="bold"><anchor xml:id="anchorID" xreflabel="here" /></emphasis>
+ ...
+ <para><xref linkend="anchorID" /> is a link to an anchor.</para>
+ ...
+</section></programlisting>
+ <para>The generated text from the mark-up in <xref linkend="anchorEx"/> is <literal>here is
+ a to an anchor.</literal> and the <literal>here</literal> would be a link back to the
+ anchor.</para>
+ </example>
+ </simplesect>
+ </section>
+ <section xml:id="linkStyling">
+ <title>Controlling the Generated Link Text</title>
+ <simplesect>
+ <title>Overview</title>
+ <para>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
+ <tag class="attribute">xrefstyle</tag> attribute.</para>
+ </simplesect>
+ <simplesect>
+ <title>The xrefstyle attribute</title>
+ <para>The <tag class="attribute">xrefstyle</tag> attribute's value is a string pattern. All of
+ the patterns that can be used are described in Bob Stayton's <citetitle
+ xl:href="http://sagehill.net/docbookxsl/CustomXrefs.html#Xrefstyle">DocBook XSL: The
+ Complete Guide</citetitle>.</para>
+ <para>The pattern most commonly used in the Evergreen authoring system is the
+ <literal>select</literal> pattern. This pattern is specified using the syntax shown in
+ <xref linkend="xrefstyleSelectEx"/>.</para>
+ <example xml:id="xrefstyleSelectEx">
+ <title>Syntax for the Select Pattern</title>
+ <programlisting language="docbook"><xref ... <emphasis role="bold">xrefstyle="select: <replaceable>opt1</replaceable> <replaceable>opt2</replaceable> ... <replaceable>optN</replaceable>"</emphasis> /></programlisting>
+ </example>
+ <para>The values for <replaceable>optN</replaceable> select the text generated for the link
+ text.</para>
+ </simplesect>
+ <simplesect>
+ <title>Turning off page numbers</title>
+ <para>Authors can turn off the generation of page numbers in the PDF using the
+ <literal>nopage</literal> 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 <tag class="element">link</tag> elements
+ and <tag class="element">olink</tag> elements that provide a value for the link text, the
+ <literal>nopage</literal> option produces a the supplied link text without a page number.
+ For <tag class="element">xref</tag> elements and <tag class="element">olink</tag> elements
+ that rely on the publication system to generate the link text, the <literal>nopage</literal>
+ is insufficient to create a valid link. The author will need to provide either the <link
+ linkend="linksLabel" xrefstyle="select: nopage">label</link> option to the pattern or the
+ <link linkend="linksTitle" xrefstyle="select: nopage">title</link> option to the selection
+ pattern.</para>
+ <para><xref linkend="linkexample2"/> shows a <tag class="element">link</tag> element that
+ would not generate a page number.</para>
+ <example xml:id="linkexample2" pgwide="1">
+ <?dbfo pgwide="1"?>
+ <title>Example of an Internal Link with no Page Number</title>
+ <programlisting><section xml:id="link">
+ ...
+ <para>... this <emphasis role="bold"><link linkend="link" xrefstyle="select: nopage">link to the top</link></emphasis> of ...</para>
+ ...
+</section></programlisting>
+ </example>
+ </simplesect>
+ <simplesect xml:id="linksLabel">
+ <title>Using the target's label</title>
+ <para>Figures, tables, and examples have labels that are used to generate the link text. To
+ ensure that an <tag class="element">xref</tag> element or an <tag class="element"
+ >olink</tag> 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
+ <literal>label</literal> option to the selection pattern.</para>
+ <para><xref linkend="linkexample3"/> shows an <tag class="element">xref</tag> element that
+ generates a label without a page number.</para>
+ <example xml:id="linkexample3" pgwide="1">
+ <?dbfo pgwide="1"?>
+ <title>A Cross-Reference to a Figure with no Page Number</title>
+ <programlisting><figure xml:id="link">
+ ...
+</figure>
+<para><emphasis role="bold"><xref linkend="link" xrefstyle="select: nopage label" /></emphasis> shows ...</para>
+...
+</programlisting>
+ </example>
+ </simplesect>
+ <simplesect xml:id="linksTitle">
+ <title>Using the target's title</title>
+ <para>Chapters, sections, and blocks have titles that are used to generate the link text. To
+ ensure that an <tag class="element">xref</tag> element or an <tag class="element"
+ >olink</tag> 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
+ <literal>title</literal> option to the selection pattern.</para>
+ <para><xref linkend="linkexample4"/> shows an <tag class="element">xref</tag> element that
+ generates a title without a page number.</para>
+ <example xml:id="linkexample4" pgwide="1">
+ <?dbfo pgwide="1"?>
+ <title>A Cross-Reference to a Block with no Page Number</title>
+ <programlisting><simplesect xml:id="link">
+ ...
+</simplesect>
+...
+<para>As discussed in <emphasis role="bold"><olink targetptr="link" xrefstyle="select: nopage label" /></emphasis> ...</para>
+...
+</programlisting>
+ </example>
+ </simplesect>
+ </section>
+</chapter>
Added: trunk/docs/1.6/lists.xml
===================================================================
--- trunk/docs/1.6/lists.xml (rev 0)
+++ trunk/docs/1.6/lists.xml 2009-09-09 20:31:19 UTC (rev 14000)
@@ -0,0 +1,400 @@
+<?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="lists">
+ <title>Lists</title>
+ <info>
+ <abstract>
+ <para>DocBook has several list structures to choose from. It has the standard numbered lists
+ and bulleted lists. In addition it provides specialized types of lists for glossaries and
+ other occasions. All of these lists may be used in Evergreen documentation. </para>
+ </abstract>
+ </info>
+ <section>
+ <title>Simple Lists</title>
+ <simplesect>
+ <title>Overview</title>
+ <para>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.</para>
+ </simplesect>
+ <simplesect>
+ <title>Specifying a simple list</title>
+ <para>A simple list is specified by a <tag class="element">simplelist</tag> element. <tag
+ class="element">simplelist</tag> has two optional attributes:</para>
+ <table pgwide="1">
+ <title>Attributes of the <tag class="element">simplelist</tag> Element</title>
+ <tgroup cols="3">
+ <thead>
+ <row>
+ <entry>Attribute</entry>
+ <entry>Values</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>
+ <tag class="attribute">type</tag>
+ </entry>
+ <entry><tag class="attvalue">inline</tag>, <tag class="attvalue">horiz</tag>, <tag
+ class="attvalue">vert</tag> (default)</entry>
+ <entry>Specifies how the items in the list are to be listed.</entry>
+ </row>
+ <row>
+ <entry>
+ <tag class="attribute">columns</tag>
+ </entry>
+ <entry>>=1</entry>
+ <entry>Specifies the number of columns to use when <tag class="attribute">type</tag>
+ is set to <tag class="attvalue">horiz</tag> or <tag class="attvalue"
+ >vert</tag>.</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ <para>The elements of a simple list are specified using a <tag class="element">member</tag>
+ element. The contents of each <tag class="element">member</tag> element can only contain
+ character data and in-line elements.</para>
+ </simplesect>
+ <simplesect>
+ <title>Example</title>
+ <para><xref linkend="simpmarkup"/> shows the markup for a simple list.</para>
+ <example xml:id="simpmarkup" xreflabel="Example 1">
+ <title>Simple List Markup</title>
+ <programlisting><simplelist>
+ <member>Swedish Fish</member>
+ <member>Mike & Ike</member>
+ <member>Sour Patch Kids</member>
+ <member>Gummy Bears</member>
+</simplelist></programlisting>
+ </example>
+ </simplesect>
+ </section>
+ <section>
+ <title>Itemized Lists</title>
+ <simplesect>
+ <title>Overview</title>
+ <para>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 <tag
+ class="element">ul</tag> tag in HTML.</para>
+ </simplesect>
+ <simplesect>
+ <title>Specifying an itemized list</title>
+ <para>An itemized list is specified by an <tag class="element">itemizedlist</tag> element. You
+ can specify an <tag class="attribute">xml:id</tag> attribute for itemized lists. If the list
+ is going to referenced by an <tag class="element">xref</tag> element, you should also
+ specify a value for the <tag class="attribute">xreflabel</tag> attribute.</para>
+ <para>Each item in an itemized list is specified by a <tag class="element">listitem</tag>
+ element. The <tag class="element">listitem</tag> element is a wrapper element and can
+ contain any container elements such as a <tag class="element">para</tag> element. All
+ content within a <tag class="element">listitem</tag> element will be indented to the same
+ level. You can also specify sub-lists within a <tag class="element">listitem</tag>
+ element.</para>
+ </simplesect>
+ <simplesect>
+ <title>Example</title>
+ <para><xref linkend="itemmarkup"/> shows the markup for an itemized list.</para>
+ <example xml:id="itemmarkup" xreflabel="Example 2">
+ <title>Itemized List Markup</title>
+ <programlisting><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></programlisting>
+ </example>
+ </simplesect>
+ </section>
+ <section>
+ <title>Ordered List</title>
+ <simplesect>
+ <title>Overview</title>
+ <para>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 <tag
+ class="element">ol</tag> tag in HTML.</para>
+ </simplesect>
+ <simplesect>
+ <title>Specifying an ordered list</title>
+ <para>Ordered lists are specified by an <tag class="element">orderedlist</tag> element. In
+ addition to the <tag class="attribute">xml:id</tag> attribute and <tag class="attribute"
+ >xreflabel</tag> attribute, <tag class="element">orderedlist</tag> elements have three
+ optional elements.</para>
+ <table pgwide="1">
+ <title>Attributes of the <tag class="element">orderedlist</tag> Element</title>
+ <tgroup cols="3">
+ <thead>
+ <row>
+ <entry>Attribute</entry>
+ <entry>Values</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>
+ <tag class="attribute">continuation</tag>
+ </entry>
+ <entry><tag class="attvalue">continues</tag>, <tag class="attvalue">restarts</tag>
+ (default)</entry>
+ <entry>Specifies whether the item numbering should restart at one or continue from the
+ previous ordered list.</entry>
+ </row>
+ <row>
+ <entry>
+ <tag class="attribute">inheritnum</tag>
+ </entry>
+ <entry><tag class="attvalue">inherit</tag>, <tag class="attvalue">ignore</tag>
+ (default)</entry>
+ <entry>Valid only for nested lists. Specifies whether the items in the nested list
+ contain a reference to the item of the parent list.</entry>
+ </row>
+ <row>
+ <entry>
+ <tag class="attribute">numeration</tag>
+ </entry>
+ <entry><tag class="attvalue">arabic</tag>, <tag class="attvalue">loweralpha</tag>,
+ <tag class="attvalue">lowerroman</tag>, <tag class="attvalue">upperalpha</tag>,
+ <tag class="attvalue">upperroman</tag></entry>
+ <entry>Specifies the numbering style to use for the list.</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ <para>Items in an ordered list are specified using a <tag class="element">listitem</tag>
+ element. The <tag class="element">listitem</tag> element is a wrapper element and can
+ contain any container elements such as a <tag class="element">para</tag> element. All
+ content within a <tag class="element">listitem</tag> element will be indented to the same
+ level. You can also specify sub-lists within a <tag class="element">listitem</tag>
+ element.</para>
+ </simplesect>
+ </section>
+ <section xml:id="VariableLists">
+ <title>Variable Lists</title>
+ <simplesect>
+ <title>Overview</title>
+ <para>A variable list looks similar to a glossary. It consists of a word, or phrase, and some
+ text describing the word, or phrase. <xref linkend="varexample"
+ xrefstyle="select: title nopage"/> shows a variable list.</para>
+ <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>
+ </simplesect>
+ <simplesect>
+ <title>Specifying the list</title>
+ <para>Variable lists are specified by a <tag class="element">variablelist</tag> element. The
+ <tag class="element">variablelist</tag> element can have the optional <tag
+ class="attribute">xml:id</tag> attribute and <tag class="attribute">xreflabel</tag>
+ attribute specified. You can also supply a title for a variable list by adding a <tag
+ class="element">title</tag> element as the <tag class="element">variablelist</tag>
+ element's first child.</para>
+ <para>The items in a variable list are specified using a <tag class="element"
+ >varlistentry</tag> element. The <tag class="element">varlistentry</tag> element has two
+ children elements that specify the contents of the item:</para>
+ <itemizedlist>
+ <listitem>
+ <para><tag class="element">term</tag></para>
+ </listitem>
+ <listitem>
+ <para><tag class="element">listitem</tag></para>
+ </listitem>
+ </itemizedlist>
+ </simplesect>
+ <simplesect>
+ <title>Specifying terms</title>
+ <para>You can specify one or more <tag class="element">term</tag> elements in a <tag
+ class="element">varlistentry</tag> element. Each <tag class="element">term</tag> element
+ can contain text and in-line markup elements. Each <tag class="element">term</tag> element
+ should contain a single term or phrase that the list item describes.</para>
+ </simplesect>
+ <simplesect>
+ <title>Describing a term</title>
+ <para>You describe the term, or terms, defined by the <tag class="element">term</tag> elements
+ using a single <tag class="element">listitem</tag> element. The <tag class="element"
+ >listitem</tag> element is a wrapper element and can contain any container elements such
+ as a <tag class="element">para</tag> element. All content within a <tag class="element"
+ >listitem</tag> element will be indented to the same level. You can also specify sub-lists
+ within a <tag class="element">listitem</tag> element.</para>
+ </simplesect>
+ <simplesect>
+ <title>Example</title>
+ <para><xref linkend="varmarkup"/> shows the markup representing <xref linkend="varexample"
+ />.</para>
+ <example xml:id="varmarkup">
+ <title>Variable List Markup</title>
+ <programlisting><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></programlisting>
+ </example>
+ </simplesect>
+ </section>
+ <section xml:id="GlossList">
+ <title>Glossary Lists</title>
+ <simplesect>
+ <title>Overview</title>
+ <para>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. <xref linkend="glossexample" xrefstyle="select: nopage label"/> shows a use
+ of a glossary list.</para>
+ <glosslist xml:id="glossexample" xreflabel="List of Terms">
+ <title>List of Terms</title>
+ <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>
+ </simplesect>
+ <simplesect>
+ <title>Specifying the list</title>
+ <para>A glossary list is specified using the <tag class="element">glosslist</tag> element. If
+ you want to refer back to a glossary list, you can provide values for the <tag
+ class="attribute">xml:id</tag> attribute and the <tag class="attribute">xreflabel</tag>
+ attribute. Like variable lists, glossary lists can have titles.</para>
+ <para>The entries in a glossary list are specified using a <tag class="element"
+ >glossentry</tag> element. The <tag class="element">glossentry</tag> element typically has
+ two children: <tag class="element">glossterm</tag> and <tag class="element">glossdef</tag>.
+ You can also use the <tag class="element">glosssee</tag> element to xref with other
+ definitions.</para>
+ </simplesect>
+ <simplesect>
+ <title>Specifying a term</title>
+ <para>A <tag class="element">glossentry</tag> element can have only one <tag class="element"
+ >glossterm</tag> 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 <tag
+ class="element">glossentry</tag> element's <tag class="attribute">xml:id</tag>
+ attribute.</para>
+ <note>
+ <para>The <tag class="element">glossterm</tag> element can also be used in text entries to
+ refer to terms defined in a glossary entry. When used in this manner, you supply a value
+ for the <tag class="attribute">linkend</tag> attribute.</para>
+ </note>
+ </simplesect>
+ <simplesect>
+ <title>Defining a term</title>
+ <para>You define a term using either one or more <tag class="element">glossdef</tag> elements
+ or a <tag class="element">glosssee</tag> element. The <tag class="element">glossdef</tag>
+ element is a content element that contains markup specifying a definition. If you use more
+ than one <tag class="element">glossdef</tag> element, they are treated as separate
+ definitions for the same term.</para>
+ <para>The <tag class="element">glosssee</tag> element redirects the reader to a term with the
+ same meaning. It acts like a "See" entry in a dictionary. It has one attribute,
+ <tag class="attribute">otherterm</tag>, whose value is the id of the term to which the
+ reader is redirected.</para>
+ </simplesect>
+ <simplesect>
+ <title>Example</title>
+ <para><xref linkend="glossmarkup"/> shows the markup for <xref linkend="glossexample"
+ xrefstyle="select: nopage label"/>.</para>
+ <example xml:id="glossmarkup" xreflabel="Example 4" pgwide="1">
+ <?dbfo pgwide="1"?>
+ <title>Glossary List Markup</title>
+ <programlisting><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></programlisting>
+ </example>
+ </simplesect>
+ </section>
+</chapter>
Added: trunk/docs/1.6/overview.xml
===================================================================
--- trunk/docs/1.6/overview.xml (rev 0)
+++ trunk/docs/1.6/overview.xml 2009-09-09 20:31:19 UTC (rev 14000)
@@ -0,0 +1,149 @@
+<?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="overview">
+ <title>Evergreen and DocBook</title>
+ <section>
+ <title>About our approach</title>
+ <simplesect>
+ <title>Overview</title>
+ <para>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. </para>
+ <para>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. </para>
+ </simplesect>
+ <simplesect>
+ <title>History</title>
+ <para>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. </para>
+ <para>The rationales for this approach were as follows:</para>
+ <itemizedlist>
+ <listitem>
+ <para>The Evergreen project needed to move past the gaps and duplicated efforts of having
+ documentation written within local library systems and leverage its size and skills
+ toward a common goal.</para>
+ </listitem>
+ <listitem>
+ <para>The commitment to single-source documentation means that core Evergreen
+ documentation would be could be repurposed as necessary into many different formats --
+ one core set of files, many outputs.</para>
+ </listitem>
+ <listitem>
+ <para>XML provides structure to a document and semantic "meaningfulness." </para>
+ </listitem>
+ <listitem>
+ <para>The DocBook standard is a commonly-used documentation standard that has the
+ advantages over other standards of relative ease of use and a long, well-established
+ history of development and stewardship. DocBook is also the de facto standard XML schema
+ and publishing tool set for a number of open source projects, so we will be able to
+ capitalize on the work others have done before us.</para>
+ </listitem>
+ </itemizedlist>
+ </simplesect>
+ <simplesect>
+ <title>DocBook 5.0</title>
+ <para>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.</para>
+ </simplesect>
+ <simplesect>
+ <title>Our production model in a nutshell</title>
+ <para>(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.) </para>
+ <para>
+ <itemizedlist>
+ <listitem>
+ <para><emphasis role="bold">Documentation writers</emphasis> author Evergreen
+ documentation in whatever format they choose (this is a guiding principal of the
+ Evergreen documentation project), using the editors of their choice. While authors are
+ encouraged to produce documentation in DocBook 5.0, we will accept new documentation
+ in any form the author chooses to write it (and however "localized" it may be). Note
+ that the DIG project will be providing heavily-commented template files for DocBook
+ XML production. </para>
+ </listitem>
+ <listitem>
+ <para>Authors submit documents to the <emphasis role="bold">intake team</emphasis>, who
+ will submit the documentation to functional testing and revise content accordingly.
+ </para>
+ </listitem>
+ <listitem>
+ <para>If documentation needs conversion from its format to DocBook 5.0, the DIG
+ <emphasis role="bold">XML conversion team</emphasis> wrangles it.</para>
+ </listitem>
+ <listitem>
+ <para>One the files are in valid, well-formed XML conforming to the DocBook 5.0
+ standard, <emphasis role="bold">DIG XML editors</emphasis> (the human kind of editors)
+ review the files for conformance with Evergreen documentation style guidelines.</para>
+ </listitem>
+ <listitem>
+ <para>When the XML files are ready, the <emphasis role="bold">DIG transform
+ team</emphasis> members use a variety of back-end tools to process the files (or, in
+ DocBook and XML terminology, <glossterm>transform</glossterm> the files) into HTML,
+ PDF, and other formats. <emphasis role="bold">Web designers</emphasis> play a crucial
+ role at this stage as well, creating and maintaining the Cascading Stylesheets (CSS)
+ that make the documentation aesthetically pleasing and more user-friendly. Finally, a
+ small group of <emphasis role="bold">"the buck stops here" editors</emphasis> move the
+ HTML and PDF files into their folders on the website.</para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ <para>
+ </para>
+ </simplesect>
+ </section>
+ <section>
+ <title>Formatting XML</title>
+ <simplesect>
+ <title>Overview</title>
+ <para>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." </para>
+ <para>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. </para>
+ </simplesect>
+ <simplesect>
+ <title>Validation</title>
+ <para>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. </para>
+ </simplesect>
+ </section>
+ <section xml:id="info">
+ <title>Other Resources</title>
+ <simplesect>
+ <title>DocBook References</title>
+ <para>For more general references and familiarization with with DocBook, see the
+ following:</para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <link xl:href="http://DocBook.org/">DocBook.org</link>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <link xl:href="http://opensource.bureau-cornavin.com/crash-course/">The Crash Course to
+ DocBook</link>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <link xl:href="http://nwalsh.com/docbook/">Norman Walsh's DocBook page</link>
+ </para>
+ </listitem>
+ </itemizedlist>
+ </simplesect>
+ </section>
+</chapter>
Added: trunk/docs/1.6/programming.xml
===================================================================
--- trunk/docs/1.6/programming.xml (rev 0)
+++ trunk/docs/1.6/programming.xml 2009-09-09 20:31:19 UTC (rev 14000)
@@ -0,0 +1,493 @@
+<?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="programming">
+ <title>Working with Code</title>
+ <info>
+ <abstract>
+ <para>There are several instances when you will need to show code in documentation. You may need to use a class name, an interface name,
+ or an element name as part of a sentence. You will also need to provide long code samples in many places. DocBook has a number of
+ elements that are used for placing code in your documentation.</para>
+ </abstract>
+ </info>
+ <section>
+ <title>Code Listings</title>
+ <para>There are two types of code listings:</para>
+ <itemizedlist>
+ <listitem linkend="exampleSect">
+ <para>Formal examples with titles</para>
+ </listitem>
+ <listitem linkend="codeBlockSect">
+ <para>Untitled code blocks</para>
+ </listitem>
+ </itemizedlist>
+ <para>Often when making long code listings a writer also needs to explain what specific lines of code do. This can be done using
+ callouts as explained in <xref linkend="calloutSect" /></para>
+ <section xml:id="exampleSect">
+ <title>Examples</title>
+ <simplesect>
+ <title>When to use</title>
+ <para>Examples are formal code listings that have a title. They are useful for code listings that are linked to from other places in
+ the text. They are also added to the <emphasis>List of Examples</emphasis>.</para>
+ </simplesect>
+ <simplesect>
+ <title>Marking up an example</title>
+ <indexterm><primary>example element</primary></indexterm>
+ <indexterm><primary>programlisting element</primary></indexterm>
+ <para>Examples are marked up using the <tag class="element">example</tag> element. You should always provide a descriptive value for
+ the <tag class="element">example</tag> element's <tag class="attribute">xml:id</tag> attribute. The
+ <tag class="element">example</tag> element also takes a <tag class="attribute">pgwide</tag> attribute that signals that the
+ code listing should span the width of the page.<footnote><para>The <tag class="attribute">pgwide</tag> attribute is not currently
+ supported by the publication system. Writers will also need the PI for making code blocks wide as shown in
+ <xref linkend="examplePgwideSS" />.</para></footnote></para>
+ <para>The first child of the <tag class="element">example</tag> element is a <tag class="element">title</tag> element. The contents of
+ the title element will be used as the caption of the example. It will also be used as the text for any cross references.</para>
+ <para>The last child of the example element is the <tag class="element">programlisting</tag> element. The
+ <tag class="element">programlisting</tag> element contains the code sample itself. Any text placed inside the
+ <tag class="element">programlisting</tag> element is treated literally. Therefore, any spacing that you use will be exactly reproduced
+ when the document is produced.</para>
+ <warning>
+ <para>When using XML inside a <tag class="element">programlisting</tag> element you must not use the <literal><</literal> or
+ <literal>></literal> characters. Instead use <wordasword>&lt;</wordasword> and <wordasword>&gt;</wordasword>.</para>
+ </warning>
+ <para>The <tag class="element">programlisting</tag> element takes a <tag class="attribute">language</tag> attribute that
+ specifies the type of code in the example. <xref linkend="languageAttrTbl"/> describes the acceptable values.</para>
+ <table xml:id="languageAttrTbl">
+ <title>Values for the Program Listing Language Attribute</title>
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>Value</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry><tag class="attvalue">java</tag></entry>
+ <entry>Specifies that the listing is Java code.</entry>
+ </row>
+ <row>
+ <entry><tag class="attvalue">spring</tag></entry>
+ <entry>Specifies that the listing is Spring XML. This is often used in configuration files.</entry>
+ </row>
+ <row>
+ <entry><tag class="attvalue">wsdl</tag></entry>
+ <entry>Specifies that the listing is WSDL.</entry>
+ </row>
+ <row>
+ <entry><tag class="attvalue">xmlschema</tag></entry>
+ <entry>Specifies that the code listing is XML Schema. This is often seen in the type's section of a WSDL document.</entry>
+ </row>
+ <row>
+ <entry><tag class="attvalue">xml</tag></entry>
+ <entry>Specifies that the code listing is XML.</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ </simplesect>
+ <simplesect>
+ <title>Example</title>
+ <para><xref linkend="example_example"/> shows the mark-up for an example.</para>
+ <example xml:id="example_example" pgwide="1">
+ <?dbfo pgwide="1"?>
+ <title>Example Mark-Up</title>
+ <programlisting><example id="example_example">
+<title>Example Service</title>
+<programlisting language="java">public class ServiceName extends javax.xml.ws.Service
+{
+ ...
+ public ServiceName(URL wsdlLocation, QName serviceName) { }
+
+ public ServiceName() { }
+
+ public Greeter getPortName() { }
+ .
+ .
+ .
+}</programlisting>
+</example></programlisting>
+ </example>
+ <para>The mark-up shown in <xref linkend="example_example" /> is generated into <xref linkend="exampleExampleGen" />.</para>
+ <example xml:id="exampleExampleGen">
+ <title>Example Service</title>
+ <programlisting language="java">public class ServiceName extends javax.xml.ws.Service
+{
+ ...
+ public ServiceName(URL wsdlLocation, QName serviceName) { }
+
+ public ServiceName() { }
+
+ public Greeter getPortName() { }
+ .
+ .
+ .
+}</programlisting>
+ </example>
+ </simplesect>
+ <simplesect xml:id="examplePgwideSS">
+ <title>Making the example span the page</title>
+ <para>The code used for an example does not always fit properly in the space allotted for text in the PDF output template. To fix this
+ writers can specify that an example should span the entire page from the left margin to the right margin using the
+ <markup><?dbfo pgwide="1"?></markup> PI.</para>
+ <para>As shown in <xref linkend="examplePgwideEx"/>, the <markup><?dbfo pgwide="1"?></markup> PI is placed directly
+ after the opening <tag class="element">example</tag> tag.</para>
+ <example xml:id="examplePgwideEx">
+ <?dbfo pgwide="1"?>
+ <title>Wide Example Mark-Up</title>
+ <programlisting><example id="examplePgwideEx">
+<?dbfo pgwide="1"?>
+<title>Example Service</title>
+<programlisting language="java">
+ .
+ .
+ .
+}</programlisting>
+</example></programlisting>
+ </example>
+ </simplesect>
+ </section>
+ <section xml:id="codeBlockSect">
+ <title>Code Blocks</title>
+ <simplesect>
+ <title>When to use</title>
+ <para>Code blocks are useful for short code listings that show a specific action. They are not appropriate for code listings
+ that need to be referenced later. They also do not appear in the <emphasis>List of Examples</emphasis>.</para>
+ </simplesect>
+ <simplesect>
+ <title>Mark-up</title>
+ <indexterm><primary>informalexample element</primary></indexterm>
+ <indexterm><primary>programlisting element</primary></indexterm>
+ <para>Code blocks are marked up using the <tag class="element">informalexample</tag> element.</para>
+ <para>The only child of the <tag class="element">informalexample</tag> element is a <tag class="element">programlisting</tag> element.
+ This element contains the code listing itself. Any text placed inside the <tag class="element">programlisting</tag> element is
+ treated literally. Therefore, any spacing that you use will be exactly reproduced when the document is produced.</para>
+ <warning>
+ <para>When using XML inside a <tag class="element">programlisting</tag> element you must not use the <literal><</literal> or
+ <literal>></literal> characters. Instead use <wordasword>&lt;</wordasword> and <wordasword>&gt;</wordasword>.</para>
+ </warning>
+ <para>The <tag class="element">programlisting</tag> element takes a <tag class="attribute">language</tag> attribute that
+ specifies the type of code in the example. <xref linkend="languageAttrTbl"/> describes the acceptable values.</para>
+ </simplesect>
+ <simplesect>
+ <title>Example</title>
+ <para><xref linkend="block_example"/> shows the mark-up for a standalone block of code.</para>
+ <example xml:id="block_example" pgwide="1">
+ <?dbfo pgwide="1"?>
+ <title>Example Code Block</title>
+ <programlisting><informalexample>
+ <programlisting language="javascript">var WebServiceProvider1 = {
+ 'wsdlLocation': 'file:./wsdl/hello_world.wsdl',
+ 'serviceName': 'SOAPService1',
+ 'portName': 'SoapPort1',
+ 'targetNamespace': http://objectweb.org/hello_world_soap_http',
+};</programlisting>
+</informalexample></programlisting>
+ </example>
+ <para>The mark-up shown in <xref linkend="block_example"/> would be published as follows:</para>
+ <informalexample>
+ <programlisting language="javascript">var WebServiceProvider1 = {
+ 'wsdlLocation': 'file:./wsdl/hello_world.wsdl',
+ 'serviceName': 'SOAPService1',
+ 'portName': 'SoapPort1',
+ 'targetNamespace': 'http://objectweb.org/hello_world_soap_http',
+};</programlisting>
+</informalexample>
+ </simplesect>
+ <simplesect xml:id="codeBlockPgwideSS">
+ <title>Making the code block span the page</title>
+ <para>Code listings do not always fit properly in the space allotted for text in the PDF output template. To fix this
+ writers can specify that a code listing should span the entire page from the left margin to the right margin using the
+ <markup><?dbfo pgwide="1"?></markup> PI.</para>
+ <para>As shown in <xref linkend="codeBlockPgwideEx"/>, the <markup><?dbfo pgwide="1"?></markup> PI is placed directly
+ after the opening <tag class="element">informalexample</tag> tag.</para>
+ <example xml:id="codeBlockPgwideEx">
+ <?dbfo pgwide="1"?>
+ <title>Wide Code Block Mark-Up</title>
+ <programlisting><informalexample id="codeBlockPgwideEx">
+<?dbfo pgwide="1"?>
+<programlisting language="java">
+ .
+ .
+ .
+}</programlisting>
+</informalexample></programlisting>
+ </example>
+ </simplesect>
+ </section>
+ <section xml:id="calloutSect">
+ <title>Using Callouts</title>
+ <indexterm><primary>co element</primary></indexterm>
+ <indexterm><primary>calloutlist element</primary></indexterm>
+ <para>It is often helpful to use callouts to explain what it happening in a section of code. Specifying callouts is a two step process:</para>
+ <orderedlist>
+ <listitem>
+ <para>Specify where in the code listing you want to place callout markers.</para>
+ </listitem>
+ <listitem>
+ <para>Specify the callout text for each callout.</para>
+ </listitem>
+ </orderedlist>
+ <simplesect>
+ <title>Specifying the callout locations</title>
+ <para>To specify the placement of a callout in a program listing you place a <tag class="element">co</tag> element at the location inside of the program listing you want the callout to appear. The <tag class="element">co</tag> element requires that you set a value for its <tag class="attribute">id</tag> attribute. The value is used to associate the callout marker with the text that describes it. You should also provide a value for the <tag class="element">co</tag> element's <tag class="attribute">linkends</tag> attribute. This value will match the value of the <tag class="attribute">id</tag> attribute of the associated text. Using this attribute allows for a links to be generated between the callout and the associated text.</para>
+ <note>
+ <para>Setting the <tag class="attribute">linkends</tag> attribute before entering the callout text will result in an invalid XML file. Once you add the callout text, the file should be valid.</para>
+ </note>
+ </simplesect>
+ <simplesect>
+ <title>Specifying the callout text</title>
+ <para>The text associated with a callout is specified outside of the <tag class="element">programlisting</tag> element and the <tag class="element">example</tag> element. Shortly after the <tag class="element">example</tag> element, preferably immediately after, you need to place a <tag class="element">calloutlist</tag> element. The <tag class="element">calloutlist</tag> element wraps the elements that specify the callout text. It contains an optional <tag class="element">title</tag> element and one <tag class="element">callout</tag> element for each callout specified for the associated program listing.</para>
+ <para>Each <tag class="element">callout</tag> element must have its <tag class="attribute">arearefs</tag> attribute set to the value of <tag class="attribute">id</tag> attribute of the callout for which it defines the text. If you set the <tag class="attribute">linkends</tag> attribute of the associated <tag class="element">co</tag> element, you must also set the <tag class="element">callout</tag> element's <tag class="attribute">id</tag> attribute to the matching value. The callout text is the value of the <tag class="element">callout</tag> element.</para>
+ </simplesect>
+ <simplesect>
+ <title>Example</title>
+ <para><xref linkend="callout_example"/> shows the mark-up for <olink targetptr="LinksCalloutExample"/>.</para>
+ <example xml:id="callout_example" pgwide="1">
+ <?dbfo pgwide="1"?>
+ <title>Using Callouts</title>
+ <programlisting><example xml:id="LinksCalloutExample">
+<dbfo pgwide="1"?>
+ <title>Document Set Site Map</title>
+ <programlisting><?xml version="1.0" encoding="utf-8"?> <co linkends="sitemapptr0" xml:id="sitemapco0"/>
+<targetset> <co linkends="sitemapptr3" xml:id="sitemapco3"/>
+ <targetsetinfo> <co linkends="sitemapptr4" xml:id="sitemapco4"/>
+ Site map for the Evergreen XML Style Guide
+ </targetsetinfo>
+ <sitemap> <co linkends="sitemapptr5" xml:id="sitemapco5"/>
+ <dir name="docs_rls_inferno"> <co linkends="sitemapptr6" xml:id="sitemapco6"/>
+ <dir name="fluff"> <co linkends="sitemapptr75" xml:id="sitemapco75"/>
+ <dir name="overview"> <co linkends="sitemapptr7" xml:id="sitemapco7"/>
+ <document targetdoc="InfernoOverview"> <co linkends="sitemapptr8" xml:id="sitemapco8"/>
+ <xi:include href="overview/target.db" xmlns:xi="http://www.w3.org/2001/XInclude" /> <co linkends="sitemapptr9" xml:id="sitemapco9"/>
+ </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></programlisting>
+</example>
+<calloutlist>
+ <title>Elements of the Site Map</title>
+ <callout arearefs="sitemapco0" xml:id="sitemapptr0">
+ <para>The site map should always be encoded as UTF-8. This ensures that all of the generated target data has the same encodings regardless of the encodings used by the XML source files.</para>
+ </callout>
+ <callout arearefs="sitemapco3" xml:id="sitemapptr3">
+ <para>The <tag class="element">targetset</tag> element is the root of the site map.</para>
+ </callout>
+ <callout arearefs="sitemapco4" xml:id="sitemapptr4">
+ <para>The <tag class="element">targetsetinfo</tag> element allows you to provide a description for the document set or any other information that is relevant to the site map.</para>
+ </callout>
+ <callout arearefs="sitemapco5" xml:id="sitemapptr5">
+ <para>The <tag class="element">sitemap</tag> element contains the directory layout of the output files.</para>
+ </callout>
+ <callout arearefs="sitemapco6" xml:id="sitemapptr6">
+ <para>The name of the top-level directory is not important in the generation of the target databases for the links. The links are generated relative to the top-level directory.</para>
+ </callout>
+ <callout arearefs="sitemapco75" xml:id="sitemapptr75">
+ <para>This is a directory that only contains other directories.</para>
+ </callout>
+ <callout arearefs="sitemapco7" xml:id="sitemapptr7">
+ <para>This directory holds a generated book.</para>
+ </callout>
+ <callout arearefs="sitemapco8" xml:id="sitemapptr8">
+ <para>The <tag class="element">document</tag> element's <tag class="attribute">targetdoc</tag> attribute specifies the identifier used in the <tag class="element">olink</tag> element's <tag class="attribute">targetdoc</tag> attribute when linking to targets in the document.</para>
+ </callout>
+ <callout arearefs="sitemapco9" xml:id="sitemapptr9">
+ <para>The target database is included in the site map using an <tag class="element">xi:include</tag> element. The path for each book's target database should be <filename><replaceable>book_src_dir</replaceable>/target.db</filename>.</para>
+ </callout>
+</calloutlist></programlisting>
+ </example>
+ </simplesect>
+ </section>
+ </section>
+ <section xml:id="prog_arts">
+ <title>In-line Code</title>
+ <simplesect>
+ <title>DocBook programming elements</title>
+ <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:</para>
+ <itemizedlist>
+ <listitem>
+ <para><tag class="element">tag</tag></para>
+ </listitem>
+ <listitem>
+ <para><tag class="element">classname</tag></para>
+ </listitem>
+ <listitem>
+ <para><tag class="element">interfacename</tag></para>
+ </listitem>
+ <listitem>
+ <para><tag class="element">methodname</tag></para>
+ </listitem>
+ <listitem>
+ <para><tag class="element">uri</tag></para>
+ </listitem>
+ <listitem>
+ <para><tag class="element">package</tag></para>
+ </listitem>
+ <listitem>
+ <para><tag class="element">code</tag></para>
+ </listitem>
+ </itemizedlist>
+ </simplesect>
+ <simplesect>
+ <title>XML artifacts</title>
+ <para>When placing XML artifacts such as element names or attribute names in your text wrap them in an
+ <tag class="element">tag</tag> element. To specify the type of XML artifact, the <tag class="element">tag</tag> element's
+ <tag class="attribute">class</tag> attribute is always used. <xref linkend="class_values"/> shows the values used for the
+ <tag class="attribute">class</tag> attribute.</para>
+ <table xml:id="class_values">
+ <title>Values for the <tag class="attribute">class</tag> Attribute</title>
+ <tgroup cols="2">
+ <colspec colwidth="1.5in"/>
+ <thead>
+ <row>
+ <entry>Value</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry><tag class="attvalue">attribute</tag></entry>
+ <entry>Specifies that the artifact is an attribute of an XML element.</entry>
+ </row>
+ <row>
+ <entry><tag class="attvalue">element</tag></entry>
+ <entry>Specifies that the artifact is an XML element.</entry>
+ </row>
+ <row>
+ <entry><tag class="attvalue">attvalue</tag></entry>
+ <entry>Specifies that the artifact is the value of an XML element's attribute.</entry>
+ </row>
+ <row>
+ <entry><tag class="attvalue">emptytag</tag></entry>
+ <entry>Specifies an XML element that does not hold any data such as <tag class="emptytag">foo</tag>.</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ </simplesect>
+ <simplesect>
+ <title>Web Addresses, URIs, and E-Mail Addresses</title>
+ <para>To specify a Web address or URI you use the <tag class="element">uri</tag> element.</para>
+ <para>To specify an E-Mail address use the <tag class="element">email</tag> element.</para>
+ </simplesect>
+ <simplesect xml:id="gen_prog_arts">
+ <title>General programming language artifacts</title>
+ <para>DocBook defines a number of in-line tags for specifying programming artifacts. The commonly used tags are listed in
+ <xref linkend="progarti"/>.</para>
+ <table frame="all" xml:id="progarti">
+ <title>Elements for In-Line Programming Artifacts</title>
+ <tgroup cols="2">
+ <colspec colnum="1" colname="c1" colwidth="1.5in"/>
+ <colspec colnum="2" colname="c2"/>
+ <thead>
+ <row>
+ <entry>Element</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry><tag class="element">type</tag></entry>
+ <entry>Specifies that the artifact is a data type such as <type>int</type>.</entry>
+ </row>
+ <row>
+ <entry><tag class="element">constant</tag></entry>
+ <entry>Specifies that the artifact is a constant such as <constant>NULL</constant> or <constant>9</constant>.</entry>
+ </row>
+ <row>
+ <entry><tag class="element">exceptionname</tag></entry>
+ <entry>Specifies that the artifact is an exception. It could be the name of the exception or the name of the class that
+ implements the exception.</entry>
+ </row>
+ <row>
+ <entry><tag class="element">function</tag></entry>
+ <entry>Specifies that the artifact is a function such as <function>println()</function>.</entry>
+ </row>
+ <row>
+ <entry><tag class="element">parameter</tag></entry>
+ <entry>Specifies that the artifact is a parameter to a function or a method.</entry>
+ </row>
+ <row>
+ <entry><tag class="element">varname</tag></entry>
+ <entry>Specifies that the artifact is a variable.</entry>
+ </row>
+ <row>
+ <entry><tag class="element">code</tag></entry>
+ <entry>Used for generic code entries that do not fit into any other category.</entry>
+ </row>
+ <row>
+ <entry><markup>code role="annotation"</markup></entry>
+ <entry>Used for Java annotations.</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ </simplesect>
+ <simplesect>
+ <title>Object-oriented programming language artifacts</title>
+ <para>In addition to the elements listed in <xref linkend="gen_prog_arts"/>, DocBook defines a number of elements that are used
+ specifically for object-oriented programming artifacts. They are listed in <xref linkend="oo_arts"/>.</para>
+ <table frame="all" xml:id="oo_arts">
+ <title>Elements for In-Line OO Programming Artifacts</title>
+ <tgroup cols="2">
+ <colspec colnum="1" colname="c1" colwidth="1.5in"/>
+ <colspec colnum="2" colname="c2"/>
+ <thead>
+ <row>
+ <entry>Element</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry><tag class="element">interfacename</tag></entry>
+ <entry>Specifies that the artifact is a Java interface the user must implement.</entry>
+ </row>
+ <row>
+ <entry><tag class="element">oointerface</tag></entry>
+ <entry>Specifies that the artifact is a Java interface the user must implement. Requires the use of an <tag class="element">modifier</tag> element that contains details about if the interface is public or private.</entry>
+ </row>
+ <row>
+ <entry><tag class="element">classname</tag></entry>
+ <entry>Specifies that the artifact is a Java class or an instantiated object.</entry>
+ </row>
+ <row>
+ <entry><tag class="element">ooclass</tag></entry>
+ <entry>Specifies that the artifact is a Java class. Requires the use of an <tag class="element">modifier</tag> element that
+ contains details about if the class is public/private or static/final.</entry>
+ </row>
+ <row>
+ <entry><tag class="element">methodname</tag></entry>
+ <entry>Specifies that the artifact is a method. Methods are different from functions in that methods are associated with classes and objects.</entry>
+ </row>
+ <row>
+ <entry><tag class="element">ooexception</tag></entry>
+ <entry>Specifies that the artifact is a Java exception. Requires the use of an <tag class="element">modifier</tag> element that
+ contains details about if the exception is public or private.</entry>
+ </row>
+ <row>
+ <entry><tag class="element">package</tag></entry>
+ <entry>Specifies that the artifact is the name of a Java or C++ package.</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ </simplesect>
+ </section>
+</chapter>
\ No newline at end of file
Added: trunk/docs/1.6/structure.xml
===================================================================
--- trunk/docs/1.6/structure.xml (rev 0)
+++ trunk/docs/1.6/structure.xml 2009-09-09 20:31:19 UTC (rev 14000)
@@ -0,0 +1,133 @@
+<?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="structure">
+ <title>The Structure of Evergreen Documentation</title>
+ <info>
+ <abstract>
+ <para>This chapter describes the structure of Evergreen documentation, common elements in XML
+ files, and allowable documentation types.</para>
+ </abstract>
+ </info>
+ <section>
+ <title>Top-level Elements in Evergreen Documentation</title>
+ <simplesect>
+ <title>Overview</title>
+ <para>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:</para>
+ <para>http://evergreen-ils.org/docs/1.6 ...</para>
+ <para>The following is a common structural pattern for our documentation:</para>
+ <itemizedlist>
+ <listitem>
+ <para><emphasis role="bold"><tag class="element">set</tag></emphasis></para>
+ </listitem>
+ <listitem>
+ <para><emphasis role="bold"><tag class="element">book</tag></emphasis></para>
+ </listitem>
+ <listitem>
+ <para><emphasis role="bold"><tag class="element">chapter</tag></emphasis>--a major topic
+ area, such as Circulation</para>
+ </listitem>
+ <listitem>
+ <para><emphasis role="bold"><tag class="element">section</tag></emphasis>--a subsection of
+ an area, such as Patron Registration</para>
+ </listitem>
+ <listitem>
+ <para><emphasis role="bold"><tag class="element">simplesect</tag></emphasis>--subdivision
+ of section, such as Family Accounts</para>
+ </listitem>
+ <listitem>
+ <para><emphasis role="bold"><tag class="element">para</tag></emphasis>--a basic paragraph
+ marker</para>
+ </listitem>
+ </itemizedlist>
+ <para>Most authors will be working at the <tag class="element">chapter</tag> or <tag
+ class="element">section</tag> level. Chapters are created in separate files and imported
+ into the book file using <tag class="element">xinclude</tag> elements.</para>
+ <para>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 <tag class="element" revision="">glossary</tag> element. </para>
+ <para>The final chapter of this styleguide lists excluded tags for Evergreen documentation.
+ </para>
+ </simplesect>
+ </section>
+ <section>
+ <title>The Sets and Chapters of Evergreen Documentation</title>
+ <simplesect>
+ <title>Overview</title>
+ <para>Evergreen documentation has the following high-level set, books, and chapters. Filenames
+ are in parentheses:</para>
+ <para>
+ <itemizedlist>
+ <listitem>
+ <para><emphasis role="bold"><tag class="element">set</tag></emphasis> (set.xml)</para>
+ </listitem>
+ <listitem>
+ <para><emphasis role="bold"><tag class="element">book</tag></emphasis> Evergreen
+ Technical Reference (book1.xml)</para>
+ </listitem>
+ <listitem>
+ <para><emphasis role="bold"><tag class="element">chapter</tag></emphasis> Installing
+ (installing.xml)</para>
+ </listitem>
+ <listitem>
+ <para><emphasis role="bold"><tag class="element">chapter</tag></emphasis> Upgrading
+ (upgrading.xml)</para>
+ </listitem>
+ <listitem>
+ <para><emphasis role="bold"><tag class="element">chapter</tag></emphasis> Migrating from
+ other Integrated Library Systems (migrating.xml)</para>
+ </listitem>
+ <listitem>
+ <para><emphasis role="bold"><tag class="element">chapter</tag></emphasis> System
+ Administration (sysadmin.xml)</para>
+ </listitem>
+ <listitem>
+ <para><emphasis role="bold"><tag class="element">chapter</tag></emphasis> Software
+ Developers' Reference (softwaredev.xml)</para>
+ </listitem>
+ <listitem>
+ <para><emphasis role="bold"><tag class="element">chapter</tag></emphasis> Web
+ Developers' Reference (webdev.xml)</para>
+ </listitem>
+ <listitem>
+ <para><emphasis role="bold"><tag class="element">book</tag></emphasis> Evergreen (?)
+ Reference (book2.xml)</para>
+ </listitem>
+ <listitem>
+ <para><emphasis role="bold"><tag class="element">chapter</tag></emphasis> Local
+ Administration (localadmin.xml)</para>
+ </listitem>
+ <listitem>
+ <para><emphasis role="bold"><tag class="element">chapter</tag></emphasis> The OPAC
+ (opac.xml)</para>
+ </listitem>
+ <listitem>
+ <para><emphasis role="bold"><tag class="element">chapter</tag></emphasis> Cataloging
+ (cataloging.xml)</para>
+ </listitem>
+ <listitem>
+ <para><emphasis role="bold"><tag class="element">chapter</tag></emphasis> Circulation
+ (circulation.xml)</para>
+ </listitem>
+ <listitem>
+ <para><emphasis role="bold"><tag class="element">chapter</tag></emphasis> Reports
+ (reports.xml)</para>
+ </listitem>
+ <listitem>
+ <para><emphasis role="bold"><tag class="element">chapter</tag></emphasis> Acquisitions
+ (acquisitions.xml)</para>
+ </listitem>
+ <listitem>
+ <para><emphasis role="bold"><tag class="element">chapter</tag></emphasis> Future
+ Development (futuredev.xml)</para>
+ </listitem>
+ <listitem>
+ <para><emphasis role="bold"><tag class="element">chapter</tag></emphasis> Glossary
+ (glossary.xml)</para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ </simplesect>
+ </section>
+</chapter>
Added: trunk/docs/1.6/styleguide.xml
===================================================================
--- trunk/docs/1.6/styleguide.xml (rev 0)
+++ trunk/docs/1.6/styleguide.xml 2009-09-09 20:31:19 UTC (rev 14000)
@@ -0,0 +1,26 @@
+<?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="styleguide">
+ <title>Evergreen Documentation Style Guide (Draft .01)</title>
+
+ <info>
+ <pubdate><?dbtimestamp format="d b Y"?></pubdate>
+ </info>
+ <xi:include href="overview.xml"/>
+ <xi:include href="authoring.xml"/>
+ <xi:include href="structure.xml"/>
+ <xi:include href="books.xml"/>
+ <xi:include href="filenames.xml"/>
+ <xi:include href="chapter.xml"/>
+ <xi:include href="indexterms.xml"/>
+ <xi:include href="figures.xml"/>
+ <xi:include href="lists.xml"/>
+ <xi:include href="tables.xml"/>
+ <xi:include href="admon.xml"/>
+ <xi:include href="links.xml"/>
+ <xi:include href="general.xml"/>
+ <xi:include href="exclude.xml"/>
+ <xi:include href="programming.xml"/>
+ <xi:include href="glossary.xml"/>
+ <index/>
+</book>
Added: trunk/docs/1.6/tables.xml
===================================================================
--- trunk/docs/1.6/tables.xml (rev 0)
+++ trunk/docs/1.6/tables.xml 2009-09-09 20:31:19 UTC (rev 14000)
@@ -0,0 +1,818 @@
+<?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="tables">
+ <title>Tables</title>
+ <section>
+ <title>Types of Tables</title>
+ <para>There are two types of tables in DocBook:</para>
+ <itemizedlist>
+ <listitem>
+ <para>Informal tables</para>
+ </listitem>
+ <listitem>
+ <para>Tables</para>
+ </listitem>
+ </itemizedlist>
+ <para>An informal table is simply a table that does not have a title. Tables
+must have a title element and are listed in a list of tables if it is
+generated.</para>
+ </section>
+ <section>
+ <title>Specifying a Table</title>
+ <para>Both informal tables and tables use the same markup elements to define
+their structure. The differences are as follows:</para>
+ <itemizedlist>
+ <listitem>
+ <para>Informal tables are specified using the <tag class="element">informaltable</tag> element and tables are specified using
+the <tag class="element">table</tag> element.</para>
+ </listitem>
+ <listitem>
+ <para>Informal tables cannot contain a <tag class="element">title</tag> element and tables require a <tag class="element">title</tag> element.</para>
+ </listitem>
+ </itemizedlist>
+ <para>Creating a table involves the following steps:</para>
+ <procedure>
+ <step>
+ <para>Specify the proper root element.</para>
+ </step>
+ <step>
+ <para>If you are creating a table, add a <tag class="element">title</tag> element.</para>
+ </step>
+ <step>
+ <para>Add a <tag class="element">tgroup</tag> element to wrap the
+contents of the table.</para>
+ </step>
+ <step>
+ <para>If needed, add <tag class="element">colspec</tag> elements to
+specify properties for specific columns.</para>
+ </step>
+ <step>
+ <para>If needed, add <tag class="element">spanspec</tag> elements to
+define reusable column spans.</para>
+ </step>
+ <step>
+ <para>If desired, add a <tag>thead</tag> element to specify a header
+row.</para>
+ <substeps>
+ <step>
+ <para>Add a <tag class="element">row</tag> element.</para>
+ </step>
+ <step>
+ <para>Add an <tag class="element">entry</tag> element for each column
+heading.</para>
+ </step>
+ </substeps>
+ </step>
+ <step>
+ <para>Add a <tag class="element">tbody</tag> element to contain the
+body of the table.</para>
+ <substeps>
+ <step>
+ <para>Add one <tag class="element">row</tag> element for each row in
+the table.</para>
+ </step>
+ <step>
+ <para>In the <tag class="element">row</tag> elements, add an <tag class="element">entry</tag> element for each value that appear in the
+row.</para>
+ </step>
+ </substeps>
+ </step>
+ </procedure>
+ <section>
+ <title>Table Root Elements</title>
+ <para>Depending on the type of table you are using you will use either the
+<tag class="element">informaltable</tag> element or the <tag class="element">table</tag> element as the root element of your table.
+Both elements use the attributes listed in <xref linkend="rootattrs"/>.</para>
+ <table frame="all" xml:id="rootattrs" pgwide="1">
+ <title>Attributes for <tag class="element">table</tag> Element and <tag class="element">informaltable</tag> Element</title>
+ <tgroup cols="3" colsep="1" rowsep="1">
+ <colspec colwidth="1.5in"/>
+ <thead>
+ <row>
+ <entry align="center">Attribute</entry>
+ <entry align="center">Description</entry>
+ <entry align="center">Values</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>
+ <indexterm><primary>table</primary><secondary>pgwide</secondary></indexterm>
+ <tag class="attribute">pgwide</tag>
+ </entry>
+ <entry>Specifies whether the table will be span the whole page in PDF output.</entry>
+ <entry><tag class="attvalue">0</tag> (default), <tag class="attvalue">1</tag></entry>
+ </row>
+ <row>
+ <entry>
+ <tag class="attribute">colsep</tag>
+ </entry>
+ <entry>Specifies whether a rule will be drawn between the columns in the table.</entry>
+ <entry><tag class="attvalue">0</tag>, <tag class="attvalue">1</tag> (default)</entry>
+ </row>
+ <row>
+ <entry>
+ <tag class="attribute">frame</tag>
+ </entry>
+ <entry>Specifies how the table will be framed.</entry>
+ <entry><tag class="attvalue">all</tag>, <tag class="attvalue">bottom</tag>, <tag class="attvalue">none</tag>, <tag class="attvalue">sides</tag>, <tag class="attvalue">top</tag>, <tag class="attvalue">topbot</tag></entry>
+ </row>
+ <row>
+ <entry>
+ <tag class="attribute">orient</tag>
+ </entry>
+ <entry>Specifies how the table will be oriented in relationship to the rest of the text.</entry>
+ <entry><tag class="attvalue">land</tag>, <tag class="attvalue">port</tag> (default)</entry>
+ </row>
+ <row>
+ <entry>
+ <tag class="attribute">rowsep</tag>
+ </entry>
+ <entry>Specifies whether a rule will be drawn between the rows in the table.</entry>
+ <entry><tag class="attvalue">0</tag>, <tag class="attvalue">1</tag> (default)</entry>
+ </row>
+ <row>
+ <entry>
+ <tag class="attribute">xml:id</tag>
+ </entry>
+ <entry>Specifies a unique identifier used to reference the table.</entry>
+ <entry>a unique string</entry>
+ </row>
+ <row>
+ <entry>
+ <tag class="attribute">xreflabel</tag>
+ </entry>
+ <entry>
+ <para>Specifies a label to be used when cross referencing the table.</para>
+ </entry>
+ <entry>a string</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ <note>
+ <para>Attributes not listed in <xref linkend="rootattrs"/> are not used in Evergreen' documentation.</para>
+ </note>
+ </section>
+ <section>
+ <title>The tgroup Element</title>
+ <indexterm><primary>tgroup</primary></indexterm>
+ <para>The <tag class="element">tgroup</tag> element groups together the logical components of a table. It specifies the number of columns in a table and contains the column and span specifications used by the table. All of the rows, including the header, are defined inside of the <tag class="element">tgroup</tag> element.</para>
+ <para>While most tables contain a single <tag class="element">tgroup</tag> element, it is possible for a complex table to have multiple tgroup elements. In such a case, each <tag class="element">tgroup</tag> element would define a unique portion of table where the columns and spans had different specifications.</para>
+ <simplesect>
+ <title>Attributes</title>
+ <para><xref linkend="tgroupattrs"/> shows the attributes for the <tag class="element">tgroup</tag> element. Attributes in the <tag class="element">tgroup</tag> element override the corresponding attributes
+from the table's root element.</para>
+ <table xml:id="tgroupattrs" pgwide="1">
+ <title>Attributes for the <tag class="element">tgroup</tag> Element</title>
+ <tgroup cols="3">
+ <colspec colwidth="1.5in"/>
+ <thead>
+ <row>
+ <entry align="center">Attribute</entry>
+ <entry align="center">Description</entry>
+ <entry align="center">Values</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>
+ <tag class="attribute">colsep</tag>
+ </entry>
+ <entry>Specifies whether a rule will be drawn between the columns of the group.</entry>
+ <entry><tag class="attvalue">0</tag>, <tag class="attvalue">1</tag> (default)</entry>
+ </row>
+ <row>
+ <entry>
+ <tag class="attribute">rowsep</tag>
+ </entry>
+ <entry>Specifies whether a rule will be drawn between the rows of the group.</entry>
+ <entry><tag class="attvalue">0</tag>, <tag class="attvalue">1</tag> (default)</entry>
+ </row>
+ <row>
+ <entry>
+ <tag>align</tag>
+ </entry>
+ <entry>Specifies the horizontal alignment of the entries in the group.</entry>
+ <entry><tag class="attvalue">center</tag>, <tag class="attvalue">justify</tag>, <tag class="attvalue">right</tag>, <tag class="attvalue">left</tag> (default)</entry>
+ </row>
+ <row>
+ <entry>
+ <tag>cols</tag>
+ </entry>
+ <entry>A required attribute that specifies the number of columns in the group.</entry>
+ <entry>>=1</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ <note>
+ <para>Attributes not listed in <xref linkend="tgroupattrs"/> are not used in Evergreen' documentation.</para>
+ </note>
+ </simplesect>
+ <simplesect>
+ <title>Example</title>
+ <para><xref linkend="groupexample"/> shows the markup for a <tag class="element">tgroup</tag> element that defines a 3 column table.</para>
+ <informalexample xml:id="groupexample" xreflabel="The following">
+ <programlisting><informaltable ...>
+ <tgroup cols="3" colsep="1" rowsep="1" >
+ ...
+ </tgroup>
+</table></programlisting>
+ </informalexample>
+ </simplesect>
+ </section>
+ <section xml:id="ColProps">
+ <title>Specifying Column Properties</title>
+ <para>If you desire, you can specify a number of the display properties for
+the column in a table by adding <tag class="element">colspec</tag>
+elements to a <tag class="element">tgroup</tag> element. A <tag class="element">colspec</tag> element defines properties for all of the
+entries in one column in a group. You can set different properties for each
+column in a group.</para>
+ <simplesect>
+ <title>Attributes</title>
+ <para><xref linkend="colattrs"/> shows the attributes for the <tag class="element">colspec</tag> element. Attributes in the <tag class="element">colspec</tag> element override corresponding attributes in
+the parent <tag class="element">tgroup</tag> element and the table's
+root element.</para>
+ <table xml:id="colattrs" pgwide="1">
+ <title>Attributes for the <tag class="element">colspec</tag> Element</title>
+ <tgroup cols="3">
+ <colspec colwidth="1.5in"/>
+ <thead>
+ <row>
+ <entry align="center">Attribute</entry>
+ <entry align="center">Description</entry>
+ <entry align="center">Values</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>
+ <tag class="attribute">colsep</tag>
+ </entry>
+ <entry>Specifies whether a rule will be drawn to the right of entries in the column.</entry>
+ <entry><tag class="attvalue">0</tag>, <tag class="attvalue">1</tag> (default)</entry>
+ </row>
+ <row>
+ <entry>
+ <tag class="attribute">rowsep</tag>
+ </entry>
+ <entry>Specifies whether a rule will be drawn between the rows in the column.</entry>
+ <entry><tag class="attvalue">0</tag>, <tag class="attvalue">1</tag> (default)</entry>
+ </row>
+ <row>
+ <entry>
+ <tag>align</tag>
+ </entry>
+ <entry>Specifies the horizontal alignment of the entries in the column.</entry>
+ <entry><tag class="attvalue">center</tag>, <tag class="attvalue">justify</tag>, <tag class="attvalue">right</tag>, <tag class="attvalue">left</tag> (default)</entry>
+ </row>
+ <row>
+ <entry>
+ <tag>colnum</tag>
+ </entry>
+ <entry>Specifies the number of the column being specified.</entry>
+ <entry>1<=<replaceable>X</replaceable><=number of columns</entry>
+ </row>
+ <row>
+ <entry>
+ <tag class="attribute">colname</tag>
+ </entry>
+ <entry>Specifies a unique identifier by which the column can be referenced by other elements in the group.</entry>
+ <entry>a unique string</entry>
+ </row>
+ <row>
+ <entry>
+ <tag class="attribute">colwidth</tag>
+ </entry>
+ <entry>Specifies the width of the column.</entry>
+ <entry>Can be either a fixed measure using either points (pts), inches (in), or centimeters (cm).</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ <note>
+ <para>Attributes not listed in <xref linkend="colattrs"/> are not used in Evergreen' documentation.</para>
+ </note>
+ </simplesect>
+ <simplesect>
+ <title>Example</title>
+ <para><xref linkend="colspecexample"/> shows the markup for specifying a
+column that is two inches wide and whose content is justified.</para>
+ <example xml:id="colspecexample">
+ <?dbfo pgwide="1"?>
+ <title>Setting Column Properties</title>
+ <programlisting><table ...>
+ <title>...</title>
+ <tgroup ... >
+ <colspec align="justify" colwidth="2in" colname="2incol" />
+ ...
+ </tgroup>
+</table></programlisting>
+ </example>
+ </simplesect>
+ </section>
+ <section xml:id="SpanProps">
+ <title>Defining Spans</title>
+ <para>DocBook allows you to define properties for cells that span columns and
+name them for use by the cells in the group. To define a span you use the
+<tag class="element">spanspec</tag> element.</para>
+ <simplesect>
+ <title>Required Attributes</title>
+ <para>The <tag class="element">spanspec</tag> element has three
+required attributes as described in <xref linkend="spanreqattrs"/>.</para>
+ <table xml:id="spanreqattrs" pgwide="1">
+ <title>Required Attributes for the <tag class="element">spanspec</tag> Element</title>
+ <tgroup cols="2">
+ <colspec colwidth="1.5in"/>
+ <thead>
+ <row>
+ <entry align="center">Attribute</entry>
+ <entry align="center">Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>
+ <tag class="attribute">spanname</tag>
+ </entry>
+ <entry>Specifies the name by which cells will refer to the span.</entry>
+ </row>
+ <row>
+ <entry>
+ <tag class="attribute">namest</tag>
+ </entry>
+ <entry>Specifies the name, as declared in a <tag class="element">colspec</tag> element's <tag class="attribute">colname</tag> attribute, of the starting column for the span.</entry>
+ </row>
+ <row>
+ <entry>
+ <tag>nameend</tag>
+ </entry>
+ <entry>Specifies the name, as declared in a <tag class="element">colspec</tag> element's <tag class="attribute">colname</tag> attribute, of the ending column for the span.</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ </simplesect>
+ <simplesect>
+ <title>Optional Attributes</title>
+ <para>In addition to the required attributes, the <tag class="element">spanspec</tag> element can also have the attributes
+described in <xref linkend="spanoptattrs"/>. Attributes in the <tag class="element">spanspec</tag> element override corresponding attributes
+in the parent <tag class="element">tgroup</tag> element and the
+table's root element.</para>
+ <table xml:id="spanoptattrs" pgwide="1">
+ <title>Optional Attributes for the <tag class="element">spanspec</tag> Element</title>
+ <tgroup cols="3">
+ <colspec colwidth="1.5in"/>
+ <thead>
+ <row>
+ <entry align="center">Attribute</entry>
+ <entry align="center">Description</entry>
+ <entry align="center">Values</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>
+ <tag class="attribute">colsep</tag>
+ </entry>
+ <entry>Specifies whether a rule will be drawn to the right of entries in the span.</entry>
+ <entry><tag class="attvalue">0</tag>, <tag class="attvalue">1</tag> (default)</entry>
+ </row>
+ <row>
+ <entry>
+ <tag class="attribute">rowsep</tag>
+ </entry>
+ <entry>Specifies whether a rule will be drawn below the rows in the span.</entry>
+ <entry><tag class="attvalue">0</tag>, <tag class="attvalue">1</tag> (default)</entry>
+ </row>
+ <row>
+ <entry>
+ <tag>align</tag>
+ </entry>
+ <entry>Specifies the horizontal alignment of the entry in the span.</entry>
+ <entry><tag class="attvalue">center</tag>, <tag class="attvalue">justify</tag>, <tag class="attvalue">right</tag>, <tag class="attvalue">left</tag> (default)</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ <note>
+ <para>Attributes not listed in <xref linkend="spanoptattrs"/> are not used in Evergreen' documentation.</para>
+ </note>
+ </simplesect>
+ <simplesect>
+ <title>Example</title>
+ <para><xref linkend="spanexample"/> shows the markup for a span that crosses
+the second and third column of a five column table. The contents of the span
+are centered.</para>
+ <example xml:id="spanexample">
+ <?dbfo pgwide="1"?>
+ <title>Defining a Span</title>
+ <programlisting><informaltable ...>
+ <tgroup cols="5" >
+ <colspec colnum="2" colname="c2" />
+ <colspec colnum="3" colname="c3" />
+ <spanspec spanname="midspan" namest="c2" nameend="c3"
+ align="center" />
+ ...
+</informaltable></programlisting>
+ </example>
+ </simplesect>
+ </section>
+ <section xml:id="TableHead">
+ <title>Adding a Heading Row to a Table</title>
+ <para>Tables in Evergreen documentation generally have one heading row. They are specified
+using a <tag class="element">thead</tag> element. The <tag class="element">thead</tag> element is a child of a
+<tag>tgroup</tag> element. It must be placed after any <tag class="element">colspec</tag> elements and <tag class="element">spanspec</tag> elements. It should also be placed before
+any <tag class="element">tbody</tag> elements.</para>
+ <simplesect>
+ <title>Attributes</title>
+ <para><xref linkend="theadattrs"/> lists the attributes of the <tag class="element">thead</tag> element.</para>
+ <table xml:id="theadattrs" pgwide="1">
+ <title>Attributes for the <tag class="element">thead</tag> Element</title>
+ <tgroup cols="3">
+ <colspec colwidth="1.5in"/>
+ <thead>
+ <row>
+ <entry align="center">Attribute</entry>
+ <entry align="center">Description</entry>
+ <entry align="center">Values</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>
+ <tag>valign</tag>
+ </entry>
+ <entry>Specifies the vertical alignment of the entry in the heading.</entry>
+ <entry><tag class="attvalue">top</tag>, <tag class="attvalue">bottom</tag>, <tag class="attvalue">middle</tag> (default)</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ </simplesect>
+ <simplesect>
+ <title>Adding content</title>
+ <para>The content of the heading row is specified using a single <tag class="element">row</tag> element and one entry <tag class="element">child</tag> element for each column in the table. For more
+information on the row element and the entry element see <xref linkend="rowsect"/> and <xref linkend="entrysect"/>.</para>
+ </simplesect>
+ <simplesect>
+ <title>Example</title>
+ <para><xref linkend="theadexample"/> shows the markup for tables used in this
+chapter.</para>
+ <example xml:id="theadexample">
+ <title>Adding a Table Header</title>
+ <programlisting><table ...>
+ <tgroup cols="3" >
+ <colspec ... />
+ <thead>
+ <row>
+ <entry align="center">
+ Attribute
+ </entry>
+ <entry align="center">
+ Description
+ </entry>
+ <entry align="center">
+ Values
+ </entry>
+ </row>
+ </thead>
+ ...
+ </tgroup>
+</informaltable></programlisting>
+ </example>
+ </simplesect>
+ </section>
+ <section xml:id="TableRows">
+ <title>Adding Rows to a Table</title>
+ <para>The rows that make up the body of a table are defined inside of a
+<tag class="element">tbody</tag> element. Each row in the table is
+defined using a <tag class="element">row</tag> element. The contents
+of each column in the row is defined using an <tag class="element">entry</tag> element.</para>
+ <simplesect>
+ <title>The <tag class="element">tbody</tag> Element</title>
+ <para>The <tag class="element">tbody</tag> element is a wrapper for
+all of the rows in the body of a group. It is placed after all of the <tag class="element">colspec</tag> elements, all of the <tag class="element">spanspec</tag> elements, and the <tag class="element">thead</tag> element. It has a single attribute, <tag class="attribute">valign</tag>, that is described in <xref linkend="theadattrs"/>.</para>
+ </simplesect>
+ <simplesect xml:id="rowsect">
+ <title>The <tag class="element">row</tag> Element</title>
+ <para>Rows in a table are defined using the <tag>row</tag> element.
+Each <tag>row</tag> element wraps a number of <tag>entry</tag>
+children elements that cannot exceed the number columns specified in the
+<tag>tgroup</tag> element's <tag>cols</tag> attribute. It is
+possible to have less <tag>entry</tag> child elements. This can happen
+when you wish to have empty columns, when one entry spans multiple columns, or
+if there is an entry from a previous row that vertically spans the row being
+specified.</para>
+ <important>
+ <para>When spans are being used the number of <tag>entry</tag>
+elements plus the number of columns being spanned cannot add up to more than
+the number of columns defined for the group.</para>
+ </important>
+ <para>The <tag class="element">row</tag> element has two attributes as
+described in <xref linkend="rowattrs"/>. Attributes in the <tag class="element">row</tag> element override corresponding attributes in the
+parent <tag class="element">tbody</tag> element, the enclosing
+<tag class="element">tgroup</tag> element, the <tag class="element">colspec</tag> elements in the group, and the table's root
+element.</para>
+ <table xml:id="rowattrs" pgwide="1">
+ <title>Attributes for the <tag class="element">row</tag> Element</title>
+ <tgroup cols="3">
+ <colspec colwidth="1.5in"/>
+ <thead>
+ <row>
+ <entry align="center">Attribute</entry>
+ <entry align="center">Description</entry>
+ <entry align="center">Values</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>
+ <tag class="attribute">rowsep</tag>
+ </entry>
+ <entry>Specifies whether a rule will be drawn below all of the entries in the row.</entry>
+ <entry><tag class="attvalue">0</tag>, <tag class="attvalue">1</tag> (default)</entry>
+ </row>
+ <row>
+ <entry>
+ <tag>valign</tag>
+ </entry>
+ <entry>Specifies the vertical alignment of the entry in the heading.</entry>
+ <entry><tag class="attvalue">top</tag>, <tag class="attvalue">bottom</tag>, <tag class="attvalue">middle</tag> (default)</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ </simplesect>
+ <simplesect xml:id="entrysect">
+ <title>The <tag class="element">entry</tag> Element</title>
+ <para>The contents of of a table are specified using <tag>entry</tag>
+elements. <tag>entry</tag> elements are children of the
+<tag>row</tag> element and hold the contents for a column in the
+row.</para>
+ <para>The contents of a table entry can be specified using either text with
+in-line markup elements or using block-level markup elements such as the
+<tag class="element">para</tag> element, the <tag class="element">procedure</tag> element, or one of the list types.
+However, if you intend to use one of the block-level markup elements you must
+place all of the content inside a block-level element. For example, if you
+want to use a list in a table entry, along with some text outside the list,
+you must place all of the content, including the list, inside a <tag class="element">para</tag> element.</para>
+ <para>The <tag class="element">entry</tag> element's attributes are
+described in <xref linkend="entryattrs"/>. Attributes in the <tag class="element">entry</tag> element override corresponding attributes in
+the parent <tag class="element">row</tag> element, the enclosing
+<tag class="element">tbody</tag> element, the enclosing <tag class="element">tgroup</tag> element, the <tag class="element">colspec</tag> elements in the group, the <tag class="element">spansec</tag> elements in the group, and the table's root
+element.</para>
+ <table xml:id="entryattrs" pgwide="1">
+ <title>Attributes for the <tag class="element">entry</tag> Element</title>
+ <tgroup cols="3">
+ <colspec colwidth="1.5in"/>
+ <thead>
+ <row>
+ <entry align="center">Attribute</entry>
+ <entry align="center">Description</entry>
+ <entry align="center">Values</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>
+ <tag class="attribute">rowsep</tag>
+ </entry>
+ <entry>Specifies whether a rule will be drawn below the entry.</entry>
+ <entry><tag class="attvalue">0</tag>, <tag class="attvalue">1</tag> (default)</entry>
+ </row>
+ <row>
+ <entry>
+ <tag>valign</tag>
+ </entry>
+ <entry>Specifies the vertical alignment of the entry.</entry>
+ <entry><tag class="attvalue">top</tag>, <tag class="attvalue">bottom</tag>, <tag class="attvalue">middle</tag> (default)</entry>
+ </row>
+ <row>
+ <entry>
+ <tag class="attribute">colsep</tag>
+ </entry>
+ <entry>Specifies whether a rule will be drawn to the right of the entry.</entry>
+ <entry><tag class="attvalue">0</tag>, <tag class="attvalue">1</tag> (default)</entry>
+ </row>
+ <row>
+ <entry>
+ <tag class="attribute">namest</tag>
+ </entry>
+ <entry>Specifies the name of the left-most column the entry will span.</entry>
+ <entry>The value of the <tag class="attribute">name</tag> attribute of the <tag class="element">colspec</tag> element defining the left-most column of the span.</entry>
+ </row>
+ <row>
+ <entry>
+ <tag class="attribute">nameend</tag>
+ </entry>
+ <entry>Specifies the right-most column the entry will span.</entry>
+ <entry>The value of the <tag class="attribute">name</tag> attribute of the <tag class="element">colspec</tag> element defining the right-most column of the span.</entry>
+ </row>
+ <row>
+ <entry>
+ <tag class="attribute">spanname</tag>
+ </entry>
+ <entry>Specifies a defined span to use for the entry. This attribute should not be used with <tag class="attribute">namest</tag> and <tag class="attribute">nameend</tag>.</entry>
+ <entry>The value of the <tag class="attribute">name</tag> attribute of the <tag class="element">spanspec</tag> element defining the span to use for the entry.</entry>
+ </row>
+ <row>
+ <entry>
+ <tag class="attribute">align</tag>
+ </entry>
+ <entry>Specifies the horizontal alignment of the contents in the entry.</entry>
+ <entry><tag class="attvalue">center</tag>, <tag class="attvalue">justify</tag>, <tag class="attvalue">right</tag>, <tag class="attvalue">left</tag> (default)</entry>
+ </row>
+ <row>
+ <entry>
+ <tag class="attribute">morerows</tag>
+ </entry>
+ <entry>Specifies the number of additional rows the entry will span.</entry>
+ <entry>>1</entry>
+ </row>
+ <row>
+ <entry>
+ <tag class="attribute">colname</tag>
+ </entry>
+ <entry>
+ <para>Specifies the column, defined by a <tag class="element">colspec</tag> element, in which the entry belongs.</para>
+ <para><emphasis role="bold">Note: </emphasis>You must specify entries rom left to right.</para>
+ </entry>
+ <entry>The value of the <tag class="attribute">name</tag> attribute of the <tag class="element">colspec</tag> element defining the column of the span.</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ <note>
+ <para>Attributes not listed in <xref linkend="entryattrs"/> are not used in Evergreen' documentation.</para>
+ </note>
+ </simplesect>
+ <simplesect>
+ <title>Example</title>
+ <para><xref linkend="tbodyexample"/> shows the markup for tables used in this
+chapter.</para>
+ <example xml:id="tbodyexample">
+ <?dbfo pgwide="1"?>
+ <title>Add Rows to a Table</title>
+ <programlisting><table ...>
+ <tgroup cols="3" >
+ <colspec ... />
+ ...
+ <tbody>
+ <row>
+ <entry>
+ <tag class="attribute">colsep</tag>
+ </entry>
+ <entry>Specifies whether a rule will be drawn to
+ the right of entries in the span.</entry>
+ <entry>
+ <tag class="attvalue">0</tag>,
+ <tag class="attvalue">1</tag>
+ (default)</entry>
+ </row>
+ <row>
+ <entry>
+ <tag class="attribute">rowsep</tag>
+ </entry>
+ <entry>Specifies whether a rule will be drawn below
+ the rows in the span.</entry>
+ <entry>
+ <tag class="attvalue">0</tag>,
+ <tag class="attvalue">1</tag>
+ (default)</entry>
+ </row>
+ <row>
+ <entry><tag>align</tag></entry>
+ <entry>Specifies the horizontal alignment of
+ the entry in the span.</entry>
+ <entry>
+ <tag class="attvalue">center</tag>,
+ <tag class="attvalue">justify</tag>,
+ <tag class="attvalue">right</tag>,
+ <tag class="attvalue">left</tag>
+ (default)</entry>
+ </row>
+ </tbody>
+ </tgroup>
+</informaltable></programlisting>
+ </example>
+ </simplesect>
+ </section>
+ <section>
+ <title>Example</title>
+ <para><xref linkend="tableexample"/> shows a table that uses most of the
+features of a table.</para>
+ <table xml:id="tableexample" pgwide="1">
+ <title>Complicated Table</title>
+ <tgroup cols="6">
+ <colspec colnum="1" colname="c1" align="center"/>
+ <colspec colnum="2" colname="c2" align="justify"/>
+ <colspec colname="c3"/>
+ <colspec colnum="4" colname="c4"/>
+ <colspec colnum="5" colname="c5" align="right"/>
+ <colspec colname="c6" align="left"/>
+ <spanspec namest="c2" nameend="c5" spanname="25" align="center"/>
+ <spanspec namest="c1" nameend="c4" spanname="14" align="left"/>
+ <thead>
+ <row>
+ <entry>c1</entry>
+ <entry>c2</entry>
+ <entry>c3</entry>
+ <entry>c4</entry>
+ <entry>c5</entry>
+ <entry>c6</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>Pomegranate</entry>
+ <entry>Pineapple</entry>
+ <entry>Mango</entry>
+ <entry>Carambola</entry>
+ <entry>Banana</entry>
+ <entry>Papaya</entry>
+ </row>
+ <row>
+ <entry>Apples</entry>
+ <entry align="right">Kiwis</entry>
+ <entry namest="c3" nameend="c5" align="center">Passion Fruits</entry>
+ <entry>Watermelon</entry>
+ </row>
+ <row>
+ <entry spanname="14">Strawberries</entry>
+ <entry>Cantaloupe</entry>
+ <entry>Tamarind</entry>
+ </row>
+ <row>
+ <entry>Lichee</entry>
+ <entry spanname="25">Boysenberry</entry>
+ <entry>Guava</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ <para><xref linkend="tablemarkup"/> shows the markup for <xref linkend="tableexample"/>.</para>
+ <example xml:id="tablemarkup">
+ <?dbfo pgwide="1"?>
+ <title>Markup for a Table</title>
+ <programlisting><table xml:id="tableexample" pgwide="1">
+ <title>Complicated Table</title>
+ <tgroup cols="6">
+ <colspec align="center" colname="c1" colnum="1" />
+ <colspec align="justify" colname="c2" colnum="2" />
+ <colspec colname="c3" />
+ <colspec colname="c4" colnum="4" />
+ <colspec align="right" colname="c5" colnum="5" />
+ <colspec align="left" colname="c6" />
+ <spanspec align="center" nameend="c5" namest="c2"
+ spanname="25" />
+ <spanspec align="left" nameend="c4" namest="c1"
+ spanname="14" />
+ <thead>
+ <row>
+ <entry>c1</entry>
+ <entry>c2</entry>
+ <entry>c3</entry>
+ <entry>c4</entry>
+ <entry>c5</entry>
+ <entry>c6</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>Pomegranate</entry>
+ <entry>Pineapple</entry>
+ <entry>Mango</entry>
+ <entry>Carambola</entry>
+ <entry>Banana</entry>
+ <entry>Papaya</entry>
+ </row>
+ <row>
+ <entry>Apples</entry>
+ <entry align="right">Kiwis</entry>
+ <entry align="center" nameend="c5"
+ namest="c3">Passion
+ Fruits</entry>
+ <entry>Watermelon</entry>
+ </row>
+ <row>
+ <entry spanname="14">Strawberries</entry>
+ <entry>Cantaloupe</entry>
+ <entry>Tamarind</entry>
+ </row>
+ <row>
+ <entry>Lichee</entry>
+ <entry spanname="25">Boysenberry</entry>
+ <entry>Guava</entry>
+ </row>
+ </tbody>
+ </tgroup>
+</table></programlisting>
+ </example>
+ </section>
+ </section>
+</chapter>
More information about the open-ils-commits
mailing list