Doc: move Qt Linguist example docs from qtbase to qttools

Move qdoc files, images, and snippets.

Change-Id: I6ab84892dc56c23bfd056faa0713a572c814a1c2
Reviewed-by: Jerome Pasion <jerome.pasion@digia.com>

17 files changed, 903 insertions, 0 deletions

diff --git a/examples/linguist/doc/images/linguist-arrowpad_en.png b/examples/linguist/doc/images/linguist-arrowpad_en.png
new file mode 100644
index 000000000..9a95eb24f
--- /dev/null
+++ b/examples/linguist/doc/images/linguist-arrowpad_en.png
diff --git a/examples/linguist/doc/images/linguist-arrowpad_fr.png b/examples/linguist/doc/images/linguist-arrowpad_fr.png
new file mode 100644
index 000000000..fc33f9fd7
--- /dev/null
+++ b/examples/linguist/doc/images/linguist-arrowpad_fr.png
diff --git a/examples/linguist/doc/images/linguist-arrowpad_nl.png b/examples/linguist/doc/images/linguist-arrowpad_nl.png
new file mode 100644
index 000000000..f2645a81b
--- /dev/null
+++ b/examples/linguist/doc/images/linguist-arrowpad_nl.png
diff --git a/examples/linguist/doc/images/linguist-hellotr_en.png b/examples/linguist/doc/images/linguist-hellotr_en.png
new file mode 100644
index 000000000..6b3d8072c
--- /dev/null
+++ b/examples/linguist/doc/images/linguist-hellotr_en.png
diff --git a/examples/linguist/doc/images/linguist-hellotr_la.png b/examples/linguist/doc/images/linguist-hellotr_la.png
new file mode 100644
index 000000000..f1ecdb07a
--- /dev/null
+++ b/examples/linguist/doc/images/linguist-hellotr_la.png
diff --git a/examples/linguist/doc/images/linguist-trollprint_10_en.png b/examples/linguist/doc/images/linguist-trollprint_10_en.png
new file mode 100644
index 000000000..e460481f9
--- /dev/null
+++ b/examples/linguist/doc/images/linguist-trollprint_10_en.png
diff --git a/examples/linguist/doc/images/linguist-trollprint_10_pt_bad.png b/examples/linguist/doc/images/linguist-trollprint_10_pt_bad.png
new file mode 100644
index 000000000..b96d47724
--- /dev/null
+++ b/examples/linguist/doc/images/linguist-trollprint_10_pt_bad.png
diff --git a/examples/linguist/doc/images/linguist-trollprint_10_pt_good.png b/examples/linguist/doc/images/linguist-trollprint_10_pt_good.png
new file mode 100644
index 000000000..293c44a74
--- /dev/null
+++ b/examples/linguist/doc/images/linguist-trollprint_10_pt_good.png
diff --git a/examples/linguist/doc/images/linguist-trollprint_11_en.png b/examples/linguist/doc/images/linguist-trollprint_11_en.png
new file mode 100644
index 000000000..f718c995c
--- /dev/null
+++ b/examples/linguist/doc/images/linguist-trollprint_11_en.png
diff --git a/examples/linguist/doc/images/linguist-trollprint_11_pt.png b/examples/linguist/doc/images/linguist-trollprint_11_pt.png
new file mode 100644
index 000000000..0ff8c399b
--- /dev/null
+++ b/examples/linguist/doc/images/linguist-trollprint_11_pt.png
diff --git a/examples/linguist/doc/snippets/doc_src_examples_arrowpad.cpp b/examples/linguist/doc/snippets/doc_src_examples_arrowpad.cpp
new file mode 100644
index 000000000..58e790d3a
--- /dev/null
+++ b/examples/linguist/doc/snippets/doc_src_examples_arrowpad.cpp
@@ -0,0 +1,43 @@
+/****************************************************************************
+**
+** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies).
+** Contact: http://www.qt-project.org/legal
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:BSD$
+** You may use this file under the terms of the BSD license as follows:
+**
+** "Redistribution and use in source and binary forms, with or without
+** modification, are permitted provided that the following conditions are
+** met:
+**   * Redistributions of source code must retain the above copyright
+**     notice, this list of conditions and the following disclaimer.
+**   * Redistributions in binary form must reproduce the above copyright
+**     notice, this list of conditions and the following disclaimer in
+**     the documentation and/or other materials provided with the
+**     distribution.
+**   * Neither the name of Digia Plc and its Subsidiary(-ies) nor the names
+**     of its contributors may be used to endorse or promote products derived
+**     from this software without specific prior written permission.
+**
+**
+** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE."
+**
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+//! [0]
+qApp->translate("ArrowPad", x)
+//! [0]
diff --git a/examples/linguist/doc/snippets/doc_src_examples_arrowpad.qdoc b/examples/linguist/doc/snippets/doc_src_examples_arrowpad.qdoc
new file mode 100644
index 000000000..4b3ea343a
--- /dev/null
+++ b/examples/linguist/doc/snippets/doc_src_examples_arrowpad.qdoc
@@ -0,0 +1,54 @@
+/****************************************************************************
+**
+** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies).
+** Contact: http://www.qt-project.org/legal
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:BSD$
+** You may use this file under the terms of the BSD license as follows:
+**
+** "Redistribution and use in source and binary forms, with or without
+** modification, are permitted provided that the following conditions are
+** met:
+**   * Redistributions of source code must retain the above copyright
+**     notice, this list of conditions and the following disclaimer.
+**   * Redistributions in binary form must reproduce the above copyright
+**     notice, this list of conditions and the following disclaimer in
+**     the documentation and/or other materials provided with the
+**     distribution.
+**   * Neither the name of Digia Plc and its Subsidiary(-ies) nor the names
+**     of its contributors may be used to endorse or promote products derived
+**     from this software without specific prior written permission.
+**
+**
+** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE."
+**
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+//! [1]
+lrelease arrowpad.pro
+//! [1]
+
+
+//! [2]
+export LANG=fr
+setenv LANG fr
+//! [2]
+
+
+//! [3]
+set LANG=fr
+//! [3]
diff --git a/examples/linguist/doc/snippets/doc_src_examples_hellotr.qdoc b/examples/linguist/doc/snippets/doc_src_examples_hellotr.qdoc
new file mode 100644
index 000000000..2e57cac8a
--- /dev/null
+++ b/examples/linguist/doc/snippets/doc_src_examples_hellotr.qdoc
@@ -0,0 +1,71 @@
+/****************************************************************************
+**
+** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies).
+** Contact: http://www.qt-project.org/legal
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:BSD$
+** You may use this file under the terms of the BSD license as follows:
+**
+** "Redistribution and use in source and binary forms, with or without
+** modification, are permitted provided that the following conditions are
+** met:
+**   * Redistributions of source code must retain the above copyright
+**     notice, this list of conditions and the following disclaimer.
+**   * Redistributions in binary form must reproduce the above copyright
+**     notice, this list of conditions and the following disclaimer in
+**     the documentation and/or other materials provided with the
+**     distribution.
+**   * Neither the name of Digia Plc and its Subsidiary(-ies) nor the names
+**     of its contributors may be used to endorse or promote products derived
+**     from this software without specific prior written permission.
+**
+**
+** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE."
+**
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+//! [0]
+lupdate -verbose hellotr.pro
+//! [0]
+
+
+//! [1]
+<!DOCTYPE TS><TS>
+<context>
+    <name>QPushButton</name>
+    <message>
+        <source>Hello world!</source>
+        <translation type="unfinished"></translation>
+    </message>
+</context>
+</TS>
+//! [1]
+
+
+//! [2]
+linguist hellotr_la.ts
+//! [2]
+
+
+//! [3]
+<translation type='unfinished'></translation>
+//! [3]
+
+
+//! [4]
+<translation>Orbis, te saluto!</translation>
+//! [4]
diff --git a/examples/linguist/doc/snippets/doc_src_examples_trollprint.cpp b/examples/linguist/doc/snippets/doc_src_examples_trollprint.cpp
new file mode 100644
index 000000000..493e245e8
--- /dev/null
+++ b/examples/linguist/doc/snippets/doc_src_examples_trollprint.cpp
@@ -0,0 +1,77 @@
+/****************************************************************************
+**
+** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies).
+** Contact: http://www.qt-project.org/legal
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:BSD$
+** You may use this file under the terms of the BSD license as follows:
+**
+** "Redistribution and use in source and binary forms, with or without
+** modification, are permitted provided that the following conditions are
+** met:
+**   * Redistributions of source code must retain the above copyright
+**     notice, this list of conditions and the following disclaimer.
+**   * Redistributions in binary form must reproduce the above copyright
+**     notice, this list of conditions and the following disclaimer in
+**     the documentation and/or other materials provided with the
+**     distribution.
+**   * Neither the name of Digia Plc and its Subsidiary(-ies) nor the names
+**     of its contributors may be used to endorse or promote products derived
+**     from this software without specific prior written permission.
+**
+**
+** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE."
+**
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+//! [0]
+twoSidedEnabledRadio = new QRadioButton(tr("Enabled", "two-sided"));
+twoSidedDisabledRadio = new QRadioButton(tr("Disabled", "two-sided"));
+//! [0]
+
+
+//! [1]
+colorsEnabledRadio = new QRadioButton(tr("Enabled", "colors"), colors);
+colorsDisabledRadio = new QRadioButton(tr("Disabled", "colors"), colors);
+//! [1]
+
+
+//! [2]
+/*
+   TRANSLATOR MainWindow
+
+   In this application the whole application is a MainWindow.
+   Choose Help|About from the menu bar to see some text
+   belonging to MainWindow.
+
+   ...
+*/
+//! [2]
+
+
+//! [3]
+/*
+   TRANSLATOR ZClientErrorDialog
+
+   Choose Client|Edit to reach the Client Edit dialog, then choose
+   Client Specification from the drop down list at the top and pick
+   client Bartel Leendert van der Waerden. Now check the Profile
+   checkbox and then click the Start Processing button. You should
+   now see a pop up window with the text "Error: Name too long!".
+   This window is a ZClientErrorDialog.
+*/
+//! [3]
diff --git a/examples/linguist/doc/src/arrowpad.qdoc b/examples/linguist/doc/src/arrowpad.qdoc
new file mode 100644
index 000000000..4ba2e7d68
--- /dev/null
+++ b/examples/linguist/doc/src/arrowpad.qdoc
@@ -0,0 +1,223 @@
+/****************************************************************************
+**
+** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies).
+** Contact: http://www.qt-project.org/legal
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:FDL$
+** Commercial License Usage
+** Licensees holding valid commercial Qt licenses may use this file in
+** accordance with the commercial license agreement provided with the
+** Software or, alternatively, in accordance with the terms contained in
+** a written agreement between you and Digia.  For licensing terms and
+** conditions see http://qt.digia.com/licensing.  For further information
+** use the contact form at http://qt.digia.com/contact-us.
+**
+** GNU Free Documentation License Usage
+** Alternatively, this file may be used under the terms of the GNU Free
+** Documentation License version 1.3 as published by the Free Software
+** Foundation and appearing in the file included in the packaging of
+** this file.  Please review the following information to ensure
+** the GNU Free Documentation License version 1.3 requirements
+** will be met: http://www.gnu.org/copyleft/fdl.html.
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+    \example arrowpad
+    \title Arrow Pad Example
+
+    This example is a slightly more involved and introduces a key \e
+    {Qt Linguist} concept: "contexts". It also shows how to use two
+    or more languages.
+
+    \image linguist-arrowpad_en.png
+
+    We will use two translations, French and Dutch, although there is no
+    effective limit on the number of possible translations that can be used
+    with an application. The relevant lines of \c arrowpad.pro are
+
+    \snippet arrowpad/arrowpad.pro 0
+    \codeline
+    \snippet arrowpad/arrowpad.pro 1
+
+    Run \c lupdate; it should produce two identical message files
+    \c arrowpad_fr.ts and \c arrowpad_nl.ts. These files will contain all the source
+    texts marked for translation with \c tr() calls and their contexts.
+
+    See the \l{Qt Linguist manual} for more information about
+    translating Qt application.
+
+    \section1 Line by Line Walkthrough
+
+    In \c arrowpad.h we define the \c ArrowPad subclass which is a
+    subclass of QWidget. In the screenshot above, the central
+    widget with the four buttons is an \c ArrowPad.
+
+    \snippet arrowpad/arrowpad.h 0
+    \snippet arrowpad/arrowpad.h 1
+    \snippet arrowpad/arrowpad.h 2
+
+    When \c lupdate is run it not only extracts the source texts but it
+    also groups them into contexts. A context is the name of the class in
+    which the source text appears. Thus, in this example, "ArrowPad" is a
+    context: it is the context of the texts in the \c ArrowPad class.
+    The \c Q_OBJECT macro defines \c tr(x) in \c ArrowPad like this:
+
+    \snippet doc/snippets/doc_src_examples_arrowpad.cpp 0
+
+    Knowing which class each source text appears in enables \e {Qt
+    Linguist} to group texts that are logically related together, e.g.
+    all the text in a dialog will have the context of the dialog's class
+    name and will be shown together. This provides useful information for
+    the translator since the context in which text appears may influence how
+    it should be translated. For some translations keyboard
+    accelerators may need to be changed and having all the source texts in a
+    particular context (class) grouped together makes it easier for the
+    translator to perform any accelerator changes without introducing
+    conflicts.
+
+    In \c arrowpad.cpp we implement the \c ArrowPad class.
+
+    \snippet arrowpad/arrowpad.cpp 0
+    \snippet arrowpad/arrowpad.cpp 1
+    \snippet arrowpad/arrowpad.cpp 2
+    \snippet arrowpad/arrowpad.cpp 3
+
+    We call \c ArrowPad::tr() for each button's label since the labels are
+    user-visible text.
+
+    \image linguist-arrowpad_en.png
+
+    \snippet arrowpad/mainwindow.h 0
+    \snippet arrowpad/mainwindow.h 1
+
+    In the screenshot above, the whole window is a \c MainWindow.
+    This is defined in the \c mainwindow.h header file. Here too, we
+    use \c Q_OBJECT, so that \c MainWindow will become a context in
+    \e {Qt Linguist}.
+
+    \snippet arrowpad/mainwindow.cpp 0
+
+    In the implementation of \c MainWindow, \c mainwindow.cpp, we create
+    an instance of our \c ArrowPad class.
+
+    \snippet arrowpad/mainwindow.cpp 1
+
+    We also call \c MainWindow::tr() twice, once for the action and
+    once for the shortcut.
+
+    Note the use of \c tr() to support different keys in other
+    languages. "Ctrl+Q" is a good choice for Quit in English, but a
+    Dutch translator might want to use "Ctrl+A" (for Afsluiten) and a
+    German translator "Strg+E" (for Beenden). When using \c tr() for
+    \uicontrol Ctrl key accelerators, the two argument form should be used
+    with the second argument describing the function that the
+    accelerator performs.
+
+    Our \c main() function is defined in \c main.cpp as usual.
+
+    \snippet arrowpad/main.cpp 2
+    \snippet arrowpad/main.cpp 3
+
+    We choose which translation to use according to the current locale.
+    QLocale::system() can be influenced by setting the \c LANG
+    environment variable, for example. Notice that the use of a naming
+    convention that incorporates the locale for \c .qm message files,
+    (and TS files), makes it easy to implement choosing the
+    translation file according to locale.
+
+    If there is no QM message file for the locale chosen the original
+    source text will be used and no error raised.
+
+    \section1 Translating to French and Dutch
+
+    We'll begin by translating the example application into French. Start
+    \e {Qt Linguist} with \c arrowpad_fr.ts. You should get the seven source
+    texts ("\&Up", "\&Left", etc.) grouped in two contexts ("ArrowPad"
+    and "MainWindow").
+
+    Now, enter the following translations:
+
+    \list
+    \li \c ArrowPad
+         \list
+         \li \&Up - \&Haut
+         \li \&Left - \&Gauche
+         \li \&Right - \&Droite
+         \li \&Down - \&Bas
+         \endlist
+    \li \c MainWindow
+         \list
+         \li E\&xit - \&Quitter
+         \li Ctrl+Q - Ctrl+Q
+         \li \&File - \&Fichier
+         \endlist
+    \endlist
+
+    It's quickest to press \uicontrol{Alt+D} (which clicks the \uicontrol {Done \& Next}
+    button) after typing each translation, since this marks the
+    translation as done and moves on to the next source text.
+
+    Save the file and do the same for Dutch working with \c arrowpad_nl.ts:
+
+    \list
+    \li \c ArrowPad
+         \list
+         \li \&Up - \&Omhoog
+         \li \&Left - \&Links
+         \li \&Right - \&Rechts
+         \li \&Down - Omlaa\&g
+         \endlist
+    \li \c MainWindow
+         \list
+         \li E\&xit - \&Afsluiten
+         \li Ctrl+Q - Ctrl+A
+         \li File - \&Bestand
+         \endlist
+    \endlist
+
+    We have to convert the \c tt1_fr.ts and \c tt1_nl.ts translation source
+    files into QM files. We could use \e {Qt Linguist} as we've done
+    before; however using the command line tool \c lrelease ensures that
+    \e all the QM files for the application are created without us
+    having to remember to load and \uicontrol File|Release each one
+    individually from \e {Qt Linguist}.
+
+    Type
+
+    \snippet doc/snippets/doc_src_examples_arrowpad.qdoc 1
+
+    This should create both \c arrowpad_fr.qm and \c arrowpad_nl.qm. Set the \c
+    LANG environment variable to \c fr. In Unix, one of the two following
+    commands should work
+
+    \snippet doc/snippets/doc_src_examples_arrowpad.qdoc 2
+
+    In Windows, either modify \c autoexec.bat or run
+
+    \snippet doc/snippets/doc_src_examples_arrowpad.qdoc 3
+
+    When you run the program, you should now see the French version:
+
+    \image linguist-arrowpad_fr.png
+
+    Try the same with Dutch, by setting \c LANG=nl. Now the Dutch
+    version should appear:
+
+    \image linguist-arrowpad_nl.png
+
+    \section1 Exercises
+
+    Mark one of the translations in \e {Qt Linguist} as not done, i.e.
+    by unchecking the "done" checkbox; run \c lupdate, then \c lrelease,
+    then the example. What effect did this change have?
+
+    Set \c LANG=fr_CA (French Canada) and run the example program again.
+    Explain why the result is the same as with \c LANG=fr.
+
+    Change one of the accelerators in the Dutch translation to eliminate the
+    conflict between \e \&Bestand and \e \&Boven.
+*/
diff --git a/examples/linguist/doc/src/hellotr.qdoc b/examples/linguist/doc/src/hellotr.qdoc
new file mode 100644
index 000000000..9c459d979
--- /dev/null
+++ b/examples/linguist/doc/src/hellotr.qdoc
@@ -0,0 +1,174 @@
+/****************************************************************************
+**
+** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies).
+** Contact: http://www.qt-project.org/legal
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:FDL$
+** Commercial License Usage
+** Licensees holding valid commercial Qt licenses may use this file in
+** accordance with the commercial license agreement provided with the
+** Software or, alternatively, in accordance with the terms contained in
+** a written agreement between you and Digia.  For licensing terms and
+** conditions see http://qt.digia.com/licensing.  For further information
+** use the contact form at http://qt.digia.com/contact-us.
+**
+** GNU Free Documentation License Usage
+** Alternatively, this file may be used under the terms of the GNU Free
+** Documentation License version 1.3 as published by the Free Software
+** Foundation and appearing in the file included in the packaging of
+** this file.  Please review the following information to ensure
+** the GNU Free Documentation License version 1.3 requirements
+** will be met: http://www.gnu.org/copyleft/fdl.html.
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+    \example hellotr
+    \title Hello tr() Example
+
+    This example is a small Hello World program with a Latin translation. The
+    screenshot below shows the English version.
+
+    \image linguist-hellotr_en.png
+
+    See the \l{Qt Linguist manual} for more information about
+    translating Qt application.
+
+    \section1 Line by Line Walkthrough
+
+
+    \snippet hellotr/main.cpp 0
+
+    This line includes the definition of the QTranslator class.
+    Objects of this class provide translations for user-visible text.
+
+    \snippet hellotr/main.cpp 5
+
+    Creates a QTranslator object without a parent.
+
+    \snippet hellotr/main.cpp 6
+
+    Tries to load a file called \c hellotr_la.qm (the \c .qm file extension is
+    implicit) that contains Latin translations for the source texts used in
+    the program. No error will occur if the file is not found.
+
+    \snippet hellotr/main.cpp 7
+
+    Adds the translations from \c hellotr_la.qm to the pool of translations used
+    by the program.
+
+    \snippet hellotr/main.cpp 8
+
+    Creates a push button that displays "Hello world!". If \c hellotr_la.qm
+    was found and contains a translation for "Hello world!", the
+    translation appears; if not, the source text appears.
+
+    All classes that inherit QObject have a \c tr() function. Inside
+    a member function of a QObject class, we simply write \c tr("Hello
+    world!") instead of \c QPushButton::tr("Hello world!") or \c
+    QObject::tr("Hello world!").
+
+    \section1 Running the Application in English
+
+    Since we haven't made the translation file \c hellotr_la.qm, the source text
+    is shown when we run the application:
+
+    \image linguist-hellotr_en.png
+
+    \section1 Creating a Latin Message File
+
+    The first step is to create a project file, \c hellotr.pro, that lists
+    all the source files for the project. The project file can be a qmake
+    project file, or even an ordinary makefile. Any file that contains
+
+    \snippet hellotr/hellotr.pro 0
+    \snippet hellotr/hellotr.pro 1
+
+    will work. \c TRANSLATIONS specifies the message files we want to
+    maintain. In this example, we just maintain one set of translations,
+    namely Latin.
+
+    Note that the file extension is \c .ts, not \c .qm. The \c .ts
+    translation source format is designed for use during the
+    application's development. Programmers or release managers run
+    the \c lupdate program to generate and update TS files with
+    the source text that is extracted from the source code.
+    Translators read and update the TS files using \e {Qt
+    Linguist} adding and editing their translations.
+
+    The TS format is human-readable XML that can be emailed directly
+    and is easy to put under version control. If you edit this file
+    manually, be aware that the default encoding for XML is UTF-8, not
+    Latin1 (ISO 8859-1). One way to type in a Latin1 character such as
+    '\oslash' (Norwegian o with slash) is to use an XML entity:
+    "\&#xf8;". This will work for any Unicode 4.0 character.
+
+    Once the translations are complete the \c lrelease program is used to
+    convert the TS files into the QM Qt message file format. The
+    QM format is a compact binary format designed to deliver very
+    fast lookup performance. Both \c lupdate and \c lrelease read all the
+    project's source and header files (as specified in the HEADERS and
+    SOURCES lines of the project file) and extract the strings that
+    appear in \c tr() function calls.
+
+    \c lupdate is used to create and update the message files (\c hellotr_la.ts
+    in this case) to keep them in sync with the source code. It is safe to
+    run \c lupdate at any time, as \c lupdate does not remove any
+    information. For example, you can put it in the makefile, so the TS
+    files are updated whenever the source changes.
+
+    Try running \c lupdate right now, like this:
+
+    \snippet doc/snippets/doc_src_examples_hellotr.qdoc 0
+
+    (The \c -verbose option instructs \c lupdate to display messages that
+    explain what it is doing.) You should now have a file \c hellotr_la.ts in
+    the current directory, containing this:
+
+    \snippet doc/snippets/doc_src_examples_hellotr.qdoc 1
+
+    You don't need to understand the file format since it is read and
+    updated using tools (\c lupdate, \e {Qt Linguist}, \c lrelease).
+
+    \section1 Translating to Latin with Qt Linguist
+
+    We will use \e {Qt Linguist} to provide the translation, although
+    you can use any XML or plain text editor to enter a translation into a
+    TS file.
+
+    To start \e {Qt Linguist}, type
+
+    \snippet doc/snippets/doc_src_examples_hellotr.qdoc 2
+
+    You should now see the text "QPushButton" in the top left pane.
+    Double-click it, then click on "Hello world!" and enter "Orbis, te
+    saluto!" in the \uicontrol Translation pane (the middle right of the
+    window). Don't forget the exclamation mark!
+
+    Click the \uicontrol Done checkbox and choose \uicontrol File|Save from the
+    menu bar. The TS file will no longer contain
+
+    \snippet doc/snippets/doc_src_examples_hellotr.qdoc 3
+
+    but instead will have
+
+    \snippet doc/snippets/doc_src_examples_hellotr.qdoc 4
+
+    \section1 Running the Application in Latin
+
+    To see the application running in Latin, we have to generate a QM
+    file from the TS file. Generating a QM file can be achieved
+    either from within \e {Qt Linguist} (for a single TS file), or
+    by using the command line program \c lrelease which will produce one
+    QM file for each of the TS files listed in the project file.
+    Generate \c hellotr_la.qm from \c hellotr_la.ts by choosing
+    \uicontrol File|Release from \e {Qt Linguist}'s menu bar and pressing
+    \uicontrol Save in the file save dialog that pops up. Now run the \c hellotr
+    program again. This time the button will be labelled "Orbis, te
+    saluto!".
+
+    \image linguist-hellotr_la.png
+*/
diff --git a/examples/linguist/doc/src/trollprint.qdoc b/examples/linguist/doc/src/trollprint.qdoc
new file mode 100644
index 000000000..92c2b3c70
--- /dev/null
+++ b/examples/linguist/doc/src/trollprint.qdoc
@@ -0,0 +1,261 @@
+/****************************************************************************
+**
+** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies).
+** Contact: http://www.qt-project.org/legal
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:FDL$
+** Commercial License Usage
+** Licensees holding valid commercial Qt licenses may use this file in
+** accordance with the commercial license agreement provided with the
+** Software or, alternatively, in accordance with the terms contained in
+** a written agreement between you and Digia.  For licensing terms and
+** conditions see http://qt.digia.com/licensing.  For further information
+** use the contact form at http://qt.digia.com/contact-us.
+**
+** GNU Free Documentation License Usage
+** Alternatively, this file may be used under the terms of the GNU Free
+** Documentation License version 1.3 as published by the Free Software
+** Foundation and appearing in the file included in the packaging of
+** this file.  Please review the following information to ensure
+** the GNU Free Documentation License version 1.3 requirements
+** will be met: http://www.gnu.org/copyleft/fdl.html.
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+    \example trollprint
+    \title Troll Print Example
+
+    Troll Print is an example application that lets the user choose
+    printer settings. It comes in two versions: English and
+    Portuguese.
+
+    \image linguist-trollprint_10_en.png
+
+    We've included a translation file, \c trollprint_pt.ts, which contains some
+    Portuguese translations for this example.
+
+    We will consider two releases of the same application: Troll Print
+    1.0 and 1.1. We will learn to reuse the translations created for one
+    release in a subsequent release. (In this tutorial, you need to edit
+    some source files. It's probably best to copy all the files to a new
+    temporary directory and work from there.)
+
+    See the \l{Qt Linguist manual} for more information about
+    translating Qt application.
+
+    \section1 Line by Line Walkthrough
+
+    The \c PrintPanel class is defined in \c printpanel.h.
+
+    \snippet trollprint/printpanel.h 0
+
+    \c PrintPanel is a QWidget. It needs the \c Q_OBJECT macro for \c
+    tr() to work properly.
+
+    The implementation file is \c printpanel.cpp.
+
+    \snippet trollprint/printpanel.cpp 0
+
+    Some of the code is commented out in Troll Print 1.0; you will
+    uncomment it later, for Troll Print 1.1.
+
+    \snippet trollprint/printpanel.cpp 1
+    \snippet trollprint/printpanel.cpp 2
+
+    Notice the two occurrences of \c tr("Enabled") and of \c
+    tr("Disabled") in PrintPanel. Since both "Enabled"s and "Disabled"s
+    appear in the same context \e {Qt Linguist} will only display one
+    occurrence of each and will use the same translations for the
+    duplicates that it doesn't display. Whilst this is a useful
+    timesaver, in some languages, such as Portuguese, the second
+    occurrence requires a separate translation. We will see how \e {Qt
+    Linguist} can be made to display all the occurrences for separate
+    translation shortly.
+
+    The header file for \c MainWindow, \c mainwindow.h, contains no
+    surprises. In the implementation, \c mainwindow.cpp, we have some
+    user-visible source texts that must be marked for translation.
+
+    \snippet trollprint/mainwindow.cpp 0
+
+    We must translate the window title.
+
+    \snippet trollprint/mainwindow.cpp 1
+    \snippet trollprint/mainwindow.cpp 3
+
+    We also need to translate the actions and menus. Note that the
+    two argument form of \c tr() is used for the keyboard
+    accelerator, "Ctrl+Q", since the second argument is the only clue
+    the translator has to indicate what function that accelerator
+    will perform.
+
+    \snippet trollprint/main.cpp 0
+
+    The \c main() function in \c main.cpp is the same as the one in
+    the \l{arrowpad}{Arrow Pad} example. In particular, it
+    chooses a translation file based on the current locale.
+
+    \section1 Running Troll Print 1.0 in English and in Portuguese
+
+    We will use the translations in the \c trollprint_pt.ts file that is provided.
+
+    Set the \c LANG environment variable to \c pt, and then run \c
+    trollprint. You should still see the English version. Now run \c
+    lrelease, e.g. \c {lrelease trollprint.pro}, and then run the
+    example again. Now you should see the Portuguese edition (Troll
+    Imprimir 1.0):
+
+    \image linguist-trollprint_10_pt_bad.png
+
+    Whilst the translation has appeared correctly, it is in fact wrong. In
+    good Portuguese, the second occurrence of "Enabled" should be
+    "Ativadas", not "Ativado" and the ending for the second translation of
+    "Disabled" must change similarly too.
+
+    If you open \c trollprint_pt.ts using \e {Qt Linguist}, you will see that
+    there is just one occurrence of "Enabled" and of "Disabled" in the
+    translation source file, even though there are two of each in the
+    source code. This is because \e {Qt Linguist} tries to minimize the
+    translator's work by using the same translation for duplicate source
+    texts. In cases such as this where an identical translation is wrong,
+    the programmer must disambiguate the duplicate occurrences. This is
+    easily achieved by using the two argument form of \c tr().
+
+    We can easily determine which file must be changed because the
+    translator's "context" is in fact the class name for the class where
+    the texts that must be changed appears. In this case the file is \c
+    printpanel.cpp, where there are four lines to change. Add the
+    second argument "two-sided" in the appropriate \c tr() calls to the
+    first pair of radio buttons:
+
+    \snippet doc/snippets/doc_src_examples_trollprint.cpp 0
+
+    and add the second argument "colors" in the appropriate \c tr() calls
+    for the second pair of radio buttons:
+
+    \snippet doc/snippets/doc_src_examples_trollprint.cpp 1
+
+    Now run \c lupdate and open \c trollprint_pt.ts with \e {Qt Linguist}. You
+    should now see two changes.
+
+    First, the translation source file now contains \e three "Enabled",
+    "Disabled" pairs. The first pair is marked "(obs.)" signifying that they
+    are obsolete. This is because these texts appeared in \c tr() calls that
+    have been replaced by new calls with two arguments. The second pair has
+    "two-sided" as their comment, and the third pair has "colors" as their
+    comment. The comments are shown in the \uicontrol {Source text and comments}
+    area in \e {Qt Linguist}.
+
+    Second, the translation text "Ativado" and "Desativado" have been
+    automatically used as translations for the new "Enabled" and "Disabled"
+    texts, again to minimize the translator's work. Of course in this case
+    these are not correct for the second occurrence of each word, but they
+    provide a good starting point.
+
+    Change the second "Ativado" into "Ativadas" and the second
+    "Desativado" into "Desativadas", then save and quit. Run \c lrelease
+    to obtain an up-to-date binary \c trollprint_pt.qm file, and run Troll Print
+    (or rather Troll Imprimir).
+
+    \image linguist-trollprint_10_pt_good.png
+
+    The second argument to \c tr() calls, called "comments" in \e {Qt
+    Linguist}, distinguish between identical source texts that occur in
+    the same context (class). They are also useful in other cases to give
+    clues to the translator, and in the case of Ctrl key accelerators are
+    the only means of conveying the function performed by the accelerator to
+    the translator.
+
+    An additional way of helping the translator is to provide information on
+    how to navigate to the particular part of the application that contains
+    the source texts they must translate. This helps them see the context
+    in which the translation appears and also helps them to find and test
+    the translations. This can be achieved by using a \c TRANSLATOR comment
+    in the source code:
+
+    \snippet doc/snippets/doc_src_examples_trollprint.cpp 2
+
+    Try adding these comments to some source files, particularly to
+    dialog classes, describing the navigation necessary to reach the
+    dialogs. You could also add them to the example files, e.g. \c
+    mainwindow.cpp and \c printpanel.cpp are appropriate files. Run \c
+    lupdate and then start \e {Qt Linguist} and load in \c trollprint_pt.ts.
+    You should see the comments in the \uicontrol {Source text and comments} area
+    as you browse through the list of source texts.
+
+    Sometimes, particularly with large programs, it can be difficult for
+    the translator to find their translations and check that they're
+    correct. Comments that provide good navigation information can save
+    them time:
+
+    \snippet doc/snippets/doc_src_examples_trollprint.cpp 3
+
+    \section1 Troll Print 1.1
+
+    We'll now prepare release 1.1 of Troll Print. Start your favorite text
+    editor and follow these steps:
+
+    \list
+    \li Uncomment the two lines that create a QLabel with the text
+         "\<b\>TROLL PRINT\</b\>" in \c printpanel.cpp.
+    \li Word-tidying: Replace "2-sided" by "Two-sided" in \c printpanel.cpp.
+    \li Replace "1.0" with "1.1" everywhere it occurs in \c mainwindow.cpp.
+    \li Update the copyright year to 1999-2000 in \c mainwindow.cpp.
+    \endlist
+
+    (Of course the version number and copyright year would be consts or
+    #defines in a real application.)
+
+    Once finished, run \c lupdate, then open \c trollprint_pt.ts in \e {Qt
+    Linguist}. The following items are of special interest:
+
+    \list
+    \li \c MainWindow
+         \list
+         \li Troll Print 1.0 - marked "(obs.)", obsolete
+         \li About Troll Print 1.0 - marked "(obs.)", obsolete
+         \li Troll Print 1.0. Copyright 1999 Software, Inc. -
+       marked obsolete
+         \li Troll Print 1.1 - automatically translated as
+       "Troll Imprimir 1.1"
+         \li About Troll Print 1.1 - automatically translated as
+       "Troll Imprimir 1.1"
+         \li Troll Print 1.1. Copyright 1999-2000 Software,
+       Inc. - automatically translated as "Troll Imprimir 1.1.
+       Copyright 1999-2000 Software, Inc."
+         \endlist
+    \li \c PrintPanel
+         \list
+         \li 2-sided - marked "(obs.)", obsolete
+         \li \<b\>TROLL PRINT\</b\> - unmarked, i.e. untranslated
+         \li Two-sided - unmarked, i.e. untranslated.
+         \endlist
+    \endlist
+
+    Notice that \c lupdate works hard behind the scenes to make revisions
+    easier, and it's pretty smart with numbers.
+
+    Go over the translations in \c MainWindow and mark these as "done".
+    Translate "\<b\>TROLL PRINT\</b\>" as "\<b\>TROLL IMPRIMIR\</b\>".
+    When you're translating "Two-sided", press the \uicontrol {Guess Again}
+    button to translate "Two-sided", but change the "2" into "Dois".
+
+    Save and quit, then run \c lrelease. The Portuguese version
+    should look like this:
+
+    \image linguist-trollprint_11_pt.png
+
+    Choose \uicontrol{Ajuda|Sobre} (\uicontrol{Help|About}) to see the about box.
+
+    If you choose \uicontrol {Ajuda|Sobre Qt} (\uicontrol {Help|About Qt}), you'll get
+    an English dialog. Oops! Qt itself needs to be translated. See
+    \l{Internationalization with Qt} for details.
+
+    Now set \c LANG=en to get the original English version:
+
+    \image linguist-trollprint_11_en.png
+*/