TipsForContributing

If you wonder what this is all about got to GimpDocs.

  1. How can I contribute?
    1. The mailing list
  2. Preliminaries
    1. Sandbox on Windows
    2. Create a local working copy
    3. Installing
  3. Working as a translator
    1. Creating/Updating POT
    2. Creating/Updating PO files
    3. Managing PO files
      1. Essential requirements
      2. Structure of a PO file
      3. Validating your PO file and creating localized xml files
      4. Creating html files
      5. Some tips
    4. Images
      1. Hints for making good screen-shots
      2. Validating image references
    5. Routine work
      1. Creating patches
  4. Working as a doc-writer
    1. Editing XML files
    2. Validating XML files
    3. Creating a new XML file
    4. Image paths
  5. The GIMP manual build system
    1. The default Makefile
    2. The Makefile.GNU (experimental)

How can I contribute?

A good idea of start contributing to the manual is by subscribing to the mailing list. People who start working on the mailing list may have a lot of questions about setting up a sandbox on their preferred OS, which can be answered on the mailing list.

There are three main things to accomplish:

  1. Join our mailing list

  2. Create a local working copy for yourself

  3. Getting started with the local copy

  4. Test your changes and and send us your patches

The mailing list

You can subscribe to our mailing list [WWW] https://lists.xcf.berkeley.edu/mailman/listinfo/gimp-docs/ here.

Preliminaries

Sandbox on Windows

To create a gimp-help-2 environment on MS Windows is explained on a subpage:

Create a local working copy

The local working copy from our module makes sure, that everyone can work on his own without fuzzing around into others work. This means, you'll need to learn how to create an initial checkout out of the GIT repository and stay up to date. Please keep in mind, that the procedure for accessing the GNOME SVN servers anonymously and using an existing and valid GNOME account are slightly different. See [WWW] http://live.gnome.org/Git this doc and [WWW] http://live.gnome.org/TranslationProject/GitHowTo for details on how to checkout and manage your checkout.

Installing

After downloading you local copy (your "sand box"), you must run 

./autogen.sh --without-gimp

or - even better - configure the languages too: 

./autogen.sh --without-gimp ALL_LINGUAS="en xx"

where "en" is the language code for "English", and "xx" is your language code (see below).

If you are going to translate for a new language which doesn't exist yet in the autogen.sh display, you have to edit the trunk/configure.ac file and add your language in lines 36 and 39 (alphabetical order): 

QUICKREFERENCE_ALL_LINGUAS="de en fi fr it ko ru sv"
 if test "x$ALL_LINGUAS" = "x"; then
 ALL_LINGUAS="de en es fr it ko nl no pl ru sv"

else you will not be able to built your PO files. ISO 639-1 language codes can be found at [WWW] http://www.loc.gov/standards/iso639-2/php/code_list.php.

Working as a translator

We are now using "gettext" and the PO file system. A full help about "gettext" can be found at [WWW] http://www.gnu.org/software/gettext/manual/gettext.html. We are going to describe some useful features. Most of them have been included in specific commands such as make pot, make xml-xx...

Gimp-help is maintained in the xml files of the "src" folder. English is the reference language. These xml files are used by doc-writers. As a translator, you will not use them.

For translator convenience, PO files gather several XML file data together. They will be splitted in separate HTML files.

Creating/Updating POT

POT files (Portable Object Template) are english templates to be translated to other languages. They are not downloaded and you have to create/update them by running 

make pot

This creates/updates a "pot" folder.

/!\ Don't modify pot files. They are created from xml files.

If you have an inquiring mind, open a POT file in a text editor. You will see that it is made of a list of english strings in msgid tags and empty msgstr ready for translation. Example: 

msgid "What's New in GIMP 2.6?"
msgstr ""

Creating/Updating PO files

A blank PO file is like the corresponding POT file. You will write your translation in the msgstr tag.

To create/update PO files, run 

make po-xx

where xx is your language (de, es, it...). This creates/updates a "po/xx" directory.

