-<?xml version="1.0" encoding="utf-8"?>\r
-<chapter xml:id="style-contributing" xmlns="http://docbook.org/ns/docbook" version="5.0" xml:lang="EN"\r
- xmlns:xi="http://www.w3.org/2001/XInclude" xmlns:xlink="http://www.w3.org/1999/xlink">\r
- <info>\r
- <title>Contributing Documentation in DocBook Format</title>\r
- </info>\r
-\r
- <section xml:id="docbook_file_structure">\r
- <title>Evergreen Documentation File Structure</title>\r
- \r
- <para>At the root of the Evergreen documentation is the <filename>root.xml</filename> file. The file contains the <book> element and manages the organization of the \r
- 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 \r
- have to edit this file except to add an include statement to place a new chapter in the Evergreen documentation in appropriate order:</para>\r
-<programlisting><![CDATA[\r
-...\r
-<xi:include href="appendices/glossary.xml"/>\r
-...\r
-]]></programlisting>\r
- <para>The above example includes the <filename>glossary.xml</filename> file in the Evergreen documentation. This file should be located in the \r
- <filename class="directory">appendixes</filename> subdirectory relative to the <filename>root.xml</filename> file.</para> \r
- <para>When creating new files, the first line should always be:</para>\r
-<programlisting> <![CDATA[\r
-<?xml version="1.0" encoding="utf-8"?> \r
-]]></programlisting>\r
- <para>This is the standard to indicate that this is an XML file</para>\r
- <para>The next line should include the <chapter> element. Here is an example for the glossary chapter of this style guide document.</para>\r
-<programlisting> <![CDATA[\r
-<chapter xml:id="style-glossary" xmlns="http://docbook.org/ns/docbook" version="5.0" xml:lang="EN"\r
- xmlns:xi="http://www.w3.org/2001/XInclude" xmlns:xlink="http://www.w3.org/1999/xlink">\r
-]]></programlisting>\r
- <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 \r
- and other parts of the documentation.</para> \r
- <para>Also remember to add the closing </chapter> tag at the very end of the document.</para> \r
- <para>The chapter is the container for files contributed to DIG. Do not create a new file to add a <code language="xml"><section></code> to an existing \r
- <code language="xml"><chapter></code> and do not use the <code language="xml"><book></code> container in yor file since the \r
- <code language="xml"><book></code> element is already in the <filename>root.xml</filename> file.</para> \r
- </section>\r
-<section xml:id="how_to_contribte">\r
- <title>How to Contribute Documentation</title>\r
- <procedure>\r
- <title>Using Git to Upload Files from Linux</title>\r
- <step>\r
- <para><link xlink:href="http://help.github.com/linux-git-installation/" xlink:title="Install git">Install git</link>.</para> \r
- </step>\r
- <step>\r
- <para><link xlink:href="https://github.com/" xlink:title="get an account">Sign up for a free github account.</link>.</para> \r
- </step>\r
- <step>\r
- <para>Send an email to the github repository maintainer (<email>robert.soulliere@mohawkcollege.ca</email>) to request being added as a contributor.</para> \r
- </step>\r
- <step>\r
- <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>\r
- </step> \r
- <step>\r
- <para>Clone the Evergreen-DocBook repository on your local machine:</para>\r
-<screen><userinput>git clone git://github.com/rsoulliere/Evergreen-DocBook.git</userinput></screen>\r
- </step> \r
- <step>\r
- <para>Edit or add files in the clonesd repository location.</para>\r
- </step> \r
- </procedure>\r
- <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 \r
- repository):</para> \r
- <itemizedlist>\r
- <listitem><command>git pull <option>filename</option></command> - It will pull the most recent changes into your cloned version to avoid merging \r
- issues and errors when <quote>pushing</quote> your changes tp the remote repository.</listitem>\r
- <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 \r
- them into the repo.</listitem>\r
- <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 \r
- meainingful note here to indicate \r
- what you have chanaged.</listitem>\r
- <listitem><command>git push <option>filename</option></command> - Push changes to remote repository. After pushing your changes you should see them show up at: \r
- <link xlink:href="https://github.com/rsoulliere/Evergreen-DocBook/commits/master" xlink:title="see committed changes">\r
- https://github.com/rsoulliere/Evergreen-DocBook/commits/master</link>. </listitem>\r
- </itemizedlist>\r
- <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. \r
- Incorrect DocBook syntax could cause the chapter to be skipped during processing and not be included in the documentation.</para></tip>\r
- <procedure>\r
- <title>Contributing by editing existing files on github</title>\r
- <step>\r
- <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 \r
- minor edits. If you need to makke major changes please use the previous git method or send changes to the \r
- <link xlink:href="http://libmail.georgialibraries.org/mailman/listinfo/open-ils-documentation" xlink:title="DIG List">DIG list</link>.</para></note>\r
- <para><link xlink:href="https://github.com/" xlink:title="get an account">Sign up for a free github account.</link>.</para> \r
- </step>\r
- <step>\r
- <para>Send an email to the repository maintainer (<email>robert.soulliere@mohawkcollege.ca</email>) to request being added as a contributor.</para> \r
- </step>\r
- <step>\r
- <para>Go to the github repository at <link xlink:href="https://github.com/rsoulliere/Evergreen-DocBook" \r
- xlink:title="github repo">https://github.com/rsoulliere/Evergreen-DocBook</link></para>\r
- </step> \r
- <step>\r
- <para>Navigate to the file you would like to edit and click <guibutton>Edit this file</guibutton></para>\r
- </step> \r
- <step>\r
- <para>Make changes, enter your change notes in the <guilabel>Commit message</guilabel> box and click <guibutton>Commit Changes</guibutton>.</para>\r
- </step> \r
- </procedure>\r
- <para>If you are unconfortable committing Documentation in DocBook format, simply submit your text documents or suggested changes to the \r
- <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 \r
- or add your changes to the documentation.</para>\r
- </section>\r
-</chapter>\r
+<?xml version="1.0" encoding="utf-8"?>
+<chapter xml:id="style-contributing" xmlns="http://docbook.org/ns/docbook" version="5.0" xml:lang="EN"
+ xmlns:xi="http://www.w3.org/2001/XInclude" xmlns:xlink="http://www.w3.org/1999/xlink">
+ <info>
+ <title>Contributing Documentation in DocBook Format</title>
+ </info>
+
+ <section xml:id="docbook_file_structure">
+ <title>Evergreen Documentation File Structure</title>
+
+ <para>At the root of the Evergreen documentation is the <filename>root.xml</filename> file. The file contains the <book> element and manages the organization of the
+ 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
+ have to edit this file except to add an include statement to place a new chapter in the Evergreen documentation in appropriate order:</para>
+<programlisting><![CDATA[
+...
+<xi:include href="appendices/glossary.xml"/>
+...
+]]></programlisting>
+ <para>The above example includes the <filename>glossary.xml</filename> file in the Evergreen documentation. This file should be located in the
+ <filename class="directory">appendixes</filename> subdirectory relative to the <filename>root.xml</filename> file.</para>
+ <para>When creating new files, the first line should always be:</para>
+<programlisting> <![CDATA[
+<?xml version="1.0" encoding="utf-8"?>
+]]></programlisting>
+ <para>This is the standard to indicate that this is an XML file</para>
+ <para>The next line should include the <chapter> element. Here is an example for the glossary chapter of this style guide document.</para>
+<programlisting> <![CDATA[
+<chapter xml:id="style-glossary" xmlns="http://docbook.org/ns/docbook" version="5.0" xml:lang="EN"
+ xmlns:xi="http://www.w3.org/2001/XInclude" xmlns:xlink="http://www.w3.org/1999/xlink">
+]]></programlisting>
+ <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
+ and other parts of the documentation.</para>
+ <para>Also remember to add the closing </chapter> tag at the very end of the document.</para>
+ <para>The chapter is the container for files contributed to DIG. Do not create a new file to add a <code language="xml"><section></code> to an existing
+ <code language="xml"><chapter></code> and do not use the <code language="xml"><book></code> container in yor file since the
+ <code language="xml"><book></code> element is already in the <filename>root.xml</filename> file.</para>
+ </section>
+<section xml:id="how_to_contribte">
+ <title>How to Contribute Documentation</title>
+ <procedure>
+ <title>Using Git to Upload Files from Linux</title>
+ <step>
+ <para><link xlink:href="http://help.github.com/linux-git-installation/" xlink:title="Install git">Install git</link>.</para>
+ </step>
+ <step>
+ <para><link xlink:href="https://github.com/" xlink:title="get an account">Sign up for a free github account.</link>.</para>
+ </step>
+ <step>
+ <para>Send an email to the github repository maintainer (<email>robert.soulliere@mohawkcollege.ca</email>) to request being added as a contributor.</para>
+ </step>
+ <step>
+ <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>
+ </step>
+ <step>
+ <para>Clone the Evergreen-DocBook repository on your local machine:</para>
+<screen><userinput>git clone git://github.com/rsoulliere/Evergreen-DocBook.git</userinput></screen>
+ </step>
+ <step>
+ <para>Edit or add files in the cloned repository location.</para>
+ </step>
+ </procedure>
+ <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
+ repository):</para>
+ <itemizedlist>
+ <listitem><command>git pull <option>filename</option></command> - It will pull the most recent changes into your cloned version to avoid merging
+ issues and errors when <quote>pushing</quote> your changes to the remote repository.</listitem>
+ <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
+ them into the repo.</listitem>
+ <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
+ meaningful note here to indicate
+ what you have chanaged.</listitem>
+ <listitem><command>git push <option>filename</option></command> - Push changes to remote repository. After pushing your changes you should see them show up at:
+ <link xlink:href="https://github.com/rsoulliere/Evergreen-DocBook/commits/master" xlink:title="see committed changes">
+ https://github.com/rsoulliere/Evergreen-DocBook/commits/master</link>. </listitem>
+ </itemizedlist>
+ <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.
+ Incorrect DocBook syntax could cause the chapter to be skipped during processing and not be included in the documentation.</para></tip>
+ <procedure>
+ <title>Contributing by editing existing files on github</title>
+ <step>
+ <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
+ minor edits. If you need to makke major changes please use the previous git method or send changes to the
+ <link xlink:href="http://libmail.georgialibraries.org/mailman/listinfo/open-ils-documentation" xlink:title="DIG List">DIG list</link>.</para></note>
+ <para><link xlink:href="https://github.com/" xlink:title="get an account">Sign up for a free github account.</link>.</para>
+ </step>
+ <step>
+ <para>Send an email to the repository maintainer (<email>robert.soulliere@mohawkcollege.ca</email>) to request being added as a contributor.</para>
+ </step>
+ <step>
+ <para>Go to the github repository at <link xlink:href="https://github.com/rsoulliere/Evergreen-DocBook"
+ xlink:title="github repo">https://github.com/rsoulliere/Evergreen-DocBook</link></para>
+ </step>
+ <step>
+ <para>Navigate to the file you would like to edit and click <guibutton>Edit this file</guibutton></para>
+ </step>
+ <step>
+ <para>Make changes, enter your change notes in the <guilabel>Commit message</guilabel> box and click <guibutton>Commit Changes</guibutton>.</para>
+ </step>
+ </procedure>
+ <para>If you are unconfortable committing Documentation in DocBook format, simply submit your text documents or suggested changes to the
+ <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
+ or add your changes to the documentation.</para>
+ </section>
+</chapter>
projects / Evergreen-DocBook.git / commitdiff