+++ /dev/null
-<?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 / blobdiff