Managing PO files

Essential requirements

To edit PO files, you can use e.g. Kbabel or gtranslator under Linux and po-edit under Windows. You can use a text editor as well. e.g. Kate under Linux, NotePad++ under Windows.

Structure of a PO file

PO file header

The PO file header is created by "gettext" when creating the PO. It is automatically filled by Kbabel. To see it, open it in a text editor. 

#, fuzzy
msgid ""
msgstr ""
"Project-Id-Version: PACKAGE VERSION\n"
"POT-Creation-Date: 2009-01-25 20:53+0100\n"
"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
"Language-Team: LANGUAGE <LL@li.org>\n"
"MIME-Version: 1.0\n"
"Content-Type: text/plain; charset=UTF-8\n"
"Content-Transfer-Encoding: 8bit\n"

The uppercase entries are to be replaced by your values:

PACKAGE VERSION: You can use "GIMP-2.6-HELP" here.

2009-01-25 20:53+0100: This date is automatically filled by "make pot".

YEAR-MO-DA HO:MI+ZONE: This will be replaced with the proper values if you edit the po files with a translation tool like Kbabel or gtranslator, otherwise you'll have to enter the date of your revision, in this format. For example: 2009-02-28. The hour [HO]MI is important o if there are a lot of translators working on this file.

FULL NAME <EMAIL@ADDRESS>: Enter your full name and email address.

LANGUAGE <[MAILTO] LL@li.org>: if you belong to a translation team, enter its name and email address here. Else, just enter "none".

The other values are not to be modified. When your header is ready, delete the "#, fuzzy" line.

Comments

Lines beginning with "#" are comments. They provide the translator with some additional information.

Strings
msgid "Activating the dialog"
msgstr ""

"msgid" are the English strings to be translate

"msgstr" are translated strings.

A bug(?)

The xml2po tool used to create PO files sometimes works in a strange and annoying way: some tags (for instance <guiicon> tags) are replaced with <placeholder> tags, and you'll find text like this in some PO files: 

msgid "... clicking on <placeholder-1> ..."

Don't worry about that and don't change them: HTML files will be created correctly.

Sometimes even text is replaced like shown above, and the replaced text is usually provided a few lines above as a separate msgid. Well, that is a bug...

Validating your PO file and creating localized xml files

You could use the gettext command "msgfmt" or "xmllint" to validate, but rather use 

make validate-xx

This will validate PO-files and create xml files for your language in xml/xx/. If there are errors in your PO files, they will be displayed with path and line of the errors. The error messages will be cached in the file "log/xx-xmllint.log".

You can also try 

make xml-xx

which will just create the xml files (without checking if the result is valid DocBook) and may also output warnings or error messages.

Creating html files

Once localized xml files have been created, you can create html files: 

make html-xx

to create all html files, or

{{ make preview-xml/xx/.../doc.xml }}} or 

make xml/xx/.../doc.draft

where "doc" is the name of the xml file, to create a html preview.

Please note the name of the html draft in the console display, because the name of the html file is the "id=..." of the xml file, which often is different from that of the xml file (for instance, the name of the html file resulting from the "close.xml" file is "gimp-file-close.html").

Some tips

make status-xx

Under Linux, Konqueror file browser displays PO file icons as a circle with a red sector for untranslated strings, a green sector for translated strings and a blue sector for fuzzy strings. So, you have status of all PO files at a glance. 

make po/xx/.../doc.po

make html-xx

cd trunk/html/xx/
aspell check gimp-file-close.html --lang=xx

Available dictionaries can be found at [WWW] ftp://ftp.gnu.org/gnu/aspell/dict/ .

Images

You also have to manage screen-shots. They are in trunk/images. If you don't create a localized image for you language, the English image, in trunk/C, will be used by default.

Hints for making good screen-shots

Validating image references

You can verify that all images are present by opening your HTML files in your Weg browser.

You can also use a python script, "validate_references.py" that you will find in trunk/tools. help for this script is in the README file in the same directory. Of course, python must be installed on your machine.

