docs/1.6/chapter.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="chapter">\r
   4   <title>Chapters and Other Root Elements</title>\r
   5   <section>\r
   6     <title>Guidance for Evergreen Authors</title>\r
   7     <para>The following information is intended to clarify the elements in the documents you are\r
   8       working with. If you use the Evergreen templates, they will at minimum have top-level\r
   9       declarations filled out. </para>\r
  10     <para>In most cases, you will be working with chapters or sections, as described below. However,\r
  11       in some cases you may need to create a document from another root element, such as <tag\r
  12         class="element">glossary</tag>.</para>\r
  13   </section>\r
  14   <section>\r
  15     <title>Top-level Declarations</title>\r
  16     <para>The first few lines of an XML chapter contains boilerplate markup. These lines include the\r
  17       XML encoding statement and an entity declarations for the variables used in the chapter. If\r
  18       you use the Evergreen templates, these will be filled out for you.</para>\r
  19   </section>\r
  20   <section>\r
  21     <title>Root Element</title>\r
  22     <para>The root element of an XML chapter is the <tag class="element">chapter</tag> element. The\r
  23         <tag class="element">chapter</tag> element provides a wrapper for sections and\r
  24       blocks.</para>\r
  25     <para>The <tag class="element">chapter</tag> element needs to include the XML namespace\r
  26       declarations shown in <xref linkend="ChaptRootXMLNS"/>:</para>\r
  27     <example xml:id="ChaptRootXMLNS">\r
  28       <title>XML Namespace Declarations</title>\r
  29       <programlisting>&lt;chapter xmlns="http://docbook.org/ns/docbook"\r
  30 xmlns:xi="http://www.w3.org/2001/XInclude"\r
  31 xmlns:xl="http://www.w3.org/1999/xlink"&gt;</programlisting>\r
  32     </example>\r
  33     <para>The <tag class="element">chapter</tag> element's <tag class="attribute">version</tag>\r
  34       attribute must be set to <tag class="attvalue">5.0</tag>.</para>\r
  35   </section>\r
  36   <section>\r
  37     <title>Title</title>\r
  38     <para>The first child of the <tag class="element">chapter</tag> element is the <tag\r
  39         class="element">title</tag> element. The contents of the <tag class="element">title</tag>\r
  40       element is the title of the chapter, such as Evergreen Circulation or Evergreen System\r
  41       Administration.</para>\r
  42     <para>Titles in Evergreen documentation are determined by the DIG, and follow the format:\r
  43       Evergreen [Function]. </para>\r
  44   </section>\r
  45   <section xml:id="ChaptInfo">\r
  46     <title>Chapter Info</title>\r
  47     <para>After the <tag class="element">title</tag> element, a chapter should have an <tag\r
  48         class="element">info</tag> element. This element contains the chapter summary and a list of\r
  49       keywords that will be put into the generated metadata for this chapter.</para>\r
  50     <para>The chapter summary is placed inside an <tag class="element">abstract</tag> element. The\r
  51         <tag class="element">abstract</tag> element requires a nested <tag class="element"\r
  52         >para</tag> element to wrap the text.</para>\r
  53     <para>The keyword list is placed inside of a <tag class="element">keywordset</tag> element. Each\r
  54       keyword in the list must be wrapped in a <tag class="element">keyword</tag> element. (Do we\r
  55       want to use this?)</para>\r
  56   </section>\r
  57   <section xml:id="ChaptStructElements">\r
  58     <title>Structural Elements</title>\r
  59     <simplesect>\r
  60       <title>Overview</title>\r
  61       <para>Chapters are broken into sections and blocks.</para>\r
  62     </simplesect>\r
  63     <simplesect>\r
  64       <title>Sections</title>\r
  65       <para>Generally, a chapter should have five or fewer sections. If you need more sections, it\r
  66         may be because the topic for your chapter is too broad or you need to reconsider how you are\r
  67         chunking the information. Top level sections are denoted using <tag class="element"\r
  68           >section</tag> elements.</para>\r
  69       <para>Top-level sections can be broken down into five or fewer subsections. Subsections are\r
  70         also denoted using <tag class="element">section</tag> elements.</para>\r
  71     </simplesect>\r
  72     <simplesect>\r
  73       <title>Blocks (simplesect)</title>\r
  74       <para>Block are the smallest structural unit of organization in a chapter. They divide up the\r
  75         information in a section into manageable chunks of information. There should be no more than\r
  76         five block-sections in a section.</para>\r
  77       <para>Block-sections are denoted using <tag class="element">simplesect</tag> elements. Blocks\r
  78         cannot be subdivided.</para>\r
  79     </simplesect>\r
  80     <simplesect>\r
  81       <title>Example</title>\r
  82       <para><xref linkend="chapter_detailExample"/> shows a more detailed view of a chapter.</para>\r
  83       <example xml:id="chapter_detailExample" pgwide="1">\r
  84         <?dbfo pgwide="1"?>\r
  85         <title>Detailed View of a Chapter</title>\r
  86         <programlisting>&lt;?xml version=&quot;1.0&quot; encoding=&quot;UTF-8&quot;?&gt;\r
  87 &lt;chapter xmlns="http://docbook.org/ns/docbook"\r
  88 xmlns:xi="http://www.w3.org/2001/XInclude"\r
  89 xmlns:xl="http://www.w3.org/1999/xlink"\r
  90 version="5.0"\r
  91 xml:id="chapter"&gt;\r
  92   &lt;title&gt;This is a Chapter&lt;/title&gt;\r
  93   &lt;info&gt;\r
  94     &lt;abstract&gt;\r
  95       &lt;para&gt;This is a chapter summary.&lt;/para&gt;\r
  96     &lt;/abstract&gt;\r
  97   &lt;/info&gt;\r
  98   &lt;section id=&quot;section&quot;&gt;\r
  99     &lt;title&gt;This is a section&lt;/title&gt;\r
 100     ...\r
 101   &lt;/section&gt;\r
 102   &lt;section id=&quot;...&quot;&gt;\r
 103     ...\r
 104     &lt;section id=&quot;subsection&quot;&gt;\r
 105       &lt;title&gt;Sample Subsection&lt;/title&gt;\r
 106       ...\r
 107       &lt;simplesect id=&quot;block&quot;&gt;\r
 108         &lt;title&gt;Sample Block Section&lt;/title&gt;\r
 109         ...\r
 110       &lt;/simplesect&gt;\r
 111     &lt;/section&gt;\r
 112   &lt;/section&gt;\r
 113 &lt;/chapter&gt;</programlisting>\r
 114       </example>\r
 115     </simplesect>\r
 116   </section>\r
 117 </chapter>\r