+++ /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="authoring">\r
- <title>Authoring Documentation</title>\r
- <info>\r
- <abstract>\r
- <para>DocBook ....</para>\r
- </abstract>\r
- </info>\r
- <section>\r
- <title>Structure: Concept, Task, Reference</title>\r
- <para> Every chapter in Evergreen documentation, and in some cases sections, should begin by\r
- explaining this chapter's concepts, or core ideas, to the reader. This gives you the\r
- opportunity to clarify new or ambiguous terminology for otherwise experienced readers:\r
- for example, in a circulation overview you will want to differentiate non-cataloged\r
- items vs. pre-cataloged items. Explaining concepts also gives less experienced readers a\r
- chance to fill in gaps in their knowledge. </para>\r
- <para> For example, in the circulation section of the manual, you may write the following\r
- set of tasks: </para>\r
- <itemizedlist>\r
- <listitem>\r
- <para>Checking out an item Checking in an item Renewing items Recording in-house\r
- uses</para>\r
- </listitem>\r
- </itemizedlist>\r
- <para> Separating the concepts from the tasks gives your readers the chance to jump directly\r
- to the task they want to complete, if they are already familiar with the concepts. </para>\r
- <para> When you write your task information, try to organize it as a set of numbered steps\r
- that covers the most common cases. Compose each step in two sentences: first, describe\r
- the action the reader must complete, followed by a sentence describing the results of\r
- successfully performing the action if applicable. Preface optional steps with\r
- (Optional):. For example: </para>\r
- <para> To check out a cataloged item to a patron: </para>\r
- <orderedlist>\r
- <listitem>\r
- <para>In the staff client, select Circulation→Check Out Items. The Check Out tab\r
- appears.</para>\r
- </listitem>\r
- <listitem>\r
- <para>Enter the patron barcode in the Barcode text field. The system retrieves and\r
- displays the patron information, with the Check Out button highlighted in the\r
- action bar.</para>\r
- </listitem>\r
- <listitem>\r
- <para>Enter the item barcode in the text field beside the Barcode: selection in the\r
- drop-down menu.</para>\r
- </listitem>\r
- </orderedlist>\r
- <!-- the following was copied from the wiki and has not been marked up yet. It is wrapped\r
- with para elements so that it will not trigger the XML validator -->\r
- \r
- <para>(Optional): Select a different due date from the date selector. 4. Click Submit to\r
- check out the item to the patron. The item barcode, due date, and title appear in the\r
- transaction summary table. 5. Repeat steps 3 and 4 for each additional item the patron\r
- wants to borrow. 6. (Optional): Click Print Receipt to print a receipt summarizing the\r
- transactions for the patron. The Print Receipt window opens. Reference Reference\r
- information consists of lists of commands, configuration files and settings, software\r
- prerequisites, APIs, etc that need to be rigorously documented to support use cases\r
- outside the core task documentation. Reference information is typically organized by\r
- type, then by alphabetical order. For example, all system commands will be documented in\r
- their own section of the manual in alphabetical order, and all APIs will be documented\r
- in their own section of the manual in alphabetical order. System commmands: * autogen.sh\r
- * import_holdings.pl * marc2bre.pl * osrf_ctl.sh * … APIs: *\r
- open-ils.auth.authenticate.complete * open-ils.auth.authenticate.init * … Discuss how\r
- each system feature would be used by each scenario institution If applicable, provide an\r
- example of how each institutional scenario (Le Grande University vs. Metropolitan Public\r
- Library Consortium) would likely put the feature being discussed into use. You will\r
- probably want to include this information in the concept topic(s) introducing the\r
- feature, or as a separate concept topic or set of topics following the introductory\r
- concept topic. The scenarios give you a few different facets to describe when explaining\r
- the topic to your reader: * academic vs. public libraries * consortiums vs. standalone\r
- libraries * libraries with large collections vs. libraries with small collections Style\r
- guidelines Use the active voice Avoid the passive voice. For example: Rather than: The\r
- barcode is checked for a valid check digit when it is scanned. Use the active voice:\r
- When you scan the barcode, the system checks for a valid check digit. If your sentence\r
- contains “is”, be careful: it might be using the passive voice. Write concise sentences\r
- Try to keep your sentences brief. Avoiding complex phrases with related clauses helps\r
- readers concentrate on a single idea at a time. It also helps translators. Prefix\r
- conditional clauses If your sentence is conditional, place the conditional clause at the\r
- beginning of the sentence. When your reader skims your text and only sees the first part\r
- of the sentence, they might take the wrong action. For example: Rather than: Click the\r
- **Cancel** button to prevent the changes from being applied if the results did not match\r
- your expectations. Use: If the results did not match your expectations, click the\r
- **Cancel** button to prevent the changes from being applied. Contractions,\r
- abbreviations, and acronyms Do not use contractions (“you're”, “we've”, “it's”) or Latin\r
- abbreviations (e.g., etc., i.e.). These can be hard to translate and hard to read. If\r
- you use an acronym, provide the full form of the acronym and include the acronym in\r
- parentheses in the first use in your topic. After the acronym has been introduced, you\r
- can use the acronym on its own for the remainder of the topic. Highlighting Use bold to\r
- highlight the names of GUI elements such as field and button labels, window names, and\r
- menu options. </para>\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