Mercurial Kick Start by aragost Trifork

This is a tutorial for Mercurial based on the principle of
learning-by-doing. The commands and the output you see are "real" in
the sense that the commands are executed when the HTML files are
built. This ensures that the output doesn't go stale when new versions
of Mercurial are released and also that it doesn't go out of sync when
one part of the tutorial is edited without updating another.


You need `Scons`_ to build the tutorial. Run::

  scons en

to build the English version of the tutorial. Run::


to build all available languages. A cache with the results of the
shell tests will be built in the ``~/.shelltest`` directory. This can
be cleared as needed.


You will need these tools, Debian package names are listed in

* Python Subversion bindings (python-subversion)
* Docutils (python-docutils)
* Graphviz (graphviz)
* Xvfb (xvfb)
* ImageMagick (imagemagick)
* Python header files (python-dev)
* iniparse (python-iniparse)
* Gettext (gettext)
* PyQt4 (pyqt4-dev-tools)
* Python QScintilla bindings (python-qscintilla2)

The correct versions of Mercurial, TortoiseHg, and hgsubversion is
distributed with the tutorial as subrepos in the ``deps/`` folder.


*Translations are very welcome!* The Kick Start is prepared for
translation using standard Gettext ``.po`` files. Start by generating
a ``.pot`` file that you can use as a basis::

  scons pot

This will generate ``po/kick-start.pot`` with all the English source
strings. Now run::

  cd po
  msginit -l xx

to create a ``xx.po`` file for your language. If you don't have
``msginit``, then just copy ``kick-start.pot`` to ``xx.po``. You now
edit ``xx.po`` with a PO editor of your choice.

To back to the top-level and run::

  scons xx

to generate the translation for the ``xx`` language. Please commit
your changes with a ``po-xx:`` prefix in the commit message and submit
a pull request.

Updating a Translation

When the English strings change in the source files, you need to
update your translation. This is a two-step process: first you extract
the source strings into ``po/kick-start.pot``, and then you merge the
new strings into your existing translation.

Extracting the source strings is done with::

  scons pot

To merge them into your ``xx.po`` file, run::

  msgmerge --sort-by-file --update po/cs.po po/kick-start.pot

Unchanged paragraphs will remain translated and new paragraphs are
added to ``xx.po`` without a translation. If a translated paragraph
has changed, then the new paragraph is added as the ``msgid`` and your
old translation is added as ``msgstr``, but marked *fuzzy*. A fuzzy
translation is not used in the final version, but it's there in the
``xx.po`` file so that you can adjust it to fix the new source
paragraph. When the translation is updated, you must remove the fuzzy
mark so that the translation will become active. See the `Gettext
manual`_ for more information or consult your favorite PO editor.

.. _Gettext manual:


The Mercurial Kick Start can be distributed according to the terms of
the GNU General Public License version 2 or any later version.

.. _scons: