TipsForContributing

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

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 mailinglist 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

Sandbox on Windows

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

• GimpDocsWindowsSandbox

The mailinglist

You can subscribe to our mailinglist here.

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 learn how to create an initial checkout out of the SVN and staying 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 this doc for details.

You'll be able to make a svn checkout from the current gimp-help-2 in the gnome subversion repository. Just follow these steps to checkout the module as an anonymous user: Type in your terminal (I assume that you'll use bash):

svn checkout http://svn.gnome.org/svn/gimp-help-2/trunk/

If instead you already have a svn gnome account, type:

svn checkout svn+ssh://(username)@svn.gnome.org/svn/gimp-help-2/trunk

as with cvs, with svn, you can always use the command short form

svn co http://svn.gnome.org/svn/gimp-help-2/trunk/

Getting started with the local copy

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

svn update

or

svn up

The XML documents are hold in the "src" subdirectory. The root document is gimp.xml and tieds every file together. We're using XML Includes to chunk the manual in smaller pieces. The translations are seperated during the build process by the profiling process and besides every english content, indicated by a language attribute (lang) and the language id.

Most people start translating, going through every file from the root to every sibling document, which is wrong. Start by orienting chapter, section-wise; just focus on the content. We recommend translating the tools at first. The content won't change a lot.

The profiling process, as mentioned above, pics every language attribute and decides if the content included in the tag should be used in the profiled xml version or not. Eg.:

   gimp.xml--<para lang="de;en"> --> de.xml
                                 --> en.xml

How the processor is picking the right content, depends besides the language attribute in the tag also on the language attribute on the tag above. Two examples to illustrate this: XML code before profiling:

   <listitem lang="en">
     <para lang="de">
      ...
     </para>
   </listitem>

XML code after profiling the english and german version:

      en.xml                                  de.xml
    <listitem lang="en">                      ... (nothing)
    </listitem>

During profiling for english, the "german" para is not included in the english version, because the lang attribute contains a "de". The german instead contains no listitem and no para, because the lang attribute before the para says: "Prefer only tags with the lang id >>en<<"

Test your changes

To be able to build the HTML files or other formats for your language, edit configure.in and add your language id to ALL_LINGUAS. If you're unsure, what the correct docbook language id for your language is, look in the Docbook FAQ

Example: ALL_LINGUAS='en fr sv' now I want to build german HTML files: ALL_LINGUAS='en fr sv de'

Now you should be able to test your changes with: make validate which then profiles the XML contents for each language and validates the profiled XML. If there are errors, look in the xml subdirectory for the log files. Please fix all the reported validity errors so that only one error is left (eg. for de.xml):

xml/de.xml:3: element book: validity error : No declaration for attribute xmlns:xi of element book 
<book xmlns:xi="http://www.w3.org/2001/XInclude" id="gimp-main">

If you're looking for errors in your profiled XML file, do the following:

1. go to the reported line (it won't work for broken links, but you can lookup the ids)

2. then search backwards for 'src' and you see also the referenced file where the error occurs

3. after opening the file, you should be able to fix the problem

Create patches

If you access CVS anonymously, you will not be able to commit your changes directly. You should instead send them to the maintainer for the language you are writing in. If you are writing from scratch, or making very large changes, you probably want to create a recursive diff which keeps track of all changes including the subdirectories. Make sure you have updated your working copy with svn update:

cd trunk
svn update
svn diff ./ > gimp-help-2.patch

If you're starting with translating the manual into another language, you won't be able to create HTML out of your changes. So, we need at least one patch of you language to modify the build system and make it possible for you to convert the XML into your language HTML.

Thats it. Happy hacking ...

Compiling and Installing

To get HTML Docs from your current downloaded gimp-help-2 snapshot, you have to do the following.

./autogen.sh
make

You don't need to run ./configure, because ./autogen.sh is doing this for you. After autogen.sh processed fine, it should look like this:

configure: creating ./config.status
config.status: creating Makefile
config.status: creating stylesheets/plainhtml.xsl

 Rebuild the help files:  yes
 Install the help files:  yes
 Installation prefix:     /usr/local/share/gimp/2.0


Now type 'make' to compile gimp-help-2.

After typeing 'make' the generation of HTML docs should create the corresponding files in 'html' subdirectory of the gimp-help-2 module. Install the HTML docs with:

make install

You should now be able to use the english help pages with the GIMP Help Browser. Use the ""context help"".

PDF docs build uHowTo

After downloaded a fresh svn snapshot of the gimp manual latest version, you could be tempted to create by yourself the pdf version too. To do this you need dblatex from http://dblatex.sourceforge.net/. Just download the latest version (in the example 0.2.7), go in the dir where you put the package and do:

tar xvf dblatex-0.2.7.tar.gz
cd dblatex-0.2.7
python ./setup build
su
python ./setup.py install --prefix=/usr/local

then go into che gimp help source dir where you just build the manual and just do:

make pdf

then look into the ./pdf/ subdir.

Tips for contributing

Where should I start?

Start in the 'toolbox' directory, because most of the content won't change.

What you should know

You should know a bit about Docbook and XML, or be willing to learn the syntax yourself. You can get more information about Docbook and SGML under the Links.

Editors, Programs and Setups

Use any editor you want, but you should handle it well. Please keep in mind, that the tab width in XML Mode should be 2 spaces. If your editor is emacs you should use the nxml-mode, that is, in Debian: apt-get install nxml-mode. Under Linux, Kate and Kwrite are perfect for XML.

Under Windows, you can use Cygwin (a free Linux simulator you can get at http://cygwin.com) and TortoiseSVN to manage your local copy. NotePad++ is a good freeware to edit XML.

As said above, to send us a patch, you just have to create it in this way:

svn diff ./ > gimp-help-2.patch

Hints for making good screenshots

• please make screenshots only with the system default theme, which is of course gtk default (theme name Traditional if you use Debian)

• use default fonts like Bitstream Vera Sans with font-size of 10pt or 11pt anti-aliased

• reduce the screenshot area as much as possible cropping the windowmanager borders and disabling the help button (you can do it in the preference dialog)

• provide your source images (eg. for making new screenshots in other languages)

• do not scale the screenshot images, if they do not fit well in the pdf pages. Instead modify the "print resolution". You can do this easily with GIMP from the image menu: Image->Print size->X & Y resolution (leave chained). There is a rule of thumb, that for the html the width should not exceed 600px. Additionally set the print resolution to 144dpi and you are done. The only exception is if you have examples that are very tiny (as most of the wilber examples are) or you have some very tiny screen snippets (as some details from a dialog window for example) - for them just leave the print resolution unchanged (72dpi).

Hints for making good sources

• please always wrap around at the 75th char

• please, use alphabetic order when placing your language text. So, reviewing text will be easier, as we can find easily the wanted paragraphs. The exeption is "en", which is the reference and is always the first. In id's too.

• as said above, indent with spaces only, two for every tab space

TODO

Before you start to write, please check these items first. What do we have to do to get good Documentation done.

• add option to configure.in for creating printable output (eg. PDF) (db2latex)

• verify screenshots

• try to create an SGML and DTD docs for this wiki, to get more contributors

XML? Docbook?

So - you want to document some nifty tools, but don't know how to do that in XML? Thats not as hard as its sounds. XML is a markup language like HTML, but a bit more strict than HTML. I recommend that you be familiar with HTML because most of the concepts are similar in XML. The first step is to copy a documented file and rename it to the term which you want to document.

What we gonna do now is take a look at the header of a documented tool (clone.xml):

1 <sect1 id="gimp-tool-clone">
2  <title lang="en">Clone Tool</title>
3  <title lang="de">Klonwerkzeug</title>
4  <indexterm>
5    <primary lang="en">Toolbox</primary>
6    <primary lang="de">Werkzeugfenster</primary>
7    <secondary lang="en">Clone</secondary>
8    <secondary lang="de">Klonen</secondary>
9  </indexterm>

I numbered the lines of the code snippet for a better overview. As you can see every "open-tag" has a corresponding "close-tag", eg. <indexterm> as the open tag and </indexterm> is the corresponding close tag. Every topic you're writing about got a clear id. With those id's is GIMP able to reference the help topics and provide context sensitive help to the user. You can lookup the id by starting gimp with the verbose option, like:

  gimp-2.1 --verbose

Mostly you'll write for your own language. In order to tell Docbook which language the content is for, you add the lang attribute with your country code (eg. de for German, fr for french etc.). In the example above, the XML file provides two titles, one in german and one in english. For further writing you have to decide which tags you want to choose to get the content in shape. For that, look around into your copied file and check the structure. You'll see that every opened tag <foo> is closed by the corresponding close tag </foo>. The most needed tags are the following (I write the close-tag for completeness:

(add more ...)

After your file is done (lets call it foobar.xml), you can include it in the book. Lets assume, you wrote another section for the book. This will be referenced by gimp.xml. In order Docbook knows that your file should be parsed and converted to HTML (or whatever format will be used), you add the following line to gimp.xml:

<xi:include href="foobar.xml" />

This includes your foobar.xml in the gimp.xml file and will be parsed after you do a 'make' in the gimp-help-2 directory.