Translating LinuxCNC Documentation

: 1. Install Git
: 2. Configure Git
: 3. Files
: 4. Building the Documents
: 5. Committing your Changes
: 6. Creating a Patch
: 7. Translating LinuxCNC messages

1. Install Git

Install git-core, git-gui and gitk. From a terminal say:

  sudo sudo apt-get install git-core git-gui gitk

2. Configure Git

Once you have git-core, git-gui and gitk installed on your computer you have to configure it.

Open a terminal and do the following with your name and email:

 git config --global user.name "Your full name"
 git config --global user.email "you@example.com"

Next do an anonymous checkout like so:

 git clone git://git.linuxcnc.org/git/emc2.git linuxcnc-dev

Then switch to the 2.5 branch like so:

 cd linuxcnc-dev
 git checkout -b v2.5_branch origin/v2.5_branch

To verify you have the 2.5 branch use this command from within a git directory:

 git branch

which should say:

   master
 * v2.5_branch

the * indicates the current branch.

Now when you open up a txt file to edit you can be sure your editing the correct branches file.

3. Files

The documentation files are in /linuxcnc-dev/docs/src. The master docs are Master_xxx.txt. The master docs contain mostly the filenames of the documents so normally you won't edit them The only text you can edit is text that starts with the equal sign like this:

 = Getting Started

In each directory of docs/src the text files for each section are located. To edit a file first do a git pull --rebase to make sure your current and then copy the English over the one to be translated with the proper extension.

You must be very careful not to change formatting of links, anchors and titles or it will not build. For example:

 = Level 0 Title <must be the first line of the text file
 < must have a blank line here
 [[cha:level-0-title]] (((Level 0 Title))) <first one is the anchor, second one is the TOC link.

 == Level 1 Title <this should be the next line and you will see this

when you open the files.

<<cha:level-0-title,Level 0 Title>> < this is a link and the text after the , can be translated but the text before the , should not unless you are positive you have changed every link and the anchor.

Before translating a file always do a git pull --rebase to make sure your working on the most current file, otherwise the patch may fail.

After translating one txt file build and check for errors before creating a patch... I know this sounds a bit complicated but once you do it a few time it will be automatic.

4. Building the Documents

To build open a terminal and substitute john with your computer name and do the following:

 cd emc2-dev/src

 ./autogen.sh

 ./configure --enable-build-documentation >> /home/john/Desktop?/configure.txt 2>&1

 make >> /home/john/Desktop?/make.txt 2>&1

This creates two files on your desktop, the reason I redirect the output to a file is to not loose any information. After make is done open the make.txt file and search for warning and error. If you have any then fix them before creating a patch. Also look at the end of the make file to see that is says ????

5. Committing your Changes

Next run git-gui in a terminal and you should see the file you changed.

 cd linuxcnc-dev
 git gui

Stage the change by either clicking on the file name or the stage changed button. Next enter a description in the Commit Message box.

Docs: translate to ...

or similar. Then press Sign Off and notice that it puts your name and email in the commit message box. Next press commit. You can click on repository visualize 2.5 branch history and see your commit.

6. Creating a Patch

Make sure your current with

 git pull --rebase

then create the patch of your last commit

 git format-patch -1

When the patch is ok you can email or post the .patch file. If you make several commits and want to put them in a single mbox file:

 mv *.patch /tmp                ;# move old patches somewhere else
 git format-patch -3            ;# -3 is for your last three commits
 cat 0*.patch >| shortname.mbox ;# catenate all patches into single mbox file

7. Translating LinuxCNC messages

Information on translating the messages used when a GUI is displayed look [here].

Translation