Routine work

You managed to checkout the module and you have created your PO files. Before changing any text, be sure to update your working copy. That means, you're getting changes from other docwriters merged into the english XML source. To update your working copy, change into your gimp-help-2 main trunk directory and use the following command: 

 git pull --rebase

Then update POT files and your PO files: 

make pot

make po-xx

Changed strings will be marked as fuzzy in PO files.

Removed strings will be added as comments at the end of PO files. You can delete them if you want.

Edit your PO files.

Validate your PO files by creating html. Check changed html files, especially for missing images

And when all is ready, commit your changes

Creating patches

To contribute without write access to the repository, you can create patches using git. Git creates patches of your last local commits: 

git format-patch

Read more about how to contribute patches on [WWW] http://live.gnome.org/Git/Developers#head-28386038e4a0c4659205c81d6e40fe5bb8bab881

Working as a doc-writer

GIMP help continuously needs to be updated and improved and there aren't many of contributors to this work. If you want to participate, you must know english, not perfectly but enough to be understable by everybody in the world.

The XML documents are hold in the "src" subdirectory. The root document is gimp.xml and tieds every file together. We're using [WWW] XML Includes to chunk the manual in smaller pieces. The translations are separated during the build process by the profiling process.

Editing XML files

You will edit src/xml files and you have to get acquainted with the xml language. Don't be afraid: xml file structure exists yet and you will learn progressively, referring if necessary to [WWW] http://docbook.org/en/html/ .

Your text editor, "kate" under Linux, "NotePad++" under Windows must be set for

Validating XML files

To validate XML files, use 

make validate

This will validate XML files of the "src/" folder.

The result of "make validate" is displayed in the console. If all is right, you will get a "No error" message. Errors can be of two types: "parser-errors" which are errors in the XML structure and "validate errors" which may result from parser errors or be due to some weird cause. Here is an example (we introduced an error in src/menus/file/close.xml, deleting the "/" of </menuchoice> in line 58): 

*** Validating XML (en) ...
xml/en/menus/file/close.xml:59: parser error : Opening and ending tag mismatch: menuchoice line 58 and para
        </para>
               ^
xml/en/menus/file/close.xml:60: parser error : Opening and ending tag mismatch: menuchoice line 55 and listitem
      </listitem>
                 ^
xml/en/menus/file/close.xml:85: parser error : Opening and ending tag mismatch: para line 53 and itemizedlist
    </itemizedlist>
                   ^
xml/en/menus/file/close.xml:86: parser error : Opening and ending tag mismatch: listitem line 52 and sect3
  </sect3>
          ^
xml/en/menus/file/close.xml:87: parser error : Opening and ending tag mismatch: itemizedlist line 51 and sect2
</sect2>
        ^
xml/en/menus/file/close.xml:88: parser error : Premature end of data in tag sect3 line 47

^
xml/en/menus/file/close.xml:88: parser error : Premature end of data in tag sect2 line 7

^
xml/en/menus/file.xml:33: element include: XInclude error : could not load xml/en/menus/file/close.xml, and no fallback was found
-:41053: namespace error : Namespace prefix xi on include is not defined
  <xi:include href="file/close.xml"/>
                                   ^
-:41053: element include: validity error : No declaration for attribute href of element include
  <xi:include href="file/close.xml"/>
                                   ^
-:41053: element include: validity error : No declaration for element include
  <xi:include href="file/close.xml"/>
                                     ^
