docs/1.6/filenames.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="filenames">\r
   4   <title>File Structure and Filenames</title>\r
   5  \r
   6   <info>\r
   7     <abstract>\r
   8       <para>This chapter describes the physical file structure for Evergreen documentation and file\r
   9         naming conventions, including the  <tag class="element">olink</tag> element. </para>\r
  10     </abstract>\r
  11   </info>\r
  12   <section>\r
  13     <title>File Structure for Evergreen Documentation</title>\r
  14     <simplesect>\r
  15       <title>Overview</title>\r
  16       <para>The files for Evergreen documentation reside within a public directory on\r
  17         evergreen-ils.org. </para>\r
  18     </simplesect>\r
  19     <simplesect>\r
  20       <title>File structure for Evergreen documents</title>\r
  21       <itemizedlist>\r
  22         <listitem>\r
  23           <para>The set is represented by set.xml, a single file in the docs subdirectory of\r
  24             evergreen-ils.org</para>\r
  25         </listitem>\r
  26         <listitem>\r
  27           <para>The two book elements are in separate subdirectories under the docs subdirectory,\r
  28             and are labeled book1.xml and book2.xml</para>\r
  29         </listitem>\r
  30         <listitem>\r
  31           <para>Chapter elements are in their own separate subdirectories under their respective\r
  32             book directories</para>\r
  33         </listitem>\r
  34         <listitem>\r
  35           <para>Glossaries and similar chapter-like elements are treated like chapters, and are in\r
  36             separate subdirectories under their respective book directories</para>\r
  37         </listitem>\r
  38         <listitem>\r
  39           <para>Images and similar media files are placed in subdirectories under their respective\r
  40             folders.</para>\r
  41         </listitem>\r
  42       </itemizedlist>\r
  43     </simplesect>\r
  44   </section>\r
  45   <section>\r
  46     <title>Filename conventions</title>\r
  47     <itemizedlist>\r
  48       <listitem>\r
  49         <para>Evergreen filenames are in lower case without underscores or periods.</para>\r
  50       </listitem>\r
  51       <listitem>\r
  52         <para>The folders for images and other multimedia are named media. </para>\r
  53       </listitem>\r
  54       <listitem>\r
  55         <para>The XML id for the chapter is the same as the XML filename, such as sysadmin. </para>\r
  56       </listitem>\r
  57     </itemizedlist>\r
  58   </section>\r
  59 \r
  60   <section>\r
  61     <title>Conventions for olinks</title>\r
  62     <itemizedlist>\r
  63       <listitem>\r
  64         <para>To simplify the creation of olinks between between books, every Evergreen file has a\r
  65             <glossterm>document id</glossterm> that parallels the file's filename and xml:id\r
  66           attribute. Therefore, a book-level file called book2.xml has an xml:id of book2 and a\r
  67           document id of book2, while a chapter file called sysadmin.xml has an xml:id of sysadmin\r
  68           and also a document id of sysadmin.</para>\r
  69       </listitem>\r
  70       <listitem>\r
  71         <para>The document id is the first element within the file after the xml declaration, and\r
  72           has the structure element id="name".</para>\r
  73       </listitem>\r
  74     </itemizedlist>\r
  75   </section>\r
  76 </chapter>\r