Contributing Documentation in DocBook FormatEvergreen Documentation File StructureAt the root of the Evergreen documentation is the root.xml 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:
...
]]>The above example includes the glossary.xml file in the Evergreen documentation. This file should be located in the
appendixes subdirectory relative to the root.xml file.When creating new files, the first line should always be:
]]>This is the standard to indicate that this is an XML fileThe next line should include the <chapter> element. Here is an example for the glossary chapter of this style guide document.
]]>An important attribute is xml:id. 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.Also remember to add the closing </chapter> tag at the very end of the document.The chapter is the container for files contributed to DIG. Do not create a new file to add a <section> to an existing
<chapter> and do not use the <book> container in yor file since the
<book> element is already in the root.xml file.How to Contribute DocumentationUsing Git to Upload Files from LinuxInstall git.Sign up for a free github account..Send an email to the github repository maintainer (robert.soulliere@mohawkcollege.ca) to request being added as a contributor.Generate and add SSH keys to github repository..Clone the Evergreen-DocBook repository on your local machine:git clone git@github.com:rsoulliere/Evergreen-DocBook.gitEdit or add files in the cloned repository location.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):git pull - It will pull the most recent changes into your cloned version to avoid merging
issues and errors when pushing your changes to the remote repository.git add - 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.git commit - 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.git push - Push changes to remote repository. After pushing your changes you should see them show up at:
https://github.com/rsoulliere/Evergreen-DocBook/commits/master. 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.Contributing by editing existing files on githubEditing 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
DIG list.Sign up for a free github account..Send an email to the repository maintainer (robert.soulliere@mohawkcollege.ca) to request being added as a contributor.Go to the github repository at https://github.com/rsoulliere/Evergreen-DocBookNavigate to the file you would like to edit and click Edit this fileMake changes, enter your change notes in the Commit message box and click Commit Changes.If you are unconfortable committing Documentation in DocBook format, simply submit your text documents or suggested changes to the
DIG list and we will convert them to XML DocBook format
or add your changes to the documentation.