style_guide/contributing_DIG.xml

   1 <?xml version="1.0" encoding="utf-8"?>
   2 <chapter xml:id="style-contributing" xmlns="http://docbook.org/ns/docbook" version="5.0" xml:lang="EN"
   3     xmlns:xi="http://www.w3.org/2001/XInclude" xmlns:xlink="http://www.w3.org/1999/xlink">
   4     <info>
   5         <title>Contributing Documentation in DocBook Format</title>
   6     </info>
   7
   8         <section xml:id="docbook_file_structure">
   9                 <title>Evergreen Documentation File Structure</title>
  10
  11                 <para>At the root of the Evergreen  documentation is the <filename>root.xml</filename> file. The file contains the &lt;book&gt; element and manages the organization of the
  12                 Evergreen Documentation Manual. This file contains included files which are the chapters and the appendices of the documentation. If you are contributing documentation, you should not
  13                 have to edit this file except to add an include statement to place a new chapter in the Evergreen documentation in appropriate order:</para>
  14 <programlisting><![CDATA[
  15 ...
  16 <xi:include href="appendices/glossary.xml"/>
  17 ...
  18 ]]></programlisting>
  19                 <para>The above example includes the <filename>glossary.xml</filename> file in the Evergreen documentation. This file should be located in the
  20                 <filename class="directory">appendixes</filename> subdirectory relative to the <filename>root.xml</filename> file.</para>
  21                 <para>When creating new files, the first line should always be:</para>
  22 <programlisting> <![CDATA[
  23 <?xml version="1.0" encoding="utf-8"?>
  24 ]]></programlisting>
  25                 <para>This is the standard to indicate that this is an XML file</para>
  26                 <para>The next line should include the &lt;chapter&gt; element. Here is an example for the glossary chapter of this style guide document.</para>
  27 <programlisting> <![CDATA[
  28 <chapter xml:id="style-glossary" xmlns="http://docbook.org/ns/docbook" version="5.0" xml:lang="EN"
  29     xmlns:xi="http://www.w3.org/2001/XInclude" xmlns:xlink="http://www.w3.org/1999/xlink">
  30 ]]></programlisting>
  31                 <para>An important attribute is <code language="xml">xml:id</code>. This must be a unique id to the entire documentation and is important for cross referencing chapters, sections, tables
  32                 and other parts of the documentation.</para>
  33                 <para>Also remember to add the closing &lt;/chapter&gt; tag at the very end of the document.</para>
  34                 <para>The chapter is the container for files contributed to DIG. Do not create a new file to add a <code language="xml">&lt;section&gt;</code> to an existing
  35                 <code language="xml">&lt;chapter&gt;</code> and do not use the <code language="xml">&lt;book&gt;</code> container in yor file since the
  36                 <code language="xml">&lt;book&gt;</code> element is already in the <filename>root.xml</filename> file.</para>
  37         </section>
  38 <section xml:id="how_to_contribte">
  39                 <title>How to Contribute Documentation</title>
  40                 <procedure>
  41                         <title>Using Git to Upload Files from Linux</title>
  42                         <step>
  43                                 <para><link xlink:href="http://help.github.com/linux-git-installation/"  xlink:title="Install git">Install git</link>.</para>
  44                         </step>
  45                         <step>
  46                                 <para><link xlink:href="https://github.com/" xlink:title="get an account">Sign up for a free github account.</link>.</para>
  47                         </step>
  48                         <step>
  49                                 <para>Send an email to the github repository maintainer (<email>robert.soulliere@mohawkcollege.ca</email>) to request being added as a contributor.</para>
  50                         </step>
  51                         <step>
  52                                 <para><link xlink:href="http://help.github.com/linux-key-setup/" xlink:title="linux key setup">Generate and add SSH keys to github repository.</link>.</para>
  53                         </step>
  54                         <step>
  55                                 <para>Clone the Evergreen-DocBook repository on your local machine:</para>
  56 <screen><userinput>git clone git@github.com:rsoulliere/Evergreen-DocBook.git</userinput></screen>
  57                         </step>
  58                         <step>
  59                                 <para>Edit or add files in the cloned repository location.</para>
  60                         </step>
  61                 </procedure>
  62                 <para>For editing and committing changes to the repository there are only a handful of commands you need to know (run these inside the directory structure of your cloned
  63                 repository):</para>
  64                 <itemizedlist>
  65                         <listitem><command>git pull <option>filename</option></command> -  It will pull the most recent changes into your cloned version to avoid merging
  66                         issues and errors when <quote>pushing</quote> your changes to the remote repository.</listitem>
  67                         <listitem><command>git add <option>filename</option></command> - Adds new files to repository. This is needed to tell git that you have added or edited files and want to add
  68                         them into the repo.</listitem>
  69                         <listitem><command>git commit <option>filename</option></command> - Commits changes to the repository. A text file will open describing what will be committed. Add a
  70                         meaningful note here to indicate
  71                         what you have chanaged.</listitem>
  72                         <listitem><command>git push <option>filename</option></command> - Push changes to remote repository. After pushing your changes you should see them show up at:
  73                         <link xlink:href="https://github.com/rsoulliere/Evergreen-DocBook/commits/master" xlink:title="see committed changes">
  74                         https://github.com/rsoulliere/Evergreen-DocBook/commits/master</link>. </listitem>
  75                 </itemizedlist>
  76                         <tip><para>If possible, please test files locally or verify DocBook syntax is correct. The docBook files are generated every night to update the HTML and PDF files.
  77                         Incorrect DocBook syntax could cause the chapter to be skipped during processing and not be included in the documentation.</para></tip>
  78                 <procedure>
  79                         <title>Contributing by editing existing files on github</title>
  80                         <step>
  81                                 <note><para>Editing files directly in github using the following procedures is not recommended for larger changes, but is useful for quick typo corrections and other
  82                                 minor edits. If you need to makke major changes please use the previous git method or send changes to the
  83                                 <link xlink:href="http://libmail.georgialibraries.org/mailman/listinfo/open-ils-documentation" xlink:title="DIG List">DIG list</link>.</para></note>
  84                                 <para><link xlink:href="https://github.com/" xlink:title="get an account">Sign up for a free github account.</link>.</para>
  85                         </step>
  86                         <step>
  87                                 <para>Send an email to the  repository maintainer (<email>robert.soulliere@mohawkcollege.ca</email>) to request being added as a contributor.</para>
  88                         </step>
  89                         <step>
  90                                 <para>Go to the github repository at <link xlink:href="https://github.com/rsoulliere/Evergreen-DocBook"
  91                                 xlink:title="github repo">https://github.com/rsoulliere/Evergreen-DocBook</link></para>
  92                         </step>
  93                         <step>
  94                                 <para>Navigate to the file you would like to edit and click <guibutton>Edit this file</guibutton></para>
  95                         </step>
  96                         <step>
  97                                 <para>Make changes, enter your change notes in the <guilabel>Commit message</guilabel> box and click <guibutton>Commit Changes</guibutton>.</para>
  98                         </step>
  99                 </procedure>
 100                 <para>If you are unconfortable committing Documentation in DocBook format, simply submit your text documents or suggested changes to the
 101                 <link xlink:href="http://libmail.georgialibraries.org/mailman/listinfo/open-ils-documentation" xlink:title="DIG List">DIG list</link> and we will convert them to XML DocBook format
 102                 or add your changes to the documentation.</para>
 103         </section>
 104 </chapter>