Add DocBook style guide from Jeremy Buhler.

diff --git a/style_guide/glossary.xml b/style_guide/glossary.xml
new file mode 100644 (file)
index 0000000..ccd9243
--- /dev/null
+++ b/style_guide/glossary.xml
@@ -0,0 +1,597 @@
+<?xml version="1.0" encoding="utf-8"?>\r
+<chapter xml:id="style-glossary" xmlns="http://docbook.org/ns/docbook" version="5.0" xml:lang="EN"\r
+    xmlns:xi="http://www.w3.org/2001/XInclude" xmlns:xlink="http://www.w3.org/1999/xlink">\r
+    <info>\r
+        <title>DIG DocBook reference</title>\r
+    </info>\r
+    <section>\r
+        <info>\r
+            <title>Elements</title>\r
+        </info>\r
+        <para>Below is a non-exhaustive list of DocBook elements used in Evergreen documentation.\r
+            Authors may use other elements but are encouraged to draw from this list first. Each\r
+            term links to the authoritative DocBook 5 reference pages at <link\r
+                xlink:href="http://www.docbook.org/tdg5/en/html/"\r
+                >http://www.docbook.org/tdg5/en/html/part2.html</link>.</para>\r
+        <glossary>\r
+            <title/>\r
+            <glossentry xml:id="section">\r
+                <glossterm>\r
+                    <link xlink:href="http://www.docbook.org/tdg5/en/html/section.html"\r
+                        >section</link>\r
+                </glossterm>\r
+                <glossdef>\r
+                    <para>A titled subdivision of a <markup linkend="chapter">chapter</markup>, only\r
+                        required if a chapter has two or more sections. Sections appear in TOC and\r
+                        have their own pages in HTML output (use <markup linkend="simplesect"\r
+                            >simplesect</markup> to exclude from TOC). The <markup linkend="xmlid"\r
+                            >xml:id</markup> attribute is optional and can be applied ad hoc when\r
+                        linking to a section.</para>\r
+                    <para>The section element can be nested to\r
+                        create subsections. Here are some examples used in <emphasis>The Book of Evergreen</emphasis>: </para>\r
+                    <itemizedlist>\r
+                        <listitem>\r
+                            <para><emphasis>section -> section</emphasis> (for a section and\r
+                                subsection, both appearing in TOC)</para>\r
+                        </listitem>\r
+                        <listitem>\r
+                            <para><emphasis>section -> simplesect</emphasis> (for a section and\r
+                                subsection, w/ only the top level in the TOC)</para>\r
+                        </listitem>\r
+                        <listitem>\r
+                            <para><emphasis>section -> section -> simplesect</emphasis> (for a\r
+                                section, subsection, and sub-subsection, with the top 2 in the\r
+                                TOC))</para>\r
+                        </listitem>\r
+                    </itemizedlist>\r
+                </glossdef></glossentry>\r
+            <glossentry xml:id="xref">\r
+                <glossterm>\r
+                    <link xlink:href="http://www.docbook.org/tdg5/en/html/xref.html">xref</link>\r
+                </glossterm>\r
+                <glossdef>\r
+                    <para>A cross reference to another part of the document (use <markup\r
+                            linkend="link">link</markup> for external links). The destination is set\r
+                        with the <markup linkend="linkend">linkend</markup> attribute, which matches\r
+                        the <markup linkend="xmlid">xml:id</markup> of the destination element. Link\r
+                        text is auto-generated.</para>\r
+                    <para><application>oXygen</application> returns a validation error if the link\r
+                        destination is in another xml file; this is resolved when the files are\r
+                        assembled for publication and can be ignored.</para>\r
+                </glossdef></glossentry>\r
+            <glossentry xml:id="guimenu">\r
+                <glossterm>\r
+                    <link xlink:href="http://www.docbook.org/tdg5/en/html/guimenu.html"\r
+                        >guimenu</link>\r
+                </glossterm>\r
+                <glossdef>\r
+                    <para>Use for the names of staff client menus; formatted in italics.</para>\r
+                </glossdef></glossentry>\r
+            <glossentry xml:id="menuchoice">\r
+                <glossterm>\r
+                    <link xlink:href="http://www.docbook.org/tdg5/en/html/menuchoice.html"\r
+                        >menuchoice</link>\r
+                </glossterm>\r
+                <glossdef>\r
+                    <para>Use to describe a menu selection. Usually contains <markup\r
+                            linkend="guimenu">guimenu</markup> and <markup linkend="guimenuitem"\r
+                            >guimenitiem</markup> elements (may also contain <markup\r
+                            linkend="guisubmenu">guisubmenu</markup>). Output displays an arrow\r
+                        between each child element. <programlisting><![CDATA[ \r
+    <para>To clear the staff client cache go to\r
+       <menuchoice>\r
+           <guimenu>Admin</guimenu>  \r
+           <guisubmenu>For developers</guisubmenu>\r
+           <guisubmenuitem>Clear Cache</guisubmenuitem>\r
+       </menuchoice>\r
+    </para>]]>\r
+    \r
+                            </programlisting> displays as <informalexample>\r
+                            <para>To clear the staff client cache go to <menuchoice>\r
+                                    <guimenu>Admin</guimenu>\r
+                                    <guisubmenu>For developers</guisubmenu>\r
+                                    <guimenuitem>Clear Cache</guimenuitem>\r
+                                </menuchoice>\r
+                            </para>\r
+                        </informalexample></para>\r
+                </glossdef></glossentry>\r
+            <glossentry xml:id="guimenuitem">\r
+                <glossterm>\r
+                    <link xlink:href="http://www.docbook.org/tdg5/en/html/guimenuitem.html"\r
+                        >guimenuitem</link>\r
+                </glossterm>\r
+                <glossdef>\r
+                    <para>An option in a staff client menu or submenu; formatted in italics.</para>\r
+                </glossdef></glossentry>\r
+            <glossentry xml:id="guibutton">\r
+                <glossterm>\r
+                    <link xlink:href="http://www.docbook.org/tdg5/en/html/guibutton.html"\r
+                        >guibutton</link>\r
+                </glossterm>\r
+                <glossdef>\r
+                    <para>A button in the staff client. Currently formatted with italics, though this can be changed in the stylesheets.<programlisting><![CDATA[ \r
+<para>Click <guibutton>Modify Copies</guibutton> to save your changes</para>]]>                       \r
+\r
+                        </programlisting>\r
+                        displays as<informalexample>\r
+                            <para>Click <guibutton>Modify Copies</guibutton> to save your\r
+                                changes</para>\r
+                        </informalexample></para>\r
+                </glossdef></glossentry>\r
+            <glossentry xml:id="informalfigure">\r
+                <glossterm>\r
+                    <link xlink:href="http://www.docbook.org/tdg5/en/html/informalfigure.html"\r
+                        >informalfigure</link>\r
+                </glossterm>\r
+                <glossdef>\r
+                    <para>A wrapper for a <markup>mediaobject</markup> and optional\r
+                        associated text. Stylesheet customizations ensure the contents of an informfigure are kept together during PDF pagination. The\r
+                            <markup linkend="step">step</markup> in the following example will not\r
+                        split across a page break: <programlisting>    <![CDATA[ \r
+<step>\r
+    <informalfigure>\r
+        <para>STEP TEXT GOES HERE</para>  \r
+        <mediaobject>\r
+            <alt>OPTIONAL DESCRIPTION OF IMAGE</alt>\r
+            <imageobject>\r
+                <imagedata  scalefit="0" fileref="media/FILENAME_HERE.png"/>\r
+            </imageobject>\r
+        </mediaobject>\r
+    </informalfigure>\r
+</step>]]>\r
+        \r
+                        </programlisting></para>\r
+                </glossdef></glossentry>\r
+            <glossentry xml:id="figure">\r
+                <glossterm>\r
+                    <link xlink:href="http://www.docbook.org/tdg5/en/html/figure.html">figure</link>\r
+                </glossterm>\r
+                <glossdef>\r
+                    <para>Wrapper for a <markup linkend="mediaobject">mediaobject</markup> that has\r
+                        a title and appears in list of figures (in the book's front matter). Content in <markup\r
+                            linkend="figure">figure</markup> and <markup linkend="informalfigure"\r
+                            >informalfigure</markup> is not split across PDF page breaks.</para>\r
+                </glossdef></glossentry>\r
+            <glossentry xml:id="example">\r
+                <glossterm>\r
+                    <link xlink:href="http://www.docbook.org/tdg5/en/html/example.html"\r
+                        >example</link>\r
+                </glossterm>\r
+                <glossdef>\r
+                    <para>An example with a title.</para>\r
+                </glossdef></glossentry>\r
+            <glossentry xml:id="informalexample">\r
+                <glossterm>\r
+                    <link xlink:href="http://www.docbook.org/tdg5/en/html/informalexample.html"\r
+                        >informalexample</link>\r
+                </glossterm>\r
+                <glossdef>\r
+                    <para>An example with no title.</para>\r
+                </glossdef></glossentry>\r
+            <glossentry xml:id="formalpara">\r
+                <glossterm>\r
+                    <link xlink:href="http://www.docbook.org/tdg5/en/html/formalpara.html"\r
+                        >formalpara</link>\r
+                </glossterm>\r
+                <glossdef>\r
+                    <para>A titled paragraph. The following <programlisting><![CDATA[ \r
+<formalpara>\r
+    <title>Paragraph title</title>\r
+    <para>Paragraph body...</para>  \r
+</formalpara>]]>                       \r
+                        \r
+                    </programlisting>\r
+                        displays as<informalexample>\r
+                            <formalpara>\r
+                                <title>Paragraph title</title>\r
+                                <para>Paragraph body...</para>\r
+                            </formalpara>\r
+                        </informalexample></para>\r
+                </glossdef></glossentry>\r
+            <glossentry xml:id="mediaobject">\r
+                <glossterm>\r
+                    <link xlink:href="http://www.docbook.org/tdg5/en/html/mediaobject.html"\r
+                        >mediaobject</link>\r
+                </glossterm>\r
+                <glossdef>\r
+                    <para>A wrapper for <markup linkend="imageobject"\r
+                            >imageobjects</markup>. May be wrapped in an\r
+                            <markup linkend="informalfigure">informalfigure</markup> to keep image and text together across page breaks. See <xref linkend="style-image"/> for more\r
+                        on image formatting.</para>\r
+                </glossdef></glossentry>\r
+            <glossentry xml:id="alt">\r
+                <glossterm>\r
+                    <link xlink:href="http://www.docbook.org/tdg5/en/html/alt.html">alt</link>\r
+                </glossterm>\r
+                <glossdef>\r
+                    <para>Metadata describing an element, usually for accessibility. For example, each <markup linkend="mediaobject">mediaobject</markup> may contain an\r
+                            alt element with a generic description of the\r
+                        image content.</para>\r
+                </glossdef></glossentry>\r
+            <glossentry xml:id="imageobject">\r
+                <glossterm>\r
+                    <link xlink:href="http://www.docbook.org/tdg5/en/html/imageobject.html"\r
+                        >imageobject</link>\r
+                </glossterm>\r
+                <glossdef>\r
+                    <para>Contained by <markup linkend="mediaobject">mediaobject</markup> and a\r
+                        wrapper for <markup linkend="imagedata">imagedata</markup>.  See <xref linkend="style-image"/> for more on\r
+                        image formatting in <emphasis>The Book of Evergreen</emphasis>.</para>\r
+                </glossdef></glossentry>\r
+            <glossentry xml:id="imagedata">\r
+                <glossterm>\r
+                    <link xlink:href="http://www.docbook.org/tdg5/en/html/imagedata.html"\r
+                        >imagedata</link>\r
+                </glossterm>\r
+                <glossdef>\r
+                    <para>Contained by <markup linkend="imageobject">imageobject</markup>, its\r
+                        attributes determine sizing, scaling, alignment, and source file. See <xref\r
+                            linkend="style-image"/> for more on Sitka image formatting. </para>\r
+                </glossdef></glossentry>\r
+            <glossentry xml:id="guilabel">\r
+                <glossterm>\r
+                    <link xlink:href="http://www.docbook.org/tdg5/en/html/guilabel.html"\r
+                        >guilabel</link>\r
+                </glossterm>\r
+                <glossdef>\r
+                    <para>Use for labels and titles in the staff client. Where applicable <markup\r
+                            linkend="guimenu">guimenu</markup>, <markup linkend="guimenuitem"\r
+                            >guimenuitem</markup>, and <markup linkend="guibutton"\r
+                            >guibutton</markup> are preferred. HTML is formatted in italics, PDF is\r
+                        not formatted.</para>\r
+                </glossdef></glossentry>\r
+            <glossentry xml:id="guisubmenu">\r
+                <glossterm>\r
+                    <link xlink:href="http://www.docbook.org/tdg5/en/html/guisubmenu.html"\r
+                        >guisubmenu</link>\r
+                </glossterm>\r
+                <glossdef>\r
+                    <para>A staff client submenu. Used when a submenu is part of a <markup\r
+                            linkend="menuchoice">menuchoice</markup> sequence. Not italicized.\r
+                    </para>\r
+                </glossdef></glossentry>\r
+            <glossentry xml:id="keycap">\r
+                <glossterm>\r
+                    <link xlink:href="http://www.docbook.org/tdg5/en/html/keycap.html">keycap</link>\r
+                </glossterm>\r
+                <glossdef>\r
+                    <para>The label on a keyboard button; formatted in bold (eg Press\r
+                            <keycap>F5</keycap>).</para>\r
+                </glossdef></glossentry>\r
+            <glossentry xml:id="keycombo">\r
+                <glossterm>\r
+                    <link xlink:href="http://www.docbook.org/tdg5/en/html/keycap.html">keycap</link>\r
+                </glossterm>\r
+                <glossdef>\r
+                    <para>For a combination of two or more keystrokes, wrap <markup linkend="keycap"\r
+                            >keycap</markup> elements in a keycombo. Format is bold with a + between\r
+                        keystrokes. <programlisting><![CDATA[ \r
+<para>Open a new tab with\r
+    <keycombo>\r
+        <keycap>Ctrl</keycap>\r
+        <keycap>T</keycap>\r
+    </keycombo>\r
+</para> ]]>                       \r
+\r
+                        </programlisting> displays as<informalexample>\r
+                            <para>Open a new tab with <keycombo>\r
+                                    <keycap>Ctrl</keycap>\r
+                                    <keycap>T</keycap>\r
+                                </keycombo>\r
+                            </para>\r
+                        </informalexample></para>\r
+                </glossdef></glossentry>\r
+            <glossentry xml:id="application">\r
+                <glossterm>\r
+                    <link xlink:href="http://www.docbook.org/tdg5/en/html/application.html"\r
+                        >application</link>\r
+                </glossterm>\r
+                <glossdef>\r
+                    <para>The name of a software program or application such as\r
+                            <application>Evergreen</application>. Currently not formatted, but\r
+                        consistent use would allow for future batch formatting (e.g. italicize content of all application tags).</para>\r
+                </glossdef></glossentry>\r
+            <glossentry xml:id="emphasis">\r
+                <glossterm>\r
+                    <link xlink:href="http://www.docbook.org/tdg5/en/html/emphasis.html"\r
+                        >emphasis</link>\r
+                </glossterm>\r
+                <glossdef>\r
+                    <para>Use to <emphasis>italicize</emphasis> regular text.  Use with the ROLE attribute for <emphasis role="bold">bold</emphasis> text</para>\r
+                    <para><programlisting><![CDATA[ \r
+<para>For <emphasis>italic</emphasis> and <emphasis role="bold">bold</emphasis> output.</para>\r
+]]>                       \r
+\r
+                    </programlisting> displays as<informalexample>\r
+                        <para>For <emphasis>italic</emphasis> and <emphasis role="bold">bold</emphasis> output.</para>\r
+                        \r
+                    </informalexample> </para>\r
+                </glossdef></glossentry>\r
+            <glossentry xml:id="tip">\r
+                <glossterm>\r
+                    <link xlink:href="http://www.docbook.org/tdg5/en/html/tip.html">tip</link>\r
+                </glossterm>\r
+                <glossdef>\r
+                    <para>Enclose tip text and images in this element for consistent formatting.\r
+                        Display options are set with CSS and XSL stylesheets and include custom tip\r
+                        text, icons, formatting, etc.\r
+                    \r
+                    <programlisting><![CDATA[ \r
+<tip>\r
+    <para>Tip text goes here</para>\r
+</tip> ]]>                       \r
+\r
+                    </programlisting> displays as<informalexample>\r
+                        <tip>\r
+                            <para>Tip text goes here       \r
+                            </para>\r
+                        </tip>\r
+                    </informalexample> </para>\r
+                    \r
+                </glossdef></glossentry>\r
+            <glossentry xml:id="glossary">\r
+                <glossterm>\r
+                    <link xlink:show="new" xlink:href="http://www.docbook.org/tdg5/en/html/glossary.html"\r
+                        >glossary</link>\r
+                </glossterm>\r
+                <glossdef>\r
+                    <para>Wrapper for a glossary.  Must contain <markup\r
+                            linkend="title">title</markup> element (to hide the title in published\r
+                        output use an empty <markup><![CDATA[<title/>]]></markup> tag).</para>\r
+                </glossdef></glossentry>\r
+            <glossentry xml:id="glossentry">\r
+                <glossterm>\r
+                    <link xlink:href="http://www.docbook.org/tdg5/en/html/glossentry.html"\r
+                        >glossentry</link>\r
+                </glossterm>\r
+                <glossdef>\r
+                    <para>Wrapper for each glossary entry. Should always have an <markup\r
+                            linkend="xmlid">xml:id</markup> for cross referencing. Entries are\r
+                        sorted alphabetically in published output, regardless of order in xml source\r
+                        document (this is optional and is set with stylesheet parameters). Full glossentry markup including child elements is shown below: <programlisting> <![CDATA[ \r
+<glossentry xml:id="guisubmenu">\r
+    <glossterm>guisubmenu</glossterm>\r
+    <glossdef>\r
+        <para>A staff client submenu. Used primarily when a submenu is part\r
+        of a <markup>menuchoice</markup> sequence.  Not italicized.</para> \r
+        <glossseealso otherterm="guimenu"/>\r
+    </glossdef>\r
+</glossentry>]]>                        \r
+                        \r
+                    </programlisting></para>\r
+                </glossdef></glossentry>\r
+            <glossentry xml:id="glossterm">\r
+                <glossterm>\r
+                    <link xlink:href="http://www.docbook.org/tdg5/en/html/glossterm.html"\r
+                        >glossterm</link>\r
+                </glossterm>\r
+                <glossdef>\r
+                    <para>Wrapper for the term in a <markup linkend="glossentry"\r
+                        >glossentry</markup>.</para>\r
+                </glossdef></glossentry>\r
+            <glossentry xml:id="glosssee">\r
+                <glossterm>\r
+                    <link xlink:href="http://www.docbook.org/tdg5/en/html/glosssee.html"\r
+                        >glosssee</link>\r
+                </glossterm>\r
+                <glossdef>\r
+                    <para>A "see" link that points from one <markup linkend="glossentry"\r
+                            >glossentry</markup> to another. Always has an <markup\r
+                            linkend="otherterm">otherterm</markup> attribute that corresponds to the\r
+                            <markup linkend="xmlid">xml:id</markup> of the referenced term.</para>\r
+                </glossdef></glossentry>\r
+            <glossentry xml:id="glossseealso">\r
+                <glossterm>\r
+                    <link xlink:href="http://www.docbook.org/tdg5/en/html/glossseealso.html"\r
+                        >glossseealso</link>\r
+                </glossterm>\r
+                <glossdef>\r
+                    <para>A "see also" link that points from one <markup linkend="glossentry"\r
+                            >glossentry</markup> to another. Always has an <markup\r
+                            linkend="otherterm">otherterm</markup> attribute corresponds to the\r
+                            <markup linkend="xmlid">xml:id</markup> of the referenced term.</para>\r
+                </glossdef></glossentry>\r
+            <glossentry xml:id="itemizedlist">\r
+                <glossterm>\r
+                    <link xlink:href="http://www.docbook.org/tdg5/en/html/itemizedlist.html"\r
+                        >itemizedlist</link>\r
+                </glossterm>\r
+                <glossdef>\r
+                    <para>A bulleted list with an optional title.</para>\r
+                </glossdef></glossentry>\r
+            <glossentry xml:id="orderedlist">\r
+                <glossterm>\r
+                    <link xlink:href="http://www.docbook.org/tdg5/en/html/orderedlist.html"\r
+                        >orderedlist</link>\r
+                </glossterm>\r
+                <glossdef>\r
+                    <para>A numbered list with an optional title.</para>\r
+                </glossdef></glossentry>\r
+            <glossentry xml:id="listitem">\r
+                <glossterm>\r
+                    <link xlink:href="http://www.docbook.org/tdg5/en/html/listitem.html"\r
+                        >listitem</link>\r
+                </glossterm>\r
+                <glossdef>\r
+                    <para>Wrapper for individual entries on an <markup linkend="itemizedlist"\r
+                            >itemizedlist</markup> or <markup linkend="orderedlist"\r
+                            >orderedlist</markup>.</para>\r
+                </glossdef></glossentry>\r
+            <glossentry xml:id="programlisting">\r
+                <glossterm>\r
+                    <link xlink:href="http://www.docbook.org/tdg5/en/html/programlisting.html"\r
+                        >programlisting</link>\r
+                </glossterm>\r
+                <glossdef>\r
+                    <para>When used with <markup><![CDATA[CDATA]]></markup>, text in a\r
+                        programlisting is published exactly as it appears in the xml file (including\r
+                        line breaks and white space). Formatted as a block with a shaded background,\r
+                        used only for coding examples (see\r
+                            <emphasis>/style/style_glossary.xml</emphasis> for syntax example).\r
+                    </para>\r
+                </glossdef></glossentry>\r
+            <glossentry xml:id="link">\r
+                <glossterm>\r
+                    <link xlink:href="http://www.docbook.org/tdg5/en/html/link.html">link</link>\r
+                </glossterm>\r
+                <glossdef>\r
+                    <para>For external links. Must have an <markup>xlink:href</markup> attribute with the destination URL. In PDF output\r
+                        the full URL is printed in brackts after the link text.</para>\r
+                </glossdef></glossentry>\r
+            <glossentry xml:id="procedure">\r
+                <glossterm>\r
+                    <link xlink:href="http://www.docbook.org/tdg5/en/html/procedure.html"\r
+                        >procedure</link>\r
+                </glossterm>\r
+                <glossdef>\r
+                    <para>A multi-step process consisting of two or more <markup linkend="step"\r
+                            >steps</markup>. Applies to most converted Sitka docs.</para>\r
+                    <glossseealso linkend="step">step</glossseealso>\r
+                </glossdef></glossentry>\r
+            <glossentry xml:id="step">\r
+                <glossterm>\r
+                    <link xlink:href="http://www.docbook.org/tdg5/en/html/step.html">step</link>\r
+                </glossterm>\r
+                <glossdef>\r
+                    <para>Component part of a <markup linkend="procedure">procedure</markup>. Steps\r
+                        are auto-numbered and may contain text, figures, examples, etc. The <markup\r
+                            linkend="xmlid">xml:id</markup> attribute is optional and only required\r
+                        if linking to a particular step. To keep step content together during\r
+                        pagination (eg text w/ associated image), use <markup\r
+                            linkend="informalfigure">informalfigure</markup>.</para>\r
+                </glossdef></glossentry>\r
+            <glossentry xml:id="para">\r
+                <glossterm>\r
+                    <link xlink:href="http://www.docbook.org/tdg5/en/html/para.html">para</link>\r
+                </glossterm>\r
+                <glossdef>\r
+                    <para>A paragraph; a required wrapper for text in most contexts.</para>\r
+                </glossdef></glossentry>\r
+            <glossentry xml:id="info">\r
+                <glossterm>\r
+                    <link xlink:href="http://www.docbook.org/tdg5/en/html/info.html">info</link>\r
+                </glossterm>\r
+                <glossdef>\r
+                    <para>A wrapper for metadata about an element, including title.</para>\r
+                </glossdef></glossentry>\r
+            <glossentry xml:id="book">\r
+                <glossterm>\r
+                    <link xlink:href="http://www.docbook.org/tdg5/en/html/book.html">book</link>\r
+                </glossterm>\r
+                <glossdef>\r
+                    <para>The top level element for Evergreen documentation, appears only in the file\r
+                            <emphasis>root.xml</emphasis></para>\r
+                </glossdef></glossentry>\r
+            <glossentry xml:id="part">\r
+                <glossterm>\r
+                    <link xlink:href="http://www.docbook.org/tdg5/en/html/part.html">part</link>\r
+                </glossterm>\r
+                <glossdef>\r
+                    <para>A subdivision of a book. Used only in\r
+                            <emphasis>root.xml</emphasis>; each part should have a <markup\r
+                            linkend="title">title</markup> and <markup linkend="xmlid"\r
+                            >xml:id</markup>.</para>\r
+                </glossdef></glossentry>\r
+            <glossentry xml:id="chapter">\r
+                <glossterm>\r
+                    <link xlink:href="http://www.docbook.org/tdg5/en/html/chapter.html">\r
+                        chapter</link>\r
+                </glossterm>\r
+                <glossdef>\r
+                    <para>A subdivision of a <markup linkend="part">part</markup>, further divided\r
+                        into <markup linkend="section">sections</markup>. In Evergreen documentation each chapter\r
+                        is a separate xml file referenced by <emphasis>root.xml</emphasis>.  Each chapter should\r
+                        have an <markup linkend="xmlid">xml:id</markup>.  The xml:id is required for cross-referencing and stable links to published html files.  If there is no xml:id the generated html files names may change as content is added or re-located.</para>\r
+                </glossdef></glossentry>\r
+            <glossentry xml:id="title">\r
+                <glossterm>\r
+                    <link xlink:href="http://www.docbook.org/tdg5/en/html/title.html">title</link>\r
+                </glossterm>\r
+                <glossdef>\r
+                    <para>Sets the title for the element which contains it. Required in \r
+                        chapters and sections.</para>\r
+                </glossdef></glossentry>\r
+           \r
+            <glossentry xml:id="date">\r
+                <glossterm>\r
+                    <link xlink:href="http://www.docbook.org/tdg5/en/html/date.html">date</link>\r
+                </glossterm>\r
+                <glossdef>\r
+                    <para>Wrapper for date info in any context. Mandatory component of chapter\r
+                            <markup linkend="revision">revision</markup> entries.  Format is YYYY-MM-DD</para>\r
+                    \r
+                </glossdef></glossentry>\r
+            <glossentry xml:id="authorinitials">\r
+                <glossterm>\r
+                    <link xlink:href="http://www.docbook.org/tdg5/en/html/authorinitials.html"\r
+                        >authorinitials</link>\r
+                </glossterm>\r
+                <glossdef>\r
+                    <para>An author's initials, mandatory componenet of the chapter <markup linkend="revision">revision</markup> element.\r
+                    </para>\r
+                </glossdef></glossentry>\r
+            <glossentry xml:id="simplesect">\r
+                <glossterm><link xlink:href="http://www.docbook.org/tdg5/en/html/simplesect.html"\r
+                        >simplesect</link></glossterm>\r
+                <glossdef>\r
+                    <para>A subdivision of a <markup linkend="section">section</markup> that does\r
+                        not appear in the TOC. A simplesect is terminal, i.e. cannot be further\r
+                        subdivided with <markup linkend="section">section</markup> or <markup\r
+                            linkend="simplesect">simplesect</markup> elements.</para>\r
+                </glossdef></glossentry>\r
+        </glossary>\r
+    </section>\r
+    <section>\r
+        <title>Attributes</title>\r
+        <para>DocBook elements can be modified by one or more attributes. The attibutes below are commonly used in <emphasis>The Book of Evergreen</emphasis>.  More info on DocBook 5 attributes is available at <link xlink:href="http://www.docbook.org/tdg5/en/html/ref-elements.html#common.attributes">http://www.docbook.org/tdg5/en/html/ref-elements.html#common.attributes</link></para>\r
+        <glossary>\r
+            <info>\r
+                <title>Attributes</title>\r
+            </info>\r
+            <glossentry xml:id="xmlid">\r
+                <glossterm>\r
+                    <link xlink:href="http://www.docbook.org/tdg5/en/html/ref-elements.html#db.cmn.xml:id">xml:id</link>\r
+                </glossterm>\r
+                <glossdef>\r
+                    <para>Optional xml identifier for an element, required for cross references and\r
+                        linking. Must be unique within the entire documentation set. Good practice is to make sure that, at minimum, all\r
+                        <markup linkend="book">book</markup>, <markup linkend="part">part</markup>, <markup linkend="chapter">chapter</markup>, and <markup linkend="glossentry">glossentry</markup> elements have an\r
+                        xml:id.  In html output, the xml:id becomes the name the html file and the URL for that segment of the documentation (if there is no xml:id, the html file is auto-numbered).</para>\r
+                    \r
+                </glossdef></glossentry>\r
+            <glossentry xml:id="linkend">\r
+                <glossterm>\r
+                    <link xlink:href="http://www.docbook.org/tdg5/en/html/ref-elements.html#db.cmn.linkend">linkend</link>\r
+                </glossterm>\r
+                <glossdef>\r
+                    <para>Attribute that sets the link destination. Any DocBook 5 inline\r
+                        element can become a link by adding a linkend attribute that corresponds to the\r
+                            <markup linkend="xmlid">xml:id</markup> of the destination. See\r
+                            <xref linkend="style-links"/> for more detailed info.</para>\r
+                </glossdef></glossentry>\r
+            <glossentry xml:id="otherterm">\r
+                <glossterm>\r
+                    <link xlink:href="http://www.docbook.org/tdg5/en/html/ref-elements.html#db.cmn.otherterm">otherterm</link>\r
+                </glossterm>\r
+                <glossdef>\r
+                    <para>Applied exclusively to <markup linkend="glosssee">glosssee</markup> and\r
+                            <markup linkend="glossseealso">glossseealso</markup> elements, it points\r
+                        to the referenced glossary term.  <programlisting><![CDATA[<glossseealso otherterm="date"/>]]></programlisting>displays as <informalexample><para>See also <link linkend="date">date</link>.</para></informalexample></para>\r
+                </glossdef></glossentry>\r
+            <glossentry xml:id="role">\r
+                <glossterm>\r
+                    <link xlink:href="http://www.docbook.org/tdg5/en/html/ref-elements.html#db.cmn.role">role</link>\r
+                </glossterm>\r
+                \r
+                    <glossdef><formalpara><title>Para</title><para>Applied to\r
+                            <markup linkend="para">para</markup> tags to track changes to draft\r
+                            docs for approval by other editors. Can have value of\r
+                            <emphasis>added</emphasis>, <emphasis>deleted</emphasis>, or\r
+                            <emphasis>changed</emphasis>; in html output will be highlighted in\r
+                            green, red, and yellow\r
+                            respectively.</para></formalpara></glossdef>\r
+                </glossentry>\r
+            \r
+        </glossary>\r
+    </section>\r
+</chapter>\r

diff --git a/style_guide/image.xml b/style_guide/image.xml
new file mode 100644 (file)
index 0000000..17c5fd0
--- /dev/null
+++ b/style_guide/image.xml
@@ -0,0 +1,104 @@
+<?xml version="1.0" encoding="utf-8"?>\r
+<chapter xml:id="style-image" xmlns="http://docbook.org/ns/docbook" version="5.0" xml:lang="EN"\r
+    xmlns:xi="http://www.w3.org/2001/XInclude" xmlns:xlink="http://www.w3.org/1999/xlink">\r
+\r
+    <info>\r
+        <title>Image Formatting</title>\r
+    </info>\r
+\r
+    <itemizedlist>\r
+        <listitem>\r
+            <para>.png is the preferred image format, though .jpg from legacy conversions are\r
+                acceptable</para>\r
+        </listitem>\r
+        <listitem>\r
+            <para>Images are stored in <emphasis>media</emphasis> directories for each <markup\r
+                    linkend="part">part</markup>.</para>\r
+        </listitem>\r
+        <listitem>\r
+            <para>Images up to 900px wide can be displayed without resizing. Images larger than\r
+                900px are scaled down with the <emphasis>scalefit="1"</emphasis> attribute as shown\r
+                below.</para>\r
+        </listitem>\r
+        <listitem>\r
+            <para>When scaling DocBook uses both the size (pixels) and resolution (dpi or pixels/in)\r
+                of image files. Source images should be at 96dpi, a default chosen to match legacy\r
+                images. 96dpi seems to be standard in FullShot; if using Gimp change the default for\r
+                new images from 72 pixels/in to 96 pixels/in under <menuchoice>\r
+                    <guimenu>File</guimenu>\r
+                    <guisubmenu>Preferences</guisubmenu>\r
+                    <guimenuitem>Default Image</guimenuitem>\r
+                </menuchoice></para>\r
+        </listitem>\r
+    </itemizedlist>\r
+\r
+    <simplesect>\r
+        <title>Images 900px wide or less</title>\r
+        <para>If the source image is 900px wide or less use the following code</para>\r
+        <programlisting><![CDATA[ \r
+    <mediaobject>\r
+        <alt>OPTIONAL DESCRIPTION OF IMAGE</alt>\r
+        <imageobject>\r
+            <imagedata scalefit="0" fileref="media/FILENAME.png"/>\r
+        </imageobject>\r
+    </mediaobject>]]>\r
+    </programlisting>\r
+\r
+        <para>In HTML output, the image will display at actual size; in PDF it will be scaled down\r
+            to 75% (scale percentage set in\r
+            <emphasis>~/stylesheets/sitka_fo_graphics.xsl</emphasis>). </para>\r
+    </simplesect>\r
+\r
+\r
+    <simplesect>\r
+        <title>Images wider than 900px</title>\r
+        <para>If the source image is wider than 900px use the following code</para>\r
+        <programlisting><![CDATA[ \r
+    <mediaobject>\r
+        <alt>OPTIONAL DESCRIPTION OF IMAGE</alt>\r
+        <imageobject>\r
+            <imagedata width="100%" scalefit="1" fileref="media/FILENAME.png"/>\r
+        </imageobject>\r
+    </mediaobject>]]>\r
+        </programlisting>\r
+\r
+        <para>In HTML the image will scale down to 900px width\r
+                (<emphasis>default.image.width</emphasis> setting in\r
+                <emphasis>~/stylesheets/sitka_xhtml.xsl</emphasis>). In PDF it will scale down to\r
+            page width. </para>\r
+\r
+        <tip>\r
+            <para>Wrap the <emphasis>mediaobject</emphasis> tag in a <emphasis>para</emphasis> to\r
+                add a small space between the image and preceding content.</para>\r
+        </tip>\r
+    </simplesect>\r
+\r
+    <simplesect>\r
+        <title>Keeping image and text together</title>\r
+        <para>Content wrapped in any formal or informal object (eg <emphasis>informalfigure,\r
+                formalfigure, informalexample, formalexample</emphasis>) is kept together on the\r
+            same page in pdf output. Use <emphasis>informalfigure</emphasis> to keep an image with\r
+            associated text, as in this example of a <emphasis>step</emphasis>:.</para>\r
+        <programlisting><![CDATA[ \r
+    <step>   \r
+       <informalfigure>\r
+          <para>STEP TEXT HERE</para>\r
+          <para>\r
+             <mediaobject>\r
+                <alt>OPTIONAL DESCRIPTION OF IMAGE</alt>\r
+                <imageobject>\r
+                   <imagedata width="100%" scalefit="1" fileref="media/FILENAME.png"/>\r
+                </imageobject>\r
+             </mediaobject>\r
+          </para>\r
+       </informalfigure>\r
+    </step>]]>\r
+        </programlisting>\r
+\r
+        \r
+\r
+    </simplesect>\r
+\r
+\r
+\r
+</chapter>\r

diff --git a/style_guide/links.xml b/style_guide/links.xml
new file mode 100644 (file)
index 0000000..b44ab66
--- /dev/null
+++ b/style_guide/links.xml
@@ -0,0 +1,61 @@
+<?xml version="1.0" encoding="utf-8"?>\r
+<chapter xml:id="style-links" xmlns="http://docbook.org/ns/docbook" version="5.0" xml:lang="EN"\r
+    xmlns:xi="http://www.w3.org/2001/XInclude" xmlns:xlink="http://www.w3.org/1999/xlink">\r
+\r
+    <info>\r
+\r
+        <title>Creating Links</title>\r
+    </info>\r
+\r
+<para>There are many way to link w/ docbook but the options in the table below cover the most common documentation scenarios.</para>\r
+\r
+\r
+    <informaltable>\r
+\r
+        <tgroup cols="4" align="left" colsep="1" rowsep="1">\r
+\r
+            <thead>\r
+                <row>\r
+                    <entry>Linking scenario</entry>\r
+                    <entry>Syntax</entry>\r
+                    <entry>Output</entry>\r
+                    <entry>Notes</entry>\r
+\r
+                </row>\r
+            </thead>\r
+\r
+\r
+\r
+            <tbody>\r
+                <row>\r
+                    <entry>Internal link with auto-generated link text</entry>\r
+                    <entry><![CDATA[ <xref linkend="style-glossary"/> ]]></entry>\r
+                    <entry>\r
+                        <xref linkend="style-glossary"/>\r
+                    </entry>\r
+                    <entry>The <emphasis>linkend</emphasis> value (<emphasis>style-glossary</emphasis>) is the xml:id of\r
+                        the target element; link text is auto-generated from the target. The tag is\r
+                        self-closing (no <![CDATA[</xref>]]> closing tag required></entry>\r
+                </row>\r
+                <row>\r
+                    <entry>Internal link with custom link text</entry>\r
+                    <entry><![CDATA[ <link linkend="style-glossary">The DIG glossary page</link> ]]></entry>\r
+                    <entry><link linkend="style-glossary">The DIG glossary page</link></entry>\r
+                    <entry><emphasis>linkend</emphasis> is the <emphasis>xml:id</emphasis> of the target element; link text is supplied by author</entry>\r
+                </row>\r
+                <row>\r
+                    <entry>External link</entry>\r
+                    <entry><![CDATA[ <link xlink:href="http://evergreen-ils.org/" xlink:title="Link hover text goes here">http://evergreen-ils.org/</link> ]]></entry>\r
+                    <entry><link xlink:href="http://evergreen-ils.org/" xlink:title="Link hover text goes here">http://evergreen-ils.org/</link></entry>\r
+                    <entry><emphasis>xlink:href</emphasis> is the target URL. It is good practice to show full URL so users can see it in PDF or copy and paste from pages displayed in the staff client (to open in a separate browser)</entry>\r
+                </row>\r
+\r
+\r
+            </tbody>\r
+        </tgroup>\r
+    </informaltable>\r
+    \r
+    <para>For internal links the hover tip text is generated automatically; for external links please include an xlink:title, otherwise the link hover text will be the name of the section or chapter where the link appears.</para>\r
+\r
+\r
+</chapter>\r

diff --git a/style_guide/pi.xml b/style_guide/pi.xml
new file mode 100644 (file)
index 0000000..664b745
--- /dev/null
+++ b/style_guide/pi.xml
@@ -0,0 +1,63 @@
+<?xml version="1.0" encoding="utf-8"?>\r
+<chapter xml:id="style-pi" xmlns="http://docbook.org/ns/docbook" version="5.0" xml:lang="EN"\r
+    xmlns:xi="http://www.w3.org/2001/XInclude" xmlns:xlink="http://www.w3.org/1999/xlink">\r
+    <info>\r
+        <title>Processing instructions</title>\r
+    </info>\r
+\r
+    <para>Processing instructions (PIs) are written into the xml when the desired output cannot be\r
+        achieved with DocBook elements and attributes alone. PIs may also be used to force special\r
+        formatting in only part of a document. For a more technical introduction see Bob Stayton's\r
+            <link xlink:href="http://www.sagehill.net/docbookxsl/ProcessingInstructions.html"\r
+            xlink:title="http://www.sagehill.net/docbookxsl/ProcessingInstructions.html">DocBook\r
+            XSL: The Complete Guide</link>. There are also lists of DocBook-specific processing\r
+        instructions for <link\r
+            xlink:href="http://docbook.sourceforge.net/release/xsl/current/doc/pi/pi-html.html"\r
+            xlink:title="http://docbook.sourceforge.net/release/xsl/current/doc/pi/pi-html.html"\r
+            >html</link> and <link\r
+            xlink:href="http://docbook.sourceforge.net/release/xsl/current/doc/pi/pi-fo.html"\r
+            xlink:title="http://docbook.sourceforge.net/release/xsl/current/doc/pi/pi-fo.html"\r
+            >pdf</link> output.</para>\r
+\r
+    <para>PIs should be used sparingly: it is easier to maintain documents that achieve the desired\r
+        output with DocBook elements and <link\r
+            xlink:href="http://docbook.sourceforge.net/release/xsl/current/doc/html/index.html"\r
+            xlink:title="http://docbook.sourceforge.net/release/xsl/current/doc/html/index.html"\r
+            >stylesheet parameters</link>. However, there are a few cases where PIs may be\r
+        necessary:</para>\r
+\r
+    <itemizedlist>\r
+        <listitem>\r
+            <formalpara>\r
+                <title>Force line break</title>\r
+                <para>Line breaks should not be used for spacing between elements; this is much\r
+                    better done with CSS and XSL. Hoever, if entering multiple lines that must be\r
+                    displayed in succession but without the separation of a new paragraph, you may\r
+                    use the linebreak PI.  The following code</para>\r
+            </formalpara>\r
+            <programlisting>\r
+  <![CDATA[<para>First line <?linebreak?>Second line <?linebreak?>Third line</para>]]>                  \r
+            </programlisting>\r
+            <para>Will output</para>\r
+            <informalexample><para>First line <?linebreak?>Second line <?linebreak?>Third line</para></informalexample>\r
+\r
+            <caution><para>This only works if\r
+                custom stylesheets include the following code, described in <link\r
+                    xlink:href="http://www.sagehill.net/docbookxsl/LineBreaks.html"\r
+                    xlink:title="http://www.sagehill.net/docbookxsl/LineBreaks.html">Bob Stayton's\r
+                    DocBook XSL</link>.  Sitka's customization layer includes this template as of June\r
+                30, 2010:</para>\r
+            <para>\r
+  <![CDATA[<xsl:template match="processing-instruction('linebreak')">\r
+         <fo:block/>\r
+  </xsl:template>]]>                   \r
+            </para></caution>\r
+        </listitem>\r
+        \r
+        <listitem>\r
+            <formalpara><title>Include external content</title><para>To insert external content into the html output use the <emphasis>dbhtml-include</emphasis> processing instruction as described in <link xlink:href="http://www.sagehill.net/docbookxsl/InsertExtHtml.html#CodeInPage" xlink:title="http://www.sagehill.net/docbookxsl/InsertExtHtml.html#CodeInPage">DocBook XSL</link>.\r
+            This could be used to add a custom search box to the title page, an animated tutorial in the relevant section, or any other content in valid xhtml.</para></formalpara>\r
+        </listitem>\r
+        \r
+    </itemizedlist>\r
+</chapter>\r

diff --git a/style_guide/root.xml b/style_guide/root.xml
new file mode 100644 (file)
index 0000000..dc27c66
--- /dev/null
+++ b/style_guide/root.xml
@@ -0,0 +1,42 @@
+<?xml version="1.0" encoding="utf-8"?>\r
+<book xml:id="style" xmlns="http://docbook.org/ns/docbook"\r
+      xmlns:xi="http://www.w3.org/2001/XInclude" version="5" xml:lang="EN"\r
+      xmlns:xlink="http://www.w3.org/1999/xlink">\r
+      <info>\r
+            <title>DIG/Evergreen DocBook Style Guide</title>\r
+                        \r
+        \r
+            \r
+            <copyright>\r
+                  <year>2010</year>\r
+                  <holder>Evergreen Community</holder>\r
+                 \r
+            </copyright>\r
+            <legalnotice>\r
+                  <para><link xlink:title="Creative Commons license"\r
+                        xlink:href="http://creativecommons.org/licenses/by-sa/3.0/">\r
+                        <inlinemediaobject>\r
+                              <imageobject>\r
+                                    <imagedata scalefit="0"\r
+                                          fileref="http://i.creativecommons.org/l/by-sa/3.0/80x15.png"\r
+                                    />\r
+                              </imageobject>\r
+                        </inlinemediaobject>\r
+                  </link></para>\r
+                  <para>This document was updated October 18, 2010.</para>\r
+            </legalnotice>\r
+            \r
+      </info> \r
+      \r
+     \r
+      <xi:include href="glossary.xml"/>\r
+      <xi:include href="image.xml"/> \r
+      <xi:include href="links.xml"/> \r
+      <xi:include href="pi.xml"/>     \r
+      <xi:include href="tips.xml"/>\r
+     \r
+     \r
+      \r
+      \r
+      \r
+</book>\r

diff --git a/style_guide/tips.xml b/style_guide/tips.xml
new file mode 100644 (file)
index 0000000..3e2a411
--- /dev/null
+++ b/style_guide/tips.xml
@@ -0,0 +1,41 @@
+<?xml version="1.0" encoding="utf-8"?>\r
+<chapter xml:id="style-tips" xmlns="http://docbook.org/ns/docbook" version="5.0" xml:lang="EN"\r
+    xmlns:xi="http://www.w3.org/2001/XInclude" xmlns:xlink="http://www.w3.org/1999/xlink">\r
+\r
+    <info>\r
+\r
+        <title>Miscellaneous Tips</title>\r
+    </info>\r
+\r
+\r
+    <simplesect>\r
+        <title>Table column width</title>\r
+\r
+        <para>If column width is not specified in the XML, tables will look different depending on\r
+            the output format. In HTML the columns automatically adjust to fit contents, but in PDF\r
+            the page width is divided evenly by the number of columns. This often wastes space in\r
+            PDF tables so setting relative column widths for all tables is recommended.</para>\r
+        <para>In the example below, the <emphasis>colwidth</emphasis> parameter defines relative\r
+            column width. Columns 1 and 2 are of equal width, each using a quarter of the page.\r
+            Column 3 is twice the size and covers the remaining half of the page.</para>\r
+\r
+        <programlisting><![CDATA[ \r
+<table>\r
+   <title>Title of Table Here</title>\r
+      <tgroup cols="3" align="left" colsep="1" rowsep="1">\r
+         <colspec colnum="1" colname="issues" colwidth="1*"/>\r
+         <colspec colnum="2" colname="actions" colwidth="1*"/>\r
+         <colspec colnum="3" colname="tasks" colwidth="2*"/>]]>\r
+    \r
+        </programlisting>\r
+\r
+        <para>For details see <link\r
+                xlink:href="http://www.sagehill.net/docbookxsl/ColumnWidths.html"\r
+                xlink:title="http://www.sagehill.net/docbookxsl/ColumnWidths.html">DocBook XSL: The\r
+                Complete Guide</link>.</para>\r
+\r
+    </simplesect>\r
+\r
+   \r
+\r
+</chapter>\r