docs/1.6/books.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="books" status="draft">\r
   4   <title>Creating a Book</title>\r
   5   <info>\r
   6     <abstract>\r
   7       <para>Books are the top level of organization for topics in a library. They are a collection\r
   8         of sub-topics organized into chapters. This chapter describes how to create books in XML. </para>\r
   9       <para>\r
  10         <note>\r
  11           <para>In most cases Evergreen documentation authors will not create books, but will be\r
  12             authoring chapters or sections within books, as described in the chapter on document\r
  13             structure. </para>\r
  14         </note>\r
  15       </para>\r
  16     </abstract>\r
  17   </info>\r
  18   <section>\r
  19     <title>Common Elements</title>\r
  20     <simplesect>\r
  21       <title>Overview</title>\r
  22       <para>XML based books share a number of common elements. These include:</para>\r
  23       <itemizedlist>\r
  24         <listitem>\r
  25           <para>A <tag class="element">XML version and encoding</tag> element</para>\r
  26         </listitem>\r
  27         <listitem>\r
  28           <para>A <tag class="element">root</tag> element</para>\r
  29         </listitem>\r
  30         <listitem>\r
  31           <para>A <tag class="element">title</tag> element</para>\r
  32         </listitem>\r
  33         <listitem>\r
  34           <para>An <tag class="element">info</tag> element describing the book's front matter</para>\r
  35         </listitem>\r
  36       </itemizedlist>\r
  37     </simplesect>\r
  38     <simplesect>\r
  39       <title>Root element</title>\r
  40       <para>The root element of an XML book is the <tag class="element">book</tag> element. The <tag\r
  41           class="element">book</tag> element provides a wrapper for parts, chapters, appendices,\r
  42         indexes, and glossaries.</para>\r
  43       <para>The <tag class="element">book</tag> element needs to include the XML namespace\r
  44         declarations shown in <xref linkend="BookRootXMLNS"/>:</para>\r
  45       <example xml:id="BookRootXMLNS">\r
  46         <title>XML Namespace Declarations</title>\r
  47         <programlisting>&lt;book <emphasis role="bold">xmlns="http://docbook.org/ns/docbook"\r
  48 xmlns:xi="http://www.w3.org/2001/XInclude"\r
  49 xmlns:xl="http://www.w3.org/1999/xlink"</emphasis>\r
  50 ... &gt;</programlisting>\r
  51       </example>\r
  52       <para>The <tag class="element">book</tag> element's <tag class="attribute">version</tag>\r
  53         attribute must be set to <tag class="attvalue">5.0</tag>.</para>\r
  54       <para>You must also specify a value for the <tag class="element">book</tag> element's <tag\r
  55           class="attribute">xml:id</tag> attribute. </para>\r
  56       <para>You can also use the <tag class="element">book</tag> element's <tag class="attribute"\r
  57           >status</tag> attribute to embed a draft stamp in the book. You do this by setting <tag\r
  58           class="attribute">status</tag> attribute to <tag class="attvalue">draft</tag>.</para>\r
  59     </simplesect>\r
  60     <simplesect>\r
  61       <title>Title</title>\r
  62       <para>The first child of the <tag class="element">book</tag> element is the <tag\r
  63           class="element">title</tag> element. The contents of the <tag class="element">title</tag>\r
  64         element is the title of the book.</para>\r
  65     </simplesect>\r
  66     <simplesect>\r
  67       <title>Front matter</title>\r
  68       <para>The production templates fill in the required graphics and other formatting for the\r
  69         front matter of a book. However, the author needs to include the proper legal notices and\r
  70         copyright information. All of the legal notices should be imported from the template folder\r
  71         in the library. This way you do not have to worry about updating your books when the legal\r
  72         notices change.</para>\r
  73       <para>The front matter also includes the following information:</para>\r
  74       <itemizedlist>\r
  75         <listitem>\r
  76           <para>The release date</para>\r
  77         </listitem>\r
  78         <listitem>\r
  79           <para>The product name and version</para>\r
  80         </listitem>\r
  81         <listitem>\r
  82           <para>The date the document was updated</para>\r
  83         </listitem>\r
  84         <listitem>\r
  85           <para>The common keywords for the book</para>\r
  86         </listitem>\r
  87         <listitem>\r
  88           <para>The graphics for the front page</para>\r
  89         </listitem>\r
  90       </itemizedlist>\r
  91       <para>All of the information in the front matter is boiler plate and should not be\r
  92         updated.</para>\r
  93       <para><xref linkend="legal"/> shows a book file with the front matter imported.</para>\r
  94       <example xml:id="legal" pgwide="1">\r
  95         <?dbfo pgwide="1"?>\r
  96         <title>Front Matter Imported</title>\r
  97         <programlisting>&lt;?xml version="1.0" encoding="UTF-8"?&gt;\r
  98 &lt;book xmlns="http://docbook.org/ns/docbook"\r
  99 xmlns:xi="http://www.w3.org/2001/XInclude"\r
 100 xmlns:xl="http://www.w3.org/1999/xlink"\r
 101 version="5.0"\r
 102 xml:id="overview"&gt;\r
 103 &lt;title&gt;What is &amp;prodname;?&lt;/title&gt;\r
 104 &lt;info&gt;\r
 105 &lt;xi:include href=&quot;../common/keywords.xml&quot; /&gt;\r
 106 &lt;mediaobject&gt;\r
 107   &lt;imageobject role="html"&gt;\r
 108     &lt;imagedata depth=&quot;100&quot; contentwidth=&quot;146&quot; contentdepth=&quot;55&quot; \r
 109                valign=&quot;middle&quot; fileref=&quot;./imagesdb/cover_logo.gif&quot;/&gt;\r
 110   &lt;/imageobject&gt;\r
 111 &lt;/mediaobject&gt;\r
 112 &lt;productname&gt;&amp;prodname;?&lt;/productname&gt;\r
 113 &lt;releaseinfo&gt;Version &amp;version;?&lt;/releaseinfo&gt;\r
 114 &lt;date&gt;&amp;reldate?&lt;/date&gt;\r
 115 &lt;xi:include href=&quot;../common/legalblurb.xml&quot; /&gt;\r
 116 &lt;xi:include href=&quot;../common/copynotice.xml&quot; /&gt;\r
 117 &lt;xi:include href=&quot;../common/copydate.xml&quot; /&gt;\r
 118 &lt;pubdate&gt;&lt;?dbtimestamp format="d b Y"?&gt;&lt;/pubdate&gt;\r
 119 &lt;corpauthor&gt;Evergreen Documentation Interest Group&lt;/corpauthor&gt;\r
 120 &lt;/info&gt;\r
 121 ...\r
 122 &lt;/book&gt;</programlisting>\r
 123       </example>\r
 124     </simplesect>\r
 125   </section>\r
 126   <section>\r
 127     <title>Preface</title>\r
 128     <simplesect>\r
 129       <title>Overview</title>\r
 130       <para>The preface of your book is placed into the XML file just after the <tag class="element"\r
 131           >info</tag> element. It is specified inside of a <tag class="element">preface</tag>\r
 132         element. The preface should be created in a separate file and imported, using an <tag\r
 133           class="element">xinclude</tag> element, into the book file.</para>\r
 134     </simplesect>\r
 135     <simplesect>\r
 136       <title>Parts of the preface</title>\r
 137       <para>The preface of your book will have the following sections that are unique to a\r
 138         book:</para>\r
 139       <itemizedlist>\r
 140         <listitem>\r
 141           <para>What is covered in this book?</para>\r
 142         </listitem>\r
 143         <listitem>\r
 144           <para>Who should read this book?</para>\r
 145         </listitem>\r
 146         <listitem>\r
 147           <para>How to use this book?</para>\r
 148         </listitem>\r
 149       </itemizedlist>\r
 150       <para>In addition there are several sections that are common to all of the books in the\r
 151         library. These include:</para>\r
 152       <itemizedlist>\r
 153         <listitem>\r
 154           <para>Library</para>\r
 155         </listitem>\r
 156         <listitem>\r
 157           <para>How to get the latest updates</para>\r
 158         </listitem>\r
 159         <listitem>\r
 160           <para>Additional support resources</para>\r
 161         </listitem>\r
 162         <listitem>\r
 163           <para>Documentation conventions</para>\r
 164         </listitem>\r
 165       </itemizedlist>\r
 166       <para>These common sections should be imported, using <tag class="element">xinclude</tag>\r
 167         elements, from a common template area. This ensures that any changes are propagated across\r
 168         the entire library.</para>\r
 169     </simplesect>\r
 170     <simplesect>\r
 171       <title>Adding content to a preface</title>\r
 172       <para>Writing a preface is identical to writing a chapter. This is discussed in <olink\r
 173           targetdoc="StyleGuide" targetptr="chapter"/>.</para>\r
 174     </simplesect>\r
 175     <simplesect>\r
 176       <title>Example</title>\r
 177       <para><xref linkend="preface"/> shows a preface that can be imported into a book file.</para>\r
 178       <example xml:id="preface" pgwide="1">\r
 179         <?dbfo pgwide="1"?>\r
 180         <title>Book Preface</title>\r
 181         <programlisting>&lt;?xml version=&quot;1.0&quot; encoding=&quot;UTF-8&quot;?&gt;\r
 182 &lt;preface xmlns="http://docbook.org/ns/docbook"\r
 183 xmlns:xi="http://www.w3.org/2001/XInclude"\r
 184 xmlns:xl="http://www.w3.org/1999/xlink"\r
 185 version="5.0"\r
 186 xml:id=&quot;inferno&quot;&gt;\r
 187 &lt;title&gt;Preface&lt;/title&gt;\r
 188 &lt;section&gt;\r
 189 &lt;title&gt;What is Covered in This Book&lt;/title&gt;\r
 190 &lt;para&gt;A bunch of technical stuff.&lt;/para&gt;\r
 191 &lt;/section&gt;\r
 192 &lt;section&gt;\r
 193 &lt;title&gt;Who Should Read This Book&lt;/title&gt;\r
 194 &lt;para&gt;Engineers interested in learning about the stuff discussed.&lt;/para&gt;\r
 195 &lt;/section&gt;\r
 196 &lt;section&gt;\r
 197 &lt;title&gt;How to Use This Book&lt;/title&gt;\r
 198 &lt;para&gt;Very carefully...&lt;/para&gt;\r
 199 &lt;/section&gt;\r
 200 &lt;xi:include href=&quot;../common/library.xml&quot; /&gt;\r
 201 &lt;xi:include href=&quot;../common/latest.xml&quot; /&gt;\r
 202 &lt;xi:include href=&quot;../common/searching.xml&quot; /&gt;\r
 203 &lt;xi:include href=&quot;../common/resources.xml&quot; /&gt;\r
 204 &lt;xi:include href=&quot;../common/coventions.xml&quot; /&gt;\r
 205 &lt;/preface&gt;</programlisting>\r
 206       </example>\r
 207     </simplesect>\r
 208   </section>\r
 209   <section>\r
 210     <title>Chapters</title>\r
 211     <simplesect>\r
 212       <title>Overview</title>\r
 213       <para>After the preface, you add the chapters to your book. Chapters are created in separate\r
 214         files and imported into the book file using <tag class="element">xinclude</tag> elements. </para>\r
 215       <para>You do not need to worry about adding a table of contents, list of figures, or list of\r
 216         tables. These are all created when the book is published.</para>\r
 217     </simplesect>\r
 218     <simplesect>\r
 219       <title>Writing chapters</title>\r
 220       <para>Adding content to a chapter is discussed in the <olink targetdoc="chapters"\r
 221           targetptr="chapters"/></para>\r
 222     </simplesect>\r
 223     <simplesect>\r
 224       <title>Importing chapters</title>\r
 225       <para>Chapters are imported into a book using <tag class="element">xinclude</tag>\r
 226         elements.</para>\r
 227     </simplesect>\r
 228   </section>\r
 229   <section>\r
 230     <title>Example Book</title>\r
 231     <para><xref linkend="sectLevel"/> shows a book.</para>\r
 232     <example xml:id="sectLevel" pgwide="1">\r
 233       <?dbfo pgwide="1"?>\r
 234       <title>An XML Book</title>\r
 235       <programlisting>&lt;?xml version="1.0" encoding="UTF-8"?&gt;\r
 236 &lt;book xmlns="http://docbook.org/ns/docbook"\r
 237 xmlns:xi="http://www.w3.org/2001/XInclude"\r
 238 xmlns:xl="http://www.w3.org/1999/xlink"\r
 239 version="5.0"\r
 240 xml:id=&quot;overview&quot;&gt;\r
 241 &lt;title&gt;Evergreen Guide to Martian Living&lt;/title&gt;\r
 242 &lt;info&gt;\r
 243 &lt;xi:include href=&quot;../common/legalblurb.xml&quot; /&gt;\r
 244 &lt;xi:include href=&quot;../common/copynotice.xml&quot; /&gt;\r
 245 &lt;xi:include href=&quot;../common/copydate.xml&quot; /&gt;\r
 246 &lt;/info&gt;\r
 247 &lt;xi:include href="preface.xml" /&gt;\r
 248 &lt;xi:include href="migration.xml" /&gt;\r
 249 &lt;xi:include href="housekeeping.xml" /&gt;\r
 250 &lt;xi:include href="recipes.xml" /&gt;\r
 251 &lt;xi:include href="shopping.xml" /&gt;\r
 252 &lt;index /&gt;\r
 253 &lt;/book&gt;</programlisting>\r
 254     </example>\r
 255   </section>\r
 256 </chapter>\r