Writing articles for treecutter
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.
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.
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.
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.
Password or SSH key
Git repository link
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"
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.
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
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
. 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.