-:41167: element sect1: validity error : Element sect1 content does not follow the DTD, expecting (sect1info? , (title , subtitle? , titleabbrev?) , (toc | lot | index | glossary | bibliography)* , (((calloutlist | glosslist | itemizedlist | orderedlist | segmentedlist | simplelist | variablelist | caution | important | note | tip | warning | literallayout | programlisting | programlistingco | screen | screenco | screenshot | synopsis | cmdsynopsis | funcsynopsis | classsynopsis | fieldsynopsis | constructorsynopsis | destructorsynopsis | methodsynopsis | formalpara | para | simpara | address | blockquote | graphic | graphicco | mediaobject | mediaobjectco | informalequation | informalexample | informalfigure | informaltable | equation | example | figure | table | msgset | procedure | sidebar | qandaset | task | anchor | bridgehead | remark | highlights | abstract | authorblurb | epigraph | indexterm | beginpage)+ , (refentry* | sect2* | simplesect*)) | refentry+ | sect2+ | simplesect+) , (toc | lot | index | glossary | bibliography)*), got (title indexterm sect2 sect2 sect2 sect2 sect2 sect2 sect2 sect2 sect2 sect2 sect2 sect2 sect2 include sect2 sect2 )
</sect1>
        ^
(You will find log and xml files in log/.)

A very verbose result! Fortunately, most items are superfluous.

The parser error in line 58 results also in error in every XML structure containing the <(/)include> tag. The explanations displayed here are clear. That's not always the case. In difficult cases or when there are several parser errors, it may be interesting to open the XML file in a Web browser, Firefox for example. Here is the result of opening "close.xml" in Firefox: 

XML Parser Error: not corresponding tag. Waited : </menuchoice>.
Place : file:///home/julien/SVN-po/trunk/src/menus/file/close.xml
Line number 59, Column 11 :        
</para>
----------^

You resolve the error in the XML file, you save the file and you press the Refresh button in Firefox which, then, displays the XML file correctly.

In the console display, you can see a validate error in src/menus/file.xml. "close.xml" has not been validated and the system cannot find it. The case is evident here. In some cases, localizing the error -- in which file is it? -- can be difficult. Then you can use the number you see: 41053. This is a line number in the huge trunk/log/en-xml file. Open close.xml in Kate, type Ctrl-G and enter this number to go directly to this line in order to localize the validate error.

Line 41167: This kind of validate error appears when there is an error in the XML structure. Two parts in this display: "expecting" and "got". You can see some "?, *, +". They have the same meaning as in [WWW] http://docbook.org/en/html/:

Creating a new XML file

To create a new XML file, you can use a template that you can find in trunk/docs/templates.

Don't invent an "id=" for a file describing a non-documented command in the GIMP User Interface. You must search for the "id" by running GIMP

selecting the non-documented command and pressing F1. An error message will be displayed in the console with the "id".

You must add an include link to this file in src/gimp.xml or in another file such as src/menus/menus-filters.xml for example.

Image paths

Image paths must be in the form "fileref="images/toolbox/tools-threshold.png", not mentionning the C directory. "make xml-xx" will create "images/xx/toolbox/tools-threshold.png" automatically if this image exists, else the English image will be used by default.

The GIMP manual build system

We use the GNU tools automake, autoconf, and make for building the manual (HTML, PDF, ODF).

However, as a translator or doc-writer you will only have to use the following commands:

The default Makefile

The file Makefile contains dependencies and rules which are required for building the manual and - if necessary - any intermediate files. Once this files exists, you'll have to type 

make <target>

on the command line to create <target> (the targets are described above).

The Makefile will be created or updated with 

./autogen.sh ...

as described above ("Installing").

There is, however, a problem you should be aware of: Since we make use of some special make features which the default configuring routine can't handle, we have added an ugly workaround for now. As a consequence, ...

... you have to re-run ./autogen.sh whenever Makefile.am has been changed!

And yes, this is a bug and we'll have to fix it... :\

The Makefile.GNU (experimental)

We are thinking about to drop the autotools and just work with a manually created Makefile and maybe a simple manually created configure script. That's why we have another makefile, Makefile.GNU, for testing and experimenting. You can use it with 

make -f Makefile.GNU <target>

instead of "make <target>".

For now, Makefile.GNU is more or less identical with Makefile (except that is is more readable :) ) and you can use the same commands as described below.

Ok, to tell the truth, there are some differences:

last edited 2009-06-21 05:14:10 by RomanJoost