Warning, /sdk/pology/doc/user/about.docbook is written in an unsupported language. File is not indexed.

 <?xml version="1.0" encoding="UTF-8"?>
 <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
  "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
 
 <chapter id="ch-about">
 
 <title>A Study of PO</title>
 
 <para>Many people like to use computer programs in their native language. On the average, the working language of developers of a computer program, and the native language of its users, are different. This means that programs need to be <emphasis>translated</emphasis>. For this to be possible, first the program has to be written in such a way that it can fetch and display translations in the language set by the user. Then, there has to exist a method to collect discrete pieces of text (such as button labels, menu items, messages in dialogs...) from the program. Collected pieces of text are written into one or more files of a certain format, which the translators can work on. Finally, translated files may need to be converted into a form that the program can interpret and show translation to the user. There are many different translation systems, which support one or more of these elements of translation process.</para>
 
 <para>In the realm of free software, one particular translation system has become ubiquitous: the <ulink url="http://www.gnu.org/software/gettext/">GNU Gettext</ulink>. It covers all the elements of the translation process. It provides a way for programmers to write translatable programs, a way for text to be extracted and collected for translation, a file format on which the translators work, and a set of tools for processing translation files. Beyond the technical aspects, Gettext has evolved a set of conventions, workflows and communication patterns -- a translation <emphasis>culture</emphasis> of sorts.</para>
 
 <para>The most salient element of Gettext from translators' perspective is the translation file format it defines, the PO<footnote>
 <para>"PO" is an acronym for "portable object". This phrase is a quite generic term from the depths of computer science, opaque for practicing translators. Texts on software translation therefore always write simply "PO format", "PO files", etc.</para>
 </footnote> format. Along with other parts of Gettext, the PO format has developed over the years into the technically most capable translation file format today. Its features both enable high quality and efficiency of translation, and yet can all "fit into one person's head". <link linkend="ch-poformat">A chapter of this manual</link> provides a tour of the PO format from translator's perspective.</para>
 
 <para>Aside from the tools provided by GNU Gettext itself, many other tools for processing PO files have been written. These consist of translation editors (or "PO editors"), which provide translators with more power in editing PO files, and batch-processing tools, for purposes more specific than those covered by Gettext (e.g. conversion from and to other file formats). <emphasis>Pology</emphasis> is one of these specific batch-processing tools.</para>
 
 <para>Pology consists of a <ulink url="http://www.python.org/">Python</ulink> library, with much translation-related functionality beyond basic manipulation of PO file objects, and a collection of scripts based on this library. Both the library and the scripts have this basic trait: they tend to go in depth. Pology is designed to apply precision tasks to standalone PO files, to process collections of PO files in sophisticated ways, and while doing this to cooperate well with other tools commonly used to handle PO files (such as PO editors and version control systems). On the programming side Pology strives for simplicity and robustness, so that users who know (some) Python can easily add functionality for their custom needs. To achieve this, Pology fully relies on the conventions of the PO format, without trying to abstract the translation file format.</para>
 
 <para>As one measure of attention to detail, Pology has sections of language-specific and project-specific functionality, and even combinations of those. Users are encouraged to contribute their custom solutions into the main distribution, if these solutions can possibly serve needs of others.</para>
 
 <para>In short, Pology is <emphasis>a study of PO</emphasis>.</para>
 
 <sect1 id="sec-install">
 <title>Obtaining and Installing</title>
 
 <para>Naturally, the easiest way is to install Pology packages for your operating system distribution, if they exist. Otherwise you must obtain Pology as source code, but you will still be able to prepare it for use quite simply.</para>
 
 <para>You can either download a release tarball from <emphasis>[[insert link here]]</emphasis>, or fetch the latest development version from the version control repository. To do the latter, execute<footnote>
     <para><command>git</command> is the primary command of the <ulink url="https://git-scm.com/">Git</ulink> version control system. Git is almost certainly ready for installation from your operating system's package repositories.</para>
 </footnote>:
 <programlisting language="bash">
 $ cd <replaceable>PARENTDIR</replaceable>
 $ git clone https://invent.kde.org/sdk/pology.git
 </programlisting>
 This will create the <filename>pology</filename> subdirectory inside the <replaceable>PARENTDIR</replaceable>, and download full Pology source into it. When you want to update to the latest version later on, you do not have to download everything again; instead you can execute <userinput>git pull</userinput> in the directory Pology's root directory:
 <programlisting language="bash">
 $ cd <replaceable>POLOGYDIR</replaceable>
 $ git pull
 </programlisting>
 This will fetch only the modifications since the checkout (or the previous update) and apply them to the existing source tree.</para>
 
 <para>To prepare Pology for use, you can either properly install it or use it directly from the source directory. To install it, you first run CMake in a separate build directory to configure the build, and then <command>make</command> and <command>make install</command> to build and install:
 <programlisting language="bash">
 $ cd <replaceable>POLOGYDIR</replaceable>
 $ mkdir build &amp;&amp; cd build
 $ cmake ..
 $ make &amp;&amp; make install
 </programlisting>
 CMake will warn you of missing requirements, and give some hints on how to customize the build (e.g. installation prefix, etc). If <command>cmake</command> is run like this without any arguments, Pology will be installed into a standard system location, and should be ready to use. If you install it into a custom location (e.g. inside your home directory), then you may need to set some environment variables (see below).</para>
 
 <para>If you want to run Pology from its source directory, it is sufficient to set two environment variables:
 <programlisting language="bash">
 $ export PATH=<replaceable>POLOGYDIR</replaceable>/bin:$PATH
 $ export PYTHONPATH=<replaceable>POLOGYDIR</replaceable>:$PYTHONPATH
 </programlisting>
 You can put these commands in the shell startup script (<filename>~/.bashrc</filename> for Bash shell), so that paths are already set whenever you start a shell. Setting <envar>PATH</envar> will ready Pology's scripts for execution, and <envar>PYTHONPATH</envar> its Python library for use in custom Python scripts. You should also build some documentation:
 <programlisting language="bash">
 $ <replaceable>POLOGYDIR</replaceable>/user/local.sh build  # user manual
 $ <replaceable>POLOGYDIR</replaceable>/api/local.sh build  # API documenation
 $ <replaceable>POLOGYDIR</replaceable>/lang/<replaceable>LANG</replaceable>/doc/local.sh build  # language-specific, if any
 </programlisting>
 This will make HTML pages appear in <filename><replaceable>POLOGYDIR</replaceable>/doc-html/</filename>. To have Pology scripts output translated messages, if there exists translation into your language, you can execute:
 <programlisting language="bash">
 $ <replaceable>POLOGYDIR</replaceable>/po/pology/local.sh build [<replaceable>LANG</replaceable>]
 </programlisting>
 This will put compiled PO files into <filename><replaceable>POLOGYDIR</replaceable>/mo/</filename>, from where they will be automatically picked up by scripts running from the source directory.</para>
 
 <para>Pology provides <link linkend="sec-cmshellcomp"><emphasis>shell completion</emphasis></link> for some of the included scripts, which you can activate by sourcing the corresponding completion definition file. If you have installed Pology:
 <programlisting language="bash">
 $ . <replaceable>INSTALLDIR</replaceable>/share/pology/completion/bash/pology
 </programlisting>
 and if running Pology from the source directory
 <programlisting language="bash">
 $ . <replaceable>POLOGYDIR</replaceable>/completion/bash/pology
 </programlisting>
 </para>
 
 </sect1>
 
 <sect1 id="sec-deps">
 <title>Dependencies</title>
 
 <para>The following lists the dependencies of Pology, and notes whether they are required or optional, and what they are used for.</para>
 
 <para>Required external Python packages:
 <itemizedlist>
 <listitem>
 <para>None.</para>
 </listitem>
 </itemizedlist>
 </para>
 
 <para>Required general software:
 <itemizedlist>
 <listitem>
 <para><ulink url="http://www.cmake.org/">CMake</ulink> >= 2.8.3. The build system used for Pology.</para>
 </listitem>
 <listitem>
 <para><ulink url="http://www.gnu.org/software/gettext/">Gettext</ulink> >= 0.17. Some Pology scripts use Gettext tools internally, and the library module <ulink url="../../api/html/pology.gtxtools-module.html"><literal>pology.gtxtools</literal></ulink> wraps some of Gettext tools for use inside Python scripts. Also needed to build Pology user interface and documentation translations.</para>
 </listitem>
 <listitem>
 <para><ulink url="http://www.python.org/">Python</ulink> >= 2.5.</para>
 </listitem>
 </itemizedlist>
 </para>
 
 <para>Optional external Python packages:
 <itemizedlist>
 <listitem>
 <para><ulink url="http://freedesktop.org/wiki/Software/DBusBindings"><package>python-dbus</package></ulink> >= 0.81. Used for communication with various external applications (e.g. with the <ulink url="http://userbase.kde.org/Lokalize">Lokalize</ulink> PO editor).</para>
 </listitem>
 <listitem>
 <para><ulink url="http://www.rfk.id.au/software/pyenchant/"><package>python-enchant</package></ulink> >= 1.5.2. Frontend to various spell-checkers, used by most of Pology's spell checking functionality.</para>
 </listitem>
 <listitem>
 <para><ulink url="http://pygments.org"><package>python-pygments</package></ulink> >= 1.6. Syntax highlighting for PO and other code snippets in Pology documentation.</para>
 </listitem>
 </itemizedlist>
 </para>
 
 <para>Optional general software:
 <itemizedlist>
 <listitem>
 <para><ulink url="http://www.apertium.org/">Apertium</ulink> >= 3.3. A free/open-source machine translation platform, used by <link linkend="sec-mimtrans">the <command>pomtrans</command> script</link>.</para>
 </listitem>
 <listitem>
 <para><ulink url="http://wiki.docbook.org/DocBookXslStylesheets">Docbook XSL</ulink> >= 1.75.2. XSL transformations for converting Docbook into various end-user formats, used for building Pology documentation.</para>
 </listitem>
 <listitem>
 <para><ulink url="http://epydoc.sourceforge.net">Epydoc</ulink> >= 3.0. Python doctring to HTML doc generator. Needed to build the API documentation of Pology Python library.</para>
 </listitem>
 <listitem>
 <para><ulink url="http://www.languagetool.org/">LanguageTool</ulink> >= 1.0. Open source language checker, used by the <link linkend="sv-check-grammar"><command>check-grammar</command></link> sieve.</para>
 </listitem>
 <listitem>
 <para><ulink url="http://xmlsoft.org/">Libxml2</ulink>. XML processing library. Some of command line tools that come with it are needed to build Pology documentation (<command>xmllint</command>, <command>xsltproc</command>).</para>
 </listitem>
 <listitem>
 <para>Version control systems. Used by various Pology scripts that process PO files on the collection level, when the PO files are under version control. Currently supported: <ulink url="http://git-scm.com/">Git</ulink> >= 1.6, <ulink url="http://subversion.tigris.org/">Subversion</ulink> >= 1.4.</para>
 </listitem>
 </itemizedlist>
 </para>
 
 </sect1>
 
 </chapter>