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