[open-ils-commits] r678 - evergreen-ils.org/docs/styleguide (kgs)
svn at svn.open-ils.org
svn at svn.open-ils.org
Wed Sep 9 15:51:13 EDT 2009
Author: kgs
Date: 2009-09-09 15:51:08 -0400 (Wed, 09 Sep 2009)
New Revision: 678
Removed:
evergreen-ils.org/docs/styleguide/admon.xml
evergreen-ils.org/docs/styleguide/authoring.xml
evergreen-ils.org/docs/styleguide/books.xml
evergreen-ils.org/docs/styleguide/build.xml
evergreen-ils.org/docs/styleguide/chapter.xml
evergreen-ils.org/docs/styleguide/conditional.xml
evergreen-ils.org/docs/styleguide/exclude.xml
evergreen-ils.org/docs/styleguide/figures.xml
evergreen-ils.org/docs/styleguide/filenames.xml
evergreen-ils.org/docs/styleguide/general.xml
evergreen-ils.org/docs/styleguide/glossary.xml
evergreen-ils.org/docs/styleguide/indexterms.xml
evergreen-ils.org/docs/styleguide/links.xml
evergreen-ils.org/docs/styleguide/lists.xml
evergreen-ils.org/docs/styleguide/overview.xml
evergreen-ils.org/docs/styleguide/programming.xml
evergreen-ils.org/docs/styleguide/structure.xml
evergreen-ils.org/docs/styleguide/styleguide.xml
evergreen-ils.org/docs/styleguide/tables.xml
Log:
Checked into the wrong repository, removing.
Deleted: evergreen-ils.org/docs/styleguide/admon.xml
===================================================================
--- evergreen-ils.org/docs/styleguide/admon.xml 2009-09-09 19:49:06 UTC (rev 677)
+++ evergreen-ils.org/docs/styleguide/admon.xml 2009-09-09 19:51:08 UTC (rev 678)
@@ -1,104 +0,0 @@
-<?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>
Deleted: evergreen-ils.org/docs/styleguide/authoring.xml
===================================================================
--- evergreen-ils.org/docs/styleguide/authoring.xml 2009-09-09 19:49:06 UTC (rev 677)
+++ evergreen-ils.org/docs/styleguide/authoring.xml 2009-09-09 19:51:08 UTC (rev 678)
@@ -1,93 +0,0 @@
-<?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>
Deleted: evergreen-ils.org/docs/styleguide/books.xml
===================================================================
--- evergreen-ils.org/docs/styleguide/books.xml 2009-09-09 19:49:06 UTC (rev 677)
+++ evergreen-ils.org/docs/styleguide/books.xml 2009-09-09 19:51:08 UTC (rev 678)
@@ -1,256 +0,0 @@
-<?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>
Deleted: evergreen-ils.org/docs/styleguide/build.xml
===================================================================
--- evergreen-ils.org/docs/styleguide/build.xml 2009-09-09 19:49:06 UTC (rev 677)
+++ evergreen-ils.org/docs/styleguide/build.xml 2009-09-09 19:51:08 UTC (rev 678)
@@ -1,37 +0,0 @@
-<?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
Deleted: evergreen-ils.org/docs/styleguide/chapter.xml
===================================================================
--- evergreen-ils.org/docs/styleguide/chapter.xml 2009-09-09 19:49:06 UTC (rev 677)
+++ evergreen-ils.org/docs/styleguide/chapter.xml 2009-09-09 19:51:08 UTC (rev 678)
@@ -1,117 +0,0 @@
-<?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>
Deleted: evergreen-ils.org/docs/styleguide/conditional.xml
===================================================================
--- evergreen-ils.org/docs/styleguide/conditional.xml 2009-09-09 19:49:06 UTC (rev 677)
+++ evergreen-ils.org/docs/styleguide/conditional.xml 2009-09-09 19:51:08 UTC (rev 678)
@@ -1,203 +0,0 @@
-<?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>
Deleted: evergreen-ils.org/docs/styleguide/exclude.xml
===================================================================
--- evergreen-ils.org/docs/styleguide/exclude.xml 2009-09-09 19:49:06 UTC (rev 677)
+++ evergreen-ils.org/docs/styleguide/exclude.xml 2009-09-09 19:51:08 UTC (rev 678)
@@ -1,370 +0,0 @@
-<?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>
Deleted: evergreen-ils.org/docs/styleguide/figures.xml
===================================================================
--- evergreen-ils.org/docs/styleguide/figures.xml 2009-09-09 19:49:06 UTC (rev 677)
+++ evergreen-ils.org/docs/styleguide/figures.xml 2009-09-09 19:51:08 UTC (rev 678)
@@ -1,169 +0,0 @@
-<?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>
Deleted: evergreen-ils.org/docs/styleguide/filenames.xml
===================================================================
--- evergreen-ils.org/docs/styleguide/filenames.xml 2009-09-09 19:49:06 UTC (rev 677)
+++ evergreen-ils.org/docs/styleguide/filenames.xml 2009-09-09 19:51:08 UTC (rev 678)
@@ -1,76 +0,0 @@
-<?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>
Deleted: evergreen-ils.org/docs/styleguide/general.xml
===================================================================
--- evergreen-ils.org/docs/styleguide/general.xml 2009-09-09 19:49:06 UTC (rev 677)
+++ evergreen-ils.org/docs/styleguide/general.xml 2009-09-09 19:51:08 UTC (rev 678)
@@ -1,208 +0,0 @@
-<?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>
Deleted: evergreen-ils.org/docs/styleguide/glossary.xml
===================================================================
--- evergreen-ils.org/docs/styleguide/glossary.xml 2009-09-09 19:49:06 UTC (rev 677)
+++ evergreen-ils.org/docs/styleguide/glossary.xml 2009-09-09 19:51:08 UTC (rev 678)
@@ -1,18 +0,0 @@
-<?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>
Deleted: evergreen-ils.org/docs/styleguide/indexterms.xml
===================================================================
--- evergreen-ils.org/docs/styleguide/indexterms.xml 2009-09-09 19:49:06 UTC (rev 677)
+++ evergreen-ils.org/docs/styleguide/indexterms.xml 2009-09-09 19:51:08 UTC (rev 678)
@@ -1,74 +0,0 @@
-<?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>
Deleted: evergreen-ils.org/docs/styleguide/links.xml
===================================================================
--- evergreen-ils.org/docs/styleguide/links.xml 2009-09-09 19:49:06 UTC (rev 677)
+++ evergreen-ils.org/docs/styleguide/links.xml 2009-09-09 19:51:08 UTC (rev 678)
@@ -1,489 +0,0 @@
-<?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>
Deleted: evergreen-ils.org/docs/styleguide/lists.xml
===================================================================
--- evergreen-ils.org/docs/styleguide/lists.xml 2009-09-09 19:49:06 UTC (rev 677)
+++ evergreen-ils.org/docs/styleguide/lists.xml 2009-09-09 19:51:08 UTC (rev 678)
@@ -1,400 +0,0 @@
-<?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>
Deleted: evergreen-ils.org/docs/styleguide/overview.xml
===================================================================
--- evergreen-ils.org/docs/styleguide/overview.xml 2009-09-09 19:49:06 UTC (rev 677)
+++ evergreen-ils.org/docs/styleguide/overview.xml 2009-09-09 19:51:08 UTC (rev 678)
@@ -1,149 +0,0 @@
-<?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>
Deleted: evergreen-ils.org/docs/styleguide/programming.xml
===================================================================
--- evergreen-ils.org/docs/styleguide/programming.xml 2009-09-09 19:49:06 UTC (rev 677)
+++ evergreen-ils.org/docs/styleguide/programming.xml 2009-09-09 19:51:08 UTC (rev 678)
@@ -1,493 +0,0 @@
-<?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
Deleted: evergreen-ils.org/docs/styleguide/structure.xml
===================================================================
--- evergreen-ils.org/docs/styleguide/structure.xml 2009-09-09 19:49:06 UTC (rev 677)
+++ evergreen-ils.org/docs/styleguide/structure.xml 2009-09-09 19:51:08 UTC (rev 678)
@@ -1,133 +0,0 @@
-<?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>
Deleted: evergreen-ils.org/docs/styleguide/styleguide.xml
===================================================================
--- evergreen-ils.org/docs/styleguide/styleguide.xml 2009-09-09 19:49:06 UTC (rev 677)
+++ evergreen-ils.org/docs/styleguide/styleguide.xml 2009-09-09 19:51:08 UTC (rev 678)
@@ -1,26 +0,0 @@
-<?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>
Deleted: evergreen-ils.org/docs/styleguide/tables.xml
===================================================================
--- evergreen-ils.org/docs/styleguide/tables.xml 2009-09-09 19:49:06 UTC (rev 677)
+++ evergreen-ils.org/docs/styleguide/tables.xml 2009-09-09 19:51:08 UTC (rev 678)
@@ -1,818 +0,0 @@
-<?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