docs/1.6/styleguide/structure.xml

   1 <?xml version='1.0' encoding='UTF-8'?>\r
   2 <chapter xmlns="http://docbook.org/ns/docbook" xmlns:xi="http://www.w3.org/2001/XInclude"\r
   3   xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:id="structure">\r
   4   <title>The Structure of Evergreen Documentation</title>\r
   5   <info>\r
   6     <abstract>\r
   7       <para>This chapter describes the structure of Evergreen documentation, common elements in XML\r
   8         files, and allowable documentation types.</para>\r
   9     </abstract>\r
  10   </info>\r
  11   <section>\r
  12     <title>Top-level Elements in Evergreen Documentation</title>\r
  13     <simplesect>\r
  14       <title>Overview</title>\r
  15       <para>There are two central books for Evergreen documentation, organized within a single set.\r
  16         The documentation files are arranged it hierarchically, beginning with docs, followed by the\r
  17         version:</para>\r
  18       <para>http://evergreen-ils.org/docs/1.6 ...</para>\r
  19       <para>The following is a common structural pattern for our documentation:</para>\r
  20       <itemizedlist>\r
  21         <listitem>\r
  22           <para><emphasis role="bold"><tag class="element">set</tag></emphasis></para>\r
  23         </listitem>\r
  24         <listitem>\r
  25           <para><emphasis role="bold"><tag class="element">book</tag></emphasis></para>\r
  26         </listitem>\r
  27         <listitem>\r
  28           <para><emphasis role="bold"><tag class="element">chapter</tag></emphasis>--a major topic\r
  29             area, such as Circulation</para>\r
  30         </listitem>\r
  31         <listitem>\r
  32           <para><emphasis role="bold"><tag class="element">section</tag></emphasis>--a subsection of\r
  33             an area, such as Patron Registration</para>\r
  34         </listitem>\r
  35         <listitem>\r
  36           <para><emphasis role="bold"><tag class="element">simplesect</tag></emphasis>--subdivision\r
  37             of section, such as Family Accounts</para>\r
  38         </listitem>\r
  39         <listitem>\r
  40           <para><emphasis role="bold"><tag class="element">para</tag></emphasis>--a basic paragraph\r
  41             marker</para>\r
  42         </listitem>\r
  43       </itemizedlist>\r
  44       <para>Most authors will be working at the <tag class="element">chapter</tag> or <tag\r
  45           class="element">section</tag> level. Chapters are created in separate files and imported\r
  46         into the book file using <tag class="element">xinclude</tag> elements.</para>\r
  47       <para>There are many more DocBook elements. The above is only intended to be illustrative of\r
  48         the "tree" that shapes Evergreen documentation. There are also exceptions to the "chapter"\r
  49         element, such as the <tag class="element" revision="">glossary</tag> element. </para>\r
  50       <para>The final chapter of this styleguide lists excluded tags for Evergreen documentation.\r
  51       </para>\r
  52     </simplesect>\r
  53   </section>\r
  54   <section>\r
  55     <title>The Sets and Chapters of Evergreen Documentation</title>\r
  56     <simplesect>\r
  57       <title>Overview</title>\r
  58       <para>Evergreen documentation has the following high-level set, books, and chapters. Filenames\r
  59         are in parentheses:</para>\r
  60       <para>\r
  61         <itemizedlist>\r
  62           <listitem>\r
  63             <para><emphasis role="bold"><tag class="element">set</tag></emphasis> (set.xml)</para>\r
  64           </listitem>\r
  65           <listitem>\r
  66             <para><emphasis role="bold"><tag class="element">book</tag></emphasis> Evergreen\r
  67               Technical Reference (book1.xml)</para>\r
  68           </listitem>\r
  69           <listitem>\r
  70             <para><emphasis role="bold"><tag class="element">chapter</tag></emphasis> Installing\r
  71               (installing.xml)</para>\r
  72           </listitem>\r
  73           <listitem>\r
  74             <para><emphasis role="bold"><tag class="element">chapter</tag></emphasis> Upgrading\r
  75               (upgrading.xml)</para>\r
  76           </listitem>\r
  77           <listitem>\r
  78             <para><emphasis role="bold"><tag class="element">chapter</tag></emphasis> Migrating from\r
  79               other Integrated Library Systems (migrating.xml)</para>\r
  80           </listitem>\r
  81           <listitem>\r
  82             <para><emphasis role="bold"><tag class="element">chapter</tag></emphasis> System\r
  83               Administration (sysadmin.xml)</para>\r
  84           </listitem>\r
  85           <listitem>\r
  86             <para><emphasis role="bold"><tag class="element">chapter</tag></emphasis> Software\r
  87               Developers' Reference (softwaredev.xml)</para>\r
  88           </listitem>\r
  89           <listitem>\r
  90             <para><emphasis role="bold"><tag class="element">chapter</tag></emphasis> Web\r
  91               Developers' Reference (webdev.xml)</para>\r
  92           </listitem>\r
  93           <listitem>\r
  94             <para><emphasis role="bold"><tag class="element">book</tag></emphasis> Evergreen (?)\r
  95               Reference (book2.xml)</para>\r
  96           </listitem>\r
  97           <listitem>\r
  98             <para><emphasis role="bold"><tag class="element">chapter</tag></emphasis> Local\r
  99               Administration (localadmin.xml)</para>\r
 100           </listitem>\r
 101           <listitem>\r
 102             <para><emphasis role="bold"><tag class="element">chapter</tag></emphasis> The OPAC\r
 103               (opac.xml)</para>\r
 104           </listitem>\r
 105           <listitem>\r
 106             <para><emphasis role="bold"><tag class="element">chapter</tag></emphasis> Cataloging\r
 107               (cataloging.xml)</para>\r
 108           </listitem>\r
 109           <listitem>\r
 110             <para><emphasis role="bold"><tag class="element">chapter</tag></emphasis> Circulation\r
 111               (circulation.xml)</para>\r
 112           </listitem>\r
 113           <listitem>\r
 114             <para><emphasis role="bold"><tag class="element">chapter</tag></emphasis> Reports\r
 115               (reports.xml)</para>\r
 116           </listitem>\r
 117           <listitem>\r
 118             <para><emphasis role="bold"><tag class="element">chapter</tag></emphasis> Acquisitions\r
 119               (acquisitions.xml)</para>\r
 120           </listitem>\r
 121           <listitem>\r
 122             <para><emphasis role="bold"><tag class="element">chapter</tag></emphasis> Future\r
 123               Development (futuredev.xml)</para>\r
 124           </listitem>\r
 125           <listitem>\r
 126             <para><emphasis role="bold"><tag class="element">chapter</tag></emphasis> Glossary\r
 127               (glossary.xml)</para>\r
 128           </listitem>\r
 129         </itemizedlist>\r
 130       </para>\r
 131     </simplesect>\r
 132   </section>\r
 133 </chapter>\r