Welcome the company of trees

Writing articles for treecutter

2012-04-24

Abstract

If you want to help out and contribute with larger bodies of text or translations, this document details what you need to help out with a treecutter site.


Prerequisites

First of all you need some software. You need a good editor and the software downloading the articles. There are several types of editors, but recommended is a XML aware text editor that also works in the Unix/Linux environment. The software to download articles is named Git. The format of the articles are Docbook. There we have three new concepts to look at : XML text editor, Git and Docbook.

Text editor

There are several alternatives for Windows. If you just want to start editing I think the simplest to install notepad++ and get started. If you want to become more advanced with your text editing I recommend you to have a look at Emacs. A very powerful editor but also hard to learn.

Git

First you need to install git. Download and install the latest version of Git for Windows.

Docbook

To start editing a docbook document the easiest way is to download the site and start looking at the existing documents. To add an new document it might be easiest to copy an existing document or to use a template. Naming convention for the document should be discussed with the site owner, but the format is name.languagecode.xml. Language code is one of the valid ISO 639 two letter codes. Example: article.en.xml.

A good start for more detailed look at different tags or concepts in docbook is DocBook 5.1: The Definitive Guide. It also contains chapters detailing the background of the standard, but the Reference part describe each tag or section one can use in docbook. This is a starting point when trying to describe the content better.

From this content then HTML and PDFs are generated. The styling is done separately from the content. The styling has to be discussed with the site owner and is part of the site generation step.

Getting to work

Now the tools are installed you have a directory on your hard drive that is just waiting to get the content. You should have some information from the developer of the site.

  1. User name

  2. Password or SSH key

  3. Git repository link

  4. An agreed area to work on

First we need to set git up. Open the icon Git Bash. You will now end up in a text based shell. It might look complicated but it is not.

git config --list

. For windows you need to make some settings.

git config --global
    core.ignorecase true

is important to not confuse filenames between Linux and Windows.

Then you need to present yourself to git so that your changes to the project will be registered with your name.

git
    config --global user.name "your name here"

and

git config --global user.email "your email
    here"

.

Now you can check out the project in a directory of your choice.

git clone "username@https://example.com/git/repository"
    "C:\gitprojects\name"

. Now you can go to the directory and open the files with the notepad++ editor.

Git work flow is a bit tricky to learn and to understand if you have not used such a system before. There are really a few basic commands you need to know. clone - copy a project, add - add changes, commit - make the changes permanent with a message explaining the changes, push - send the committed changes to the project, pull - check for updates from other people.

There are of course a whole world of more complex operations and The Git Community Book and Git Pro are two starting points to learn more.

Work with a Git Bash window and an explorer window of the project files. In Git Bash, cd /c/gitprojects/name. Now open a document in the explorer window with notepad++ and change something. Save. You can direct see the changes by doing

git
    diff

in the Git Bash window. Once your changes have reached a certain point, that they feel like a package. Now you can commit the changes.

git add
    file-that-changed

. Commit your changes by

git
    commit

. Now you get to write a short summary of your changes. The message format is well defined , try to use the convention, the tools are built around it.