Warning, /sdk/pology/doc/user/common.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"
 [
     <!ENTITY apibase "../../api/en_US">
     <!ENTITY ap "&apibase;/pology.">
     <!ENTITY am "-module.html#">
 ]>
 
 <chapter id="ch-common">
 <title>Common Functionality</title>
 
 <para>Different parts of Pology provide common functionality, such as thematic groups of options to scripts, file selection patterns, reliance on PO metadata, etc. This chapter describes such common functionality.</para>
 
 <!-- ======================================== -->
 <sect1 id="sec-cmshellcomp">
 <title>Shell Completion</title>
 
 <para>Shell completion means that, similarly as for command names, it is possible to contextually complete command parameters by pressing the <keycap>Tab</keycap> key. This allows you to efficiently type in the command line, as well as to quickly remind yourself of options and option parameters without resorting to documentation or browsing the file system.</para>
 
 <para>For example, pressing <keycap>Tab</keycap> just after <link linkend="ch-sieve">the <command>posieve</command> command</link> will complete sieve names, and <keycap>Tab</keycap> after the <option>-s</option> option will complete sieve parameters based on sieves that precede it in the command line. This:
 <programlisting language="bash">
 $ posieve s&lt;TAB&gt;
 </programlisting>
 will show all sieves beginning with <literal>s</literal>, and complete the sieve name once sufficient number of characters have been entered to uniquely determine it, while this:
 <programlisting language="bash">
 $ posieve stats -s m&lt;TAB&gt;
 </programlisting>
 will show all parameters to <command>stats</command> beginning with <literal>m</literal>, and complete one of them after few more characters are typed in.</para>
 
 </sect1>
 
 <!-- ======================================== -->
 <sect1 id="sec-cmconfig">
 <title>User Configuration</title>
 
 <para>Various parts of Pology can be configured through the configuration file <filename>.pologyrc</filename> in the root of user's home directory (<filename>~/.pologyrc</filename> for short). The configuration file does not have to exist, so you have to create it when you want to configure something for the first time. It must be UTF-8 encoded.</para>
 
 <para>The configuration file is in the <ulink url="http://en.wikipedia.org/wiki/INI_file">INI</ulink> format, which is composed of sections beginning with a <literal>[<replaceable>section</replaceable>]</literal> line, and fields of the form <literal><replaceable>field</replaceable> = <replaceable>value</replaceable></literal> within a section. Comments can be written after <literal>#</literal> character at the beginning of the line. Here is an example of a <filename>~/.pologyrc</filename> file:
 <programlisting language="ini">
 [global]
 
 [user]
 name = Chusslove Illich
 original-name = Часлав Илић
 email = caslav.ilic@gmx.net
 po-editor = Kate
 
 [enchant]
 # Autodetection sufficient.
 
 [posieve]
 msgfmt-check = yes
 param-ondiff/stats = yes
 
 # Project setups follow.
 
 [project-kde]
 language = sr
 language-team = Serbian
 team-email = kde-i18n-sr@kde.org
 plural-forms = nplurals=4; plural=n==1 ? ...
 </programlisting>
 This configuration contains five sections: <literal>[global]</literal>, <literal>[user]</literal>, <literal>[enchant]</literal>, <literal>[posieve]</literal>, and <literal>[project-kde]</literal>. The <literal>[global]</literal> section set options that have an effect throught Pology, and here it is empty. The <literal>[user]</literal> section provides some information on the person who uses Pology. The <literal>[enchant]</literal> section configures the Enchant spell checker wrapper, used by Pology for spell checking. The <literal>[posieve]</literal> section configures the behavior of the <link linkend="ch-sieve"><command>posieve</command></link> script. The <literal>[project-kde]</literal> section provides information on a project that the user contributes translation to.</para>
 
 <para>Some details about the configuration file syntax are as follows. Leading and trailing whitespace in section and field names and values is not significant,  e.g. <literal>foo=bar</literal> is same as <literal>foo = bar</literal>. Percent (%) character is used to expand the value of another field, for example:
 <programlisting language="ini">
 rootdir = /path/to/somewhere
 datadir = %(rootdir)s/data
 </programlisting>
 where the <literal>%(...)s</literal> is Python's string interpolation syntax. Importantly, when you need a literal % character within a value (such as in <literal>plural-forms</literal> field in the previous example), you must repeat it twice, <literal>%%</literal>. Switch-type fields (<literal>msgfmt-check</literal> in the previous example) can take any of the following values for the two states: <literal>0</literal>, <literal>no</literal>, <literal>false</literal>, or <literal>off</literal>; and <literal>1</literal>, <literal>yes</literal>, <literal>true</literal>, or <literal>on</literal> (case is not important).</para>
 
 <para>Sections in the configuration can be of one of four general types:
 <itemizedlist>
 <listitem>
 <para>General sections, which provide information used by various parts of Pology as they need them. The <literal>[global]</literal> and <literal>[user]</literal> sections from the previous example are general sections.</para>
 </listitem>
 <listitem>
 <para>External tool sections, which are used to configure external libraries and programs used within Pology. The <literal>[enchant]</literal> section from the previous example is of this type.</para>
 </listitem>
 <listitem>
 <para>Internal tool sections, which configure the behavior of Pology's own scripts. This is the <literal>[posieve]</literal> section from the previous example.</para>
 </listitem>
 <listitem>
 <para>Project sections, which provide information related to particular translation projects that the user is contributing to. Names of these sections always start with <literal>project-</literal>, such as <literal>[project-kde]</literal> from the previous example.</para>
 </listitem>
 </itemizedlist>
 Internal tool sections are documented together with the respective tools, while sections of other types are described in the following.</para>
 
 <para>When mentioning configuration fields in their documentation and elsewhere, they are referred to as <literal>[<replaceable>section</replaceable>]/<replaceable>field</replaceable></literal>. If there is only a fixed number of possible values to a field, this is denoted as <literal>[<replaceable>section</replaceable>]/<replaceable>field</replaceable>=[<replaceable>VALUE1</replaceable>|<replaceable>VALUE2</replaceable>|<replaceable>VALUE3</replaceable>|...]</literal>; if one of the values is the default, it is prefixed with a star (*).</para>
 
 <sect2 id="sec-cmcfgglobal">
 <title>The <literal>[global]</literal> section</title>
 
 <para>The <literal>[global]</literal> section contains options which can have effect on various otherwise unrelated parts of Pology.</para>
 
 <para>Known configuration fields are as follows:
 <variablelist>
 
 <varlistentry>
 <term><literal>[global]/show-backtrace=[yes|*no]</literal></term>
 <listitem>
 <para>When one of Pology commands stops execution with an error, by default only the error message is shown. However, for reporting problems and debugging, it is much better to get a <emphasis>backtrace</emphasis> instead. Backtraces can be activated by this option.</para>
 
 <para><emphasis>Whenever you want to report a problem where a Pology command aborts with an error, make sure to activate this option and submit the full backtrace.</emphasis></para>
 </listitem>
 </varlistentry>
 
 </variablelist>
 </para>
 
 </sect2>
 
 <sect2 id="sec-cmcfguser">
 <title>The <literal>[user]</literal> section</title>
 
 <para>Many parts of Pology can take advantage of information about you and the tools you use. This information is given in the <literal>[user]</literal> section. For example, when initializing PO file from a template, your name, email address in the PO header can be filled out, or a PO file can be opened in a translation editor that you use (if it is supported).</para>
 
 <para>Known configuration fields are as follows:
 <variablelist>
 
 <varlistentry>
 <term><literal>[user]/name</literal></term>
 <listitem>
 <para>Your name if it is written in Latin script, or the romanized equivalent of your name. The intention is that it is readable (or semi-readable) to people from various places in the world, who would use it to contact you if necessary.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term><literal>[user]/original-name</literal></term>
 <listitem>
 <para>This is your name in your native language and script, whatever it may be. If it would be the same as the name in the <literal>[user]/name</literal> field, setting this field is not necessary.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term><literal>[user]/email</literal></term>
 <listitem>
 <para>Your email address.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term><literal>[user]/language</literal></term>
 <listitem>
 <para>The language code of the language you translate into. If by any chance you translate into several languages, this field can be overridden in per-project configuration sections.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term><literal>[user]/encoding</literal></term>
 <listitem>
 <para>The encoding of the PO files you work on. Nowdays this should really, really be UTF-8. If it is not UTF-8 for everything that you work on, you can override it in per-project configuration sections.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term><literal>[user]/plural-forms</literal></term>
 <listitem>
 <para>The value for the <link linkend="sec-poplurals"><literal>Plural-Forms</literal> PO header field</link> used for your language. If it differs between projects, you can override the value set here in per-project configuration sections.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term><literal>[user]/po-editor</literal></term>
 <listitem>
 <para>The human-readable name of the editor with which you translate (it does not have to be a dedicated PO editor). This is used in contexts where your editor preference is announced, such as through the <literal>X-Generator</literal> PO header field.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term><literal>[user]/po-editor-id=[lokalize]</literal></term>
 <listitem>
 <para>The keyword under which the PO editor that you use is known to Pology. For the moment, only Lokalize is supported. This is used when a Pology tool is told to open PO files on the messages it matched.</para>
 </listitem>
 </varlistentry>
 
 </variablelist>
 </para>
 
 </sect2>
 
 <sect2 id="sec-cmcfgenchant">
 <title>The <literal>[enchant]</literal> section</title>
 
 <para>This section configures <ulink url="http://www.abisource.com/projects/enchant/">Enchant</ulink>, a wrapper library for spell checking, which is used for Pology's <link linkend="sec-lgspell">spell checking functionality</link>. Through Enchant it is possible to use various spell checkers, such as Aspell, Ispell, Hunspell, etc. in a uniform way.</para>
 
 <para>Known configuration fields are as follows:
 <variablelist>
 
 <varlistentry>
 <term><literal>[enchant]/provider=[aspell|ispell|myspell|...]</literal></term>
 <listitem>
 <para>The keyword denoting the spell checker that Enchant should use. It can also be a comma-separated list of several keywords, when Enchant will use the first available spell checker in the list. You can find the up-to-date list of all known provider keywords in the <command>enchant(1)</command> man page, and run <command>enchant-lsmod</command> command to see exactly which of those are recognized as available on the system.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term><literal>[enchant]/language</literal></term>
 <listitem>
 <para>The spell checking dictionary that should be used, by language code. This value is used only if the language is not specified in any other way, such as in the PO header or through command line.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term><literal>[enchant]/environment</literal></term>
 <listitem>
 <para>The sub-language environment for spell checking. This is related to Pology's internal spelling dictionary supplements, see the <link linkend="sec-lgspell">section on spell checking</link>. This value is used only if the environment is not specified in any other way, such as in the PO header or through command line.</para>
 </listitem>
 </varlistentry>
 
 </variablelist>
 </para>
 
 </sect2>
 
 <sect2 id="sec-cmcfgaspell">
 <title>The <literal>[aspell]</literal> section</title>
 
 <para>At first Pology used <ulink url="http://aspell.net/">Aspell</ulink> for spell checking, before Enchant was introduced. Direct support for Aspell was nevertheless kept, due to some specifics that the Enchant wrapper does not support yet. (Which means that you should better use Enchant if it satisfies your needs.)</para>
 
 <para>Known configuration fields are as follows:
 <variablelist>
 
 <varlistentry>
 <term><literal>[aspell]/language</literal></term>
 <listitem>
 <para>See <literal>[enchant]/language</literal>.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term><literal>[aspell]/encoding</literal></term>
 <listitem>
 <para>Encoding for the text sent to Aspell.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term><literal>[aspell]/variety</literal></term>
 <listitem>
 <para>The sub-language variety of the Aspell spelling dictionary.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term><literal>[aspell]/environment</literal></term>
 <listitem>
 <para>See <literal>[enchant]/environment</literal>.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term><literal>[aspell]/supplements-only=[yes|*no]</literal></term>
 <listitem>
 <para>Whether to ignore the system spelling dictionary and use only Pology's internal dictionary supplements.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term><literal>[aspell]/simple-split=[yes|*no]</literal></term>
 <listitem>
 <para>By default, Pology splits the text into words in a clever fashion (eliminating text markup, format directives, etc.) before sending them to the spell checker. Sometimes this leads to bad result, and then this field can be set to <literal>yes</literal> to split text simply on whitespace (possibly, in the given context, in combination with <link linkend="sec-cmhooks">a pre-filtering hook</link> on the text).</para>
 </listitem>
 </varlistentry>
 
 </variablelist>
 </para>
 
 </sect2>
 
 <sect2 id="sec-cmcfgproj">
 <title>Per-project sections (<literal>[project-*]</literal>)</title>
 
 <para>You will easily come into the situation where you need to translate and maintain translated material within different projects, each with its own set of rules and conventions. Pology is designed to support project switching extensively, and one element of that are per-project configuration sections.</para>
 
 <para>A project configuration sections has the name <literal>[project-<replaceable>PKEY</replaceable>]</literal>, where <replaceable>PKEY</replaceable> is the project keyword. You can choose the project keyword freely, but it should contain only ASCII letters, digits, underscore and hyphen. Project configuration fields frequently have fallbacks to fields in other configuration sections. This means that when the project field is not set, its corresponding field in that other (more general) section gets used instead. In the following, this is the whenever you are instructed to see a field in another section.</para>
 
 <para>Per-project configuration fields are as follows:
 <variablelist>
 
 <varlistentry>
 <term><literal>[project-*]/name</literal></term>
 <listitem>
 <para>See <literal>[user]/name</literal>.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term><literal>[project-*]/original-name</literal></term>
 <listitem>
 <para>See <literal>[user]/original-name</literal>.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term><literal>[project-*]/email</literal></term>
 <listitem>
 <para>See <literal>[user]/email</literal>.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term><literal>[project-*]/language</literal></term>
 <listitem>
 <para>See <literal>[user]/language</literal>.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term><literal>[project-*]/language-team</literal></term>
 <listitem>
 <para>This is the name of the team which translates this project into given language. Since usually there is only one translation team per language in a project, the value of this field is just the human-readable name of the language (as opposed to language code) in English.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term><literal>[project-*]/team-email</literal></term>
 <listitem>
 <para>The email address for communication with the translation team as whole (usually the team's mailing list).</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term><literal>[project-*]/encoding</literal></term>
 <listitem>
 <para>See <literal>[user]/encoding</literal>.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term><literal>[project-*]/plural-forms</literal></term>
 <listitem>
 <para>See <literal>[user]/plural-forms</literal>.</para>
 </listitem>
 </varlistentry>
 
 </variablelist>
 </para>
 
 </sect2>
 
 </sect1>
 
 <!-- ======================================== -->
 <sect1 id="sec-cmregex">
 <title>Regular Expressions</title>
 
 <para>There are great many places in Pology where you can supply a matching pattern, to select or deselect something. This could be a PO file by its path, a PO message by its <varname>msgid</varname>, etc. Almost always and by default, this matching pattern will be a <emphasis>regular expression</emphasis> (or <emphasis>regex</emphasis> for short). Regular expressions are a powerful pattern matching language, a fascinating topic in their own right, and they will serve you well in just about any context of searching on computers. The plain text editor that you use probably offers regular expressions in its search dialog, so does your office text processor, and so on.</para>
 
 <para>Actually, the only point of this brief section is to impress the importance and usefulness of regular expressions onto you, in the case that you have not used them yet. The Internet is full of tutorials on regular expressions, so that there is no point in linking any one particular here.</para>
 
 <para>It should be mentioned that different regular expression engines have somewhat different syntax and expressiveness. Pology uses regular expressions from the Python Standard Library, described here: <ulink url="http://docs.python.org/library/re.html">http://docs.python.org/library/re.html</ulink> (keep in mind that this page is a reference, and not a tutorial, so you should look elsewhere to learn basics of regular expressions).</para>
 
 </sect1>
 
 <!-- ======================================== -->
 <sect1 id="sec-cmincexc">
 <title>Path Inclusion and Exclusion</title>
 
 <para>Pology scripts that can recursively search directory paths for PO files will usually provide several options by which certain files can be included or excluded from processing. The first pair of these options include or exclude files by path:
 <variablelist>
 
 <varlistentry>
 <term><option>-E <replaceable>REGEX</replaceable></option>, <option>--exclude-path=<replaceable>REGEX</replaceable></option></term>
 <listitem>
 <para>Every file with the path that does not match the supplied pattern is excluded from processing. This option can be repeated, when a file is excluded if its path matches <emphasis>every</emphasis> pattern. When you want to exclude by <emphasis>any</emphasis> pattern matching the path, you can connect those patterns with regular expression <literal>|</literal>-operator in a single option. This allows you to build up complex exclusion conditions if necessary.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term><option>-I <replaceable>REGEX</replaceable></option>, <option>--include-path=<replaceable>REGEX</replaceable></option></term>
 <listitem>
 <para>Only those files which have the path matching the supplied pattern are included into processing. If the option is repeated, a file is included only if its path matches every pattern.</para>
 </listitem>
 </varlistentry>
 
 </variablelist>
 </para>
 
 <para>Especially those PO files which are used at runtime (as opposed to those used for <link linkend="p-dynstattr">static translation</link>), but others too, are frequently sufficiently identified by their <emphasis>domain</emphasis> name. The domain name is the base name of the installed MO file without the extension, e.g. for <filename>/usr/share/locale/sr/LC_MESSAGES/foobar.mo</filename> the domain name is <literal>foobar</literal>. If, in a given translation project, PO files for a given language are all collected under one top directory of that language, their base names are also formed of domain names.<footnote>
 <para>The other frequently encountered file organization is when there is one directory per PO domain, and that directory contains PO files for all languages, named as <filename><replaceable>LANG</replaceable>.po</filename>.</para>
 </footnote> When this is the case, it may be more convenient or safer to match PO files by their domain names instead of paths, which is done by options:
 <variablelist>
 
 <varlistentry>
 <term><option>-e <replaceable>REGEX</replaceable></option>, <option>--exclude-name=<replaceable>REGEX</replaceable></option></term>
 <listitem>
 <para>Counterpart to <option>-E</option>/<option>--exclude-path</option> which matches by domain name.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term><option>-i <replaceable>REGEX</replaceable></option>, <option>--include-name=<replaceable>REGEX</replaceable></option></term>
 <listitem>
 <para>Counterpart to <option>-I</option>/<option>--include-path</option> which matches by domain name.</para>
 </listitem>
 </varlistentry>
 
 </variablelist>
 </para>
 
 <para>All inclusion and exclusion options can be freely mixed and repeated, with consequent resolution. A file is processed if it matches all inclusion patterns (if any is given) and does not match at least one exclusion pattern (if any is given). The other way around, a file is not processed if does not match at least one inclusion pattern (if any is given) or it matches all exclusion patterns (if any is given).</para>
 
 </sect1>
 
 <!-- ======================================== -->
 <sect1 id="sec-cmffrom">
 <title>Reading Paths From a File</title>
 
 <para>Sometimes it is convenient to make a temporary or semi-permanent grouping of files, such that the file group can be referenced through a single argument instead of repeating all the files all the time. This is particularly useful when shell piping is not applicable or not comfortable enough. The classic and simple way to group files is by having a file-list file, which contains one file path by line, which a shell command can read to collect files to process.</para>
 
 <para>Many Pology scripts can write and read file-list files. Having scripts write such files automatically is simple enough, just check given script's documentation to see if it has this capability (e.g. the <option>-m</option> option to <command>posieve</command>). More interesting are the special features that you can use when writing a file-list file manually. You would do this for standing categories which are periodically updated, such as a list of PO files ready for release.</para>
 
 <para>For completeness, here is first an example of a basic file-list file:
 <programlisting>
 xray/alpha.po
 xray/bravo.po
 yankee/charlie.po
 yankee/delta.po
 </programlisting>
 </para>
 
 <para>As is usual for path arguments to Pology scripts, you can specify both file and directory paths, and directory paths will be searched recursively for PO files (or whatever the file type that the script is processing):
 <programlisting>
 xray/
 yankee/
 zulu/echo.po
 zulu/foxtrot.po
 </programlisting>
 </para>
 
 <para>You can add comments by starting the line with hash (<literal>#</literal>), and have empty lines:
 <programlisting>
 # Translations ready for release.
 
 # Full modules.
 xray/
 yankee/
 
 # Specific files.
 zulu/echo.po
 zulu/foxtrot.po
 </programlisting>
 </para>
 
 <para>The inclusion-exclusion functionality equivalent to <link linkend="sec-cmincexc">inclusion-exclusion command line options</link> is provided through inclusion-exclusion directives. They are specified by starting the line with colon (<literal>:</literal>), followed by directive type token, followed by a regular expression. The directives are:
 <itemizedlist>
 <listitem>
 <para><literal>:/-<replaceable>REGEX</replaceable></literal> to exclude files by path,</para>
 </listitem>
 <listitem>
 <para><literal>:/+<replaceable>REGEX</replaceable></literal> to include files by path,</para>
 </listitem>
 <listitem>
 <para><literal>:-<replaceable>REGEX</replaceable></literal> to exclude files by base name without extension, and</para>
 </listitem>
 <listitem>
 <para><literal>:+<replaceable>REGEX</replaceable></literal> to include files by base name without extension.</para>
 </listitem>
 </itemizedlist>
 For example, if a whole module should be processed but for one PO file in it, it is easier to list the whole module and exclude that one file, as compared to listing all other files:
 <programlisting>
 # Modules.
 xray/
 yankee/
 # Exclude november.po (in whichever module it is).
 :-november
 </programlisting>
 Ordering and position of include-exclude directives is not significant, as they are all applied to all collected files. The semantics of application of multiple directives is the same as that of <link linkend="sec-cmincexc">counterpart command line options</link>.</para>
 
 <para>File-list files are normally fed to Pology scripts with the following option:
 <variablelist>
 
 <varlistentry>
 <term><option>-f <replaceable>FILE</replaceable></option>, <option>--files-from=<replaceable>FILE</replaceable></option></term>
 <listitem>
 <para>Read files to process from a file which contains one path per line, or special entries as described above. This option can be repeated to read several file lists. Additional paths to process can still be given as command line arguments. Any inclusion-exclusion options will be applied to the files read from the file as well (in addition to the file's internal inclusion-exclusion directives, if any).</para>
 </listitem>
 </varlistentry>
 
 </variablelist>
 </para>
 
 </sect1>
 
 <!-- ======================================== -->
 <sect1 id="sec-cmcolors">
 <title>Output Coloring</title>
 
 <para>In some contexts, Pology scripts color the terminal output for better visual separation and highlighting of important parts of the text. Examples include warning and error messages, data presented as tables and bars, and, importantly, matched segments of the text in search and validation operations.</para>
 
 <para>Output coloring is turned on by default, but sensitive to output destination: the text is colored if the output is to the terminal (using terminal escape sequences), but not if it is piped to a file. Pology scripts provide the following options by which you can influence this behavior:
 <variablelist>
 
 <varlistentry>
 <term><option>-R</option>, <option>--raw-colors</option></term>
 <listitem>
 <para>Disables output destination sensitivity, such that the text is always colored. This is useful when the output is piped to another command which can understand terminal escape sequences by which colors are produce, such as <command>less(1)</command>. A typical example would be piping search results from <link linkend="sv-find-messages">the <command>find-messages</command> sieve</link> to be able to scroll them back and forth:
 <programlisting language="bash">
 $ posieve find-messages ... -R | less -R
 </programlisting>
 The <option>-R</option> of <command>less</command> tells it to interpret escape sequences as colors, rather than showing them as literal text.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term><option>--coloring-type=[none|term*|html]</option></term>
 <listitem>
 <para>Instead of coloring for the terminal, with this option you can choose another coloring type. <literal>none</literal> disables coloring, <literal>term</literal> is the default, while <literal>html</literal> will produce HTML-tagged text ready for embedding into a web page (e.g. inside a &lt;pre&gt; element). For example, with a little bit of additional scripting, you could use <link linkend="sv-stats">the <command>stats</command> sieve</link> and <literal>html</literal> coloring to periodically update a web page with translation statistics.</para>
 </listitem>
 </varlistentry>
 
 </variablelist>
 </para>
 
 </sect1>
 
 <!-- ======================================== -->
 <sect1 id="sec-cminttools">
 <title>Integration with Other Tools</title>
 
 <para>One of the general aims of Pology is to fit well with other tools typically found in translation workflows based on PO. Although examples of this can be seen throughout the manual, this section gives the overview of integration by the particular supported tool.</para>
 
 <sect2 id="sec-cmsupped">
 <title>PO Editors</title>
 
 <para>When Pology is used to validate the translation, be it through informal but <link linkend="sv-find-messages">precise searches</link> or formal <link linkend="sec-lgrules">validation rules</link>, those translations found to be invalid must be modified (or possibly a special translator comment added to the message to silence a false positive). Pology will normally always report the PO file path and the location of the message within the file, so that you can get to it in you preferred PO editor. For greater efficiency, however, Pology can directly open the PO files on problematic messages in some PO editors. Currently these are:
 <variablelist>
 
 <varlistentry>
 <term><ulink url="http://userbase.kde.org/Lokalize">Lokalize</ulink></term>
 <listitem>
 <para>Many <link linkend="ch-sieve">sieves</link>, notably <command>find-messages</command>, <command>check-rules</command>, or <command>check-spell</command>, provide the parameter <option>lokalize</option> to open PO files on reported messages in Lokalize. This means that when run over a collection of PO files, each PO file with at least one reported message will be loaded into one of Lokalize tabs, and only the reported messages will be shown for editing under each tab. A slight catch is that Lokalize must be manually started before a sieve is run, and the Lokalize project which contains all the sieved PO files must be opened; otherwise, simply nothing will happen.</para>
 </listitem>
 </varlistentry>
 
 </variablelist>
 </para>
 
 </sect2>
 
 <sect2 id="sec-cmsuppvcs">
 <title>Version Control Systems</title>
 
 <para>From the viewpoint of translators, PO files are frequently (though not always) handled in the same way as program code, through version control systems (VCS). Pology defines an abstraction of version control functionality, which enables its tools to transparently cooperate with several VCS. Usually it is necessary to tell a Pology tool which VCS is used, which is done by specifying one of VCS keywords. Currently supported VCS and their keywords are:
 <itemizedlist>
 
 <listitem>
 <para><ulink url="http://git-scm.com/">Git</ulink>: <literal>git</literal></para>
 </listitem>
 
 <listitem>
 <para><ulink url="http://subversion.tigris.org/">Subversion</ulink>: <literal>svn</literal>, <literal>subversion</literal></para>
 </listitem>
 
 <listitem>
 <para>none (when specifying a VCS is required, but none is actually used): <literal>none</literal>, <literal>noop</literal></para>
 </listitem>
 
 </itemizedlist>
 </para>
 
 <para>VCS integration is available in following places:
 <itemizedlist>
 
 <listitem>
 <para>Producing embedded diffs with <command>poediff</command> (see <xref linkend="ch-diffpatch"/>). Option <option>-c</option>/<option>--vcs</option> can be used to switch <command>poediff</command> into VCS mode, such that it diffs given paths between repository head and working copy, or between given revisions.</para>
 </listitem>
 
 <listitem>
 <para>Translating in summit (see <xref linkend="ch-summit"/>). <command>posummit</command> will automatically add or remove files from version control as well as to and from disk, so that the modified repository tree can be directly committed after a summit maintenance operation has completed its run.</para>
 </listitem>
 
 <listitem>
 <para>Review ascription (see <xref linkend="ch-ascript"/>). VCS support is central part of <command>poascribe</command>, so it will automatically add, remove and commit files to version control as particular ascription operations require.</para>
 </listitem>
 
 </itemizedlist>
 </para>
 
 <para>Another interesting aspect of VCS support is that, when writing modified PO files to disk, by default Pology will reformat them (almost) only as much as necessary. For example, if only one <varname>msgstr</varname> string in the whole PO file has changed, and wrapping is active, only this string and nothing else will be rewrapped when the file is written out. This makes VCS revision deltas smaller and more informative.</para>
 
 </sect2>
 
 </sect1>
 
 <!-- ======================================== -->
 <sect1 id="sec-cmwrap">
 <title>Line Wrapping in PO Messages</title>
 
 <para>While <link linkend="sec-powrap">line wrapping of message strings</link> irrelevant to programs that fetch translations from them, it may be significant to the translator, especially when editing the PO file with a plain text editor. Well-wrapped strings make it easier for the translator to follow the text structure, especially in longer messages.</para>
 
 <para>Most Gettext tools (<command>msgmerge</command>, <command>msgcat</command>, <command>msgfilter</command>, etc.) provide options to wrap or not to wrap strings, where wrapping is done on the given column and escaped newlines (<literal>\n</literal>). Pology can produce this type of wrapping ("basic" wrapping) as well, but it can also wrap on expected visual line breaks in known text markup, e.g. <literal>&lt;p&gt;</literal> and <literal>&lt;br&gt;</literal> in HTML ("fine" wrapping). Compare this message in basic wrapping alone:
 <programlisting language="po">
 msgid ""
 "&lt;p>These settings control the storage of the corrected images. "
 "There are four modes to choose from:&lt;/p>&lt;p>&lt;ul>&lt;li>&lt;b>Subfolder:&lt;/"
 "b> The corrected images will be saved in a subfolder under the "
 "current album path.&lt;/li>&lt;li>&lt;b>Prefix:&lt;/b> A custom prefix will be "
 "added to the corrected image.&lt;/li>&lt;li>&lt;b>Suffix:&lt;/b> A custom "
 "suffix will be added to the corrected image.&lt;/li>&lt;li>&lt;b>Overwrite:&lt;/"
 "b> All original images will be replaced.&lt;/li>&lt;/ul>&lt;/p>&lt;p>Each of "
 "the four modes allows you to add an optional keyword to the image "
 "metadata.&lt;/p>"
 msgstr ""
 </programlisting>
 and in basic and fine wrapping together:
 <programlisting language="po">
 msgid ""
 "&lt;p>These settings control the storage of the corrected images. "
 "There are four modes to choose from:&lt;/p>"
 "&lt;p>"
 "&lt;ul>"
 "&lt;li>&lt;b>Subfolder:&lt;/b> The corrected images will be saved in a "
 "subfolder under the current album path.&lt;/li>"
 "&lt;li>&lt;b>Prefix:&lt;/b> A custom prefix will be added to the corrected "
 "image.&lt;/li>"
 "&lt;li>&lt;b>Suffix:&lt;/b> A custom suffix will be added to the corrected "
 "image.&lt;/li>"
 "&lt;li>&lt;b>Overwrite:&lt;/b> All original images will be replaced.&lt;/li>"
 "&lt;/ul>"
 "&lt;/p>"
 "&lt;p>Each of the four modes allows you to add an optional keyword "
 "to the image metadata.&lt;/p>"
 msgstr ""
 </programlisting>
 If you are editing the PO file with a dedicated PO editor, it may itself provide finely tuned wrapping and ignore the wrapping in the PO file, in which case Pology's wrapping facilities are superfluous to you<footnote>
 <para>But if several people are working on a collection of PO files, it is nevertheless good to agree on fixed wrapping. This is both friendly to those exposed to original wrapping, and to version control systems.</para>
 </footnote>. But a PO editor may also present strings wrapped just as they are in the PO file (and most do!), when Pology's fine wrapping is just as useful as in combination with a plain text editor.</para>
 
 <para>At least for alphabetic languages, the most convenient wrapping may be fine wrapping alone (no basic wrapping), while turning on editor's dynamic (visual) line wrapping. This both makes the text structure easy to follow, and allows editing the translation by logical units (paragraphs, list items) without manually adjusting column breaks or putting up with ugly overlength or mid-broken lines. However, for ideographic languages, editor's dynamic line wrapping may produce bad results, and there basic wrapping might be necessary. In fact, for the moment, for ideographic languages it may be better to pass Pology's wrapping entirely and stick with Gettext's wrapping, since the wrapping algorithm in Gettext is more sophisticated and directly supports ideographic writing systems.</para>
 
 <para>If no wrapping mode is specified when the given PO file is written out, Pology will apply basic wrapping, just as Gettext tools do. There are three general sources from which Pology tools may try to determine the wrapping mode for the given PO file, in decreasing priority: from the command line options, from the PO file's header, and from the user configuration. A tool may or may not provide command line options and configuration fields for wrapping, but PO file headers are always consulted (since this is in Pology's core PO file handling facilities). See the description of <link linkend="hdr-x-wrapping">the <literal>X-Wrapping</literal> header field</link> for how to set the wrapping mode in the PO header, and <link linkend="sv-set-header">the <literal>set-header</literal> sieve</link> for how to set this field in many PO files at once.</para>
 
 <sect2 id="sec-cmwropts">
 <title>Common Command Line Options for Wrapping</title>
 
 <para>Pology tools in which the wrapping mode can be set from command line, will provide the following options:
 <variablelist>
 
 <varlistentry>
 <term><option>--wrap</option></term>
 <listitem>
 <para>Perform basic wrapping, on certain column.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term><option>--no-wrap</option></term>
 <listitem>
 <para>Do not perform basic wrapping.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term><option>--fine-wrap</option></term>
 <listitem>
 <para>Perform fine wrapping, on various expected visual breaks introduced by text markup in rendered text.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term><option>--no-fine-wrap</option></term>
 <listitem>
 <para>Do not perform fine wrapping.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term><option>--wrap-column=<replaceable>COL</replaceable></option></term>
 <listitem>
 <para>The column at which the text should be wrapped. The wrapped line in the PO file will never be longer than this many columns, including the outer quotes. If not given, the default is 79.</para>
 </listitem>
 </varlistentry>
 
 </variablelist>
 Both positive and negative wrapping options are provided in order to be able to override the wrapping mode defined by the user configuration of the PO header. As in Gettext tools, strings are always wrapped on <literal>\n</literal> regardless of the wrapping mode.</para>
 
 </sect2>
 
 <sect2 id="sec-cmwrcfg">
 <title>Common User Configuration Fields for Wrapping</title>
 
 <para>The following configuration fields will be read by the tools which consult the user configuration for wrapping mode, in their respective configuration sections:
 <variablelist>
 
 <varlistentry>
 <term><literal>[<replaceable>section</replaceable>]/wrap=[*yes|no]</literal></term>
 <listitem>
 <para>Whether to perform basic wrapping, counterpart to <option>--wrap</option> and <option>--no-wrap</option> command line options.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term><literal>[<replaceable>section</replaceable>]/fine-wrap=[yes|*no]</literal></term>
 <listitem>
 <para>Whether to perform fine wrapping, counterpart to <option>--fine-wrap</option> and <option>--no-fine-wrap</option> command line options.</para>
 </listitem>
 </varlistentry>
 
 </variablelist>
 </para>
 
 </sect2>
 
 </sect1>
 
 <!-- ======================================== -->
 <sect1 id="sec-cmheader">
 <title>Influential Header Fields</title>
 
 <para><link linkend="sec-poheader">The PO header</link> is a natural place to provide the information which holds for the PO file as whole. Pology scripts, sieves, and hooks can take into account a number of header fields, when available, to automatically determine some aspects of processing. The fields considered are as follows:
 <variablelist>
 
 <varlistentry id="hdr-language">
 <term><literal>Language</literal></term>
 <listitem>
 <para>This field contains the language code of the translation, which Pology will take into account in all contexts where language-dependent processing is done (such as when <link linkend="sec-lgspell">spell-checking</link>). You can also specify the language into which you translate in <link linkend="sec-cmconfig">user configuration</link>, and sometimes in the command line. The language stated by the PO header will override the user configuration, but it will be in turn overridden by the command line. See also <xref linkend="sec-lglangenv"/>.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry id="hdr-x-accelerator-marker">
 <term><literal>X-Accelerator-Marker</literal></term>
 <listitem>
 <para><link linkend="sec-poaccel">Accelerator markers</link> are a frequent obstacle in text processing, such as <link linkend="sv-find-messages">searching</link> or <link linkend="sec-lgspell">spell-checking</link>, because they can split words apart. This field can be used to specify which character is used as accelerator marker throughout the file, if any. If there are several possible characters, they can be given as comma-separated list<footnote>
 <para>This does mean that the case when the comma itself is the accelerator marker is not covered, but this case is beyond unlikely.</para>
 </footnote>. While it is usually possible to specify the accelerator marker through the command line, the header field is much more convenient and flexible: there is no need to remember to add the command line option at every run, and different PO files can have different accelerator markers. However, if command line option is issued, it will override the header field.</para>
 
 <para>There is a difference between this field not existing in the header, and existing but with an empty value (i.e. <literal>"X-Accelerator-Marker: \n"</literal>). If the field does not exist, some processing elements will go into the "greedy" mode, where they use a list of known frequent accelerator markers (e.g. to remove them from the text). If the field is set to empty value, these processing elements will take it that there are no accelerator markers in text.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry id="hdr-x-associated-ui-catalogs">
 <term><literal>X-Associted-UI-Catalogs</literal></term>
 <listitem>
 <para>This field lists the PO domains which are the source of user interface references (button labels, menu items, etc.) throughout the text in current PO file. This makes it possible to automatically fetch and insert UI translations, rather than having to look them up manually and maintain them against changes; see <xref linkend="sec-lguirefs"/> for details. Several PO domains can be given as space- or comma-separated list. If the UI message is found in more than one listed PO domain, the earlier in the list takes precedence.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry id="hdr-x-environment">
 <term><literal>X-Environment</literal></term>
 <listitem>
 <para>The language environment to which the translation belongs; see <xref linkend="sec-lglangenv"/> for details. It can be a single keyword, or a comma-separated list of keywords. If several environments are given, the later in the list (which is usually the more specific) takes precedence.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry id="hdr-x-text-markup">
 <term><literal>X-Text-Markup</literal></term>
 <listitem>
 <para>When the text contains <link linkend="sec-pomarkup">markup</link>, it may be useful to remove it such that only the plain text remains. This is the case, for example, when computing word counts or applying <link linkend="sec-lgrules">terminology validation rules</link>. Another use case would be the validation of markup itself (whether a tag is properly closed, whether a tag exists, etc.) This header field specifies the markup type found in the text, as a keyword, so that Pology can determine how to process it. Several markup types can be given as comma-separated list.</para>
 
 <para>Pology currently recognizes the following markup types:
 <itemizedlist>
 <listitem><para><literal>docbook4</literal> -- Docbook 4.x markup, in documentation POs</para></listitem>
 <listitem><para><literal>html</literal> -- HTML 4.01</para></listitem>
 <listitem><para><literal>kde4</literal> -- markup in KDE4 UI POs, a mix of Qt rich-text and KUIT</para></listitem>
 <listitem><para><literal>kuit</literal> -- UI semantic markup in KDE 4</para></listitem>
 <listitem><para><literal>qtrich</literal> -- Qt rich-text, (almost) a subset of HTML</para></listitem>
 <listitem><para><literal>xmlents</literal> -- only XML-like entities, no other formal markup</para></listitem>
 </itemizedlist>
 </para>
 
 </listitem>
 </varlistentry>
 
 <varlistentry id="hdr-x-wrapping">
 <term><literal>X-Wrapping</literal></term>
 <listitem>
 <para>This header field can be set to tell Pology how to <link linkend="sec-cmwrap">wrap strings</link> in the current PO file, for example, when <command>posieve</command> modifies a message and writes the modified PO file, or when rewrapping is done explicitly by <command>porewrap</command>. The value is a comma-separated list of wrapping modes, chosen from:
 <itemizedlist>
 <listitem><para><literal>basic</literal> -- wrapping on certain column</para></listitem>
 <listitem><para><literal>fine</literal> -- wrapping on logical breaks (such as <literal>&lt;p&gt;</literal> or <literal>&lt;br/&gt;</literal> tags)</para></listitem>
 </itemizedlist>
 Wrapping on escaped newline <literal>\n</literal> is always performed, regardless of the wrapping mode. If the field value is empty, no other wrapping is done. If more than one wrapping mode is given (e.g. <literal>"X-Wrapping: basic, fine\n"</literal>), it is specificaly defined how modes are combined, so the ordering is not important. As usual, if wrapping is specified by a command line option, that will override the header field.</para>
 </listitem>
 </varlistentry>
 
 </variablelist>
 </para>
 
 <para>All of the listed header fields may be set manually, when you get to work on the particular PO file. But frequently it is possible to set them automatically, or at least automatically for the first time with later manual corrections where needed. For this you may use <link linkend="sv-set-header">the <command>set-header</command> sieve</link>. If PO files are periodically merged by the translation project automation (rather than each translator merging on his own only the PO files which he is about to update), the natural moment to run <command>set-header</command> is just after the merging. If translation is done <link linkend="ch-summit">in summit</link>, you can specify in summit configuration to set header fields on merging.</para>
 
 </sect1>
 
 <!-- ======================================== -->
 <sect1 id="sec-cmhooks">
 <title>Processing Hooks</title>
 
 <para>Pology enables the user to insert special processing elements, called <emphasis>hooks</emphasis>, at many places in the processing chain. Hooks are Python functions with certain prescribed input, output, and behavior. Depending on the exact combination of these three ingredients, there are various <emphasis>hook types</emphasis>. Finally, some hooks can be adapted to a given context through their <emphasis>hook factories</emphasis>. Pology defines many hooks internally, and users can add their own external hooks.</para>
 
 <para>Usage of hooks is best illustrated through examples. Suppose that you want to use the <link linkend="sv-find-messages">the <command>find-messages</command> sieve</link> to look for a certain word, but the text contains XML-like tags of the form <literal>&lt;<replaceable>tagname</replaceable>&gt;...&lt;<replaceable>/tagname</replaceable>&gt;</literal> which happen to be throwing off your search. Suppose that there exists a hook called <literal>remove-xml-tags</literal>, in the Pology library module <literal>remove</literal>, which takes a piece of text as input and returns that piece of text cleared of any XML-like tags. Then you could insert this hook into the search to clear the tags before matching the text, by using the <option>filter:</option> parameter to <command>find-messages</command>:
 <programlisting language="bash">
 $ posieve find-messages -s filter:'remove/remove-xml-tags' ...
 </programlisting>
 Here <literal>remove/remove-xml-tags</literal> is the hook specification, and this is its usual simplest form: the module name, followed by slash, followed by the hook name. (Sometimes it can be only the module name, when the hook function within that module has the same name as the module, but this is rare.) The hook specification was enclosed in single quotes, for the shell to see it as single string; this was not necessary here, but it is a good habit to keep up when adding hooks through command line, because hook specification can get quite involved.</para>
 
 <para>Suppose now that there is a single hook that can remove any kind of markup from the text (not only XML-like tags) called <literal>remove-markup</literal>, but that it has to be told which markup to remove, by giving it one of the markup type keywords known to Pology. Continuing the previous example, this could be done like this:
 <programlisting language="bash">
 $ posieve find-messages -s filter:'remove/remove-markup~"docbook4"' ...
 </programlisting>
 Now the hook specification is <literal>remove/remove-markup~"docbook4"</literal>. Note that outer single quotes in the command line are necessary, as otherwise the shell would strip internal double quotes, which are here integral part of hook specification. <literal>remove-markup</literal> is actually a <emphasis>hook factory</emphasis>, which produces a hook based on the parameters given after the tilde (<literal>~</literal>) character. Here <literal>"docbook4"</literal> is that parameter; why must it be quoted? Because the part after the tilde is passed as argument list to a Python function, and <literal>"docbook4"</literal> must be of string type, which is in Python denoted by quotes. For a hook factory <literal>foo/bar</literal> which would take a string and a number, the hook specification would be <literal>foo/bar~"qwyx",5</literal>. Sometimes a hook factory has default values for some or all of its arguments; in the latter case, if the defaults are sufficient, the part after the tilde in the hook specification can be left empty (e.g. <literal>foo/bar~</literal>).</para>
 
 <para>Hooks can be language- and project-dependent. Suppose that in your language the letters are sometimes accented, but the accents should be ignored on spell-checking. Then Pology may contain a hook which strips accents from text in your language. If your language code is <literal>ll</literal>, and the hook is <literal>remove-accents</literal> in (language-specific) module <literal>remove</literal>, you could check spelling while ignoring accents using the <link linkend="sv-find-messages">the <command>check-spell-ec</command> sieve</link>:
 <programlisting language="bash">
 $ posieve check-spell-ec -s filter:'ll:remove/remove-accents' ...
 </programlisting>
 The hook specification now also contains the language code separated by colon, as <literal>ll:...</literal>. If the hook is project-specific instead, it is prefixed with <literal>pp%...</literal>, where <literal>pp</literal> is the project identifier and percent sign the separator. If the hook is both language- and project-specific, then the specification is <literal>ll:pp%...</literal> or <literal>pp%ll:...</literal>.</para>
 
 <sect2 id="sec-cmhooktypes">
 <title>Hook Types</title>
 
 <para>In places where a hook can be inserted, it is convenient to succinctly state which types of hooks are acceptable. Hook types are therefore coded with letter-number-letter combinations. The first letter can be F, V, or S, standing for filtering, validation, or side-effect hook, in that order. Filtering hooks modify their input, validation hooks report problems in input in a way understood by their clients, while side-effect hooks can do anything except modifying the input. The number after the first letter describes the composition of input, which can be pure text, PO message, PO header, etc. and their combinations. The final letter indicates the semantics of the input, like whether the input text is supposed to be the original (<varname>msgid</varname>) or the translation (<varname>msgstr</varname>) or can be any of them.</para>
 
 <para>The following hooks types are currently defined (the hook type is followed by the expected input in parenthesis):
 <variablelist>
 
 <varlistentry>
 <term>F1A (text)</term>
 <listitem>
 <para>Modifies the input text.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term>V1A (text)</term>
 <listitem>
 <para>Validates the input text.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term>S1A (text)</term>
 <listitem>
 <para>Side-effects based on the input text.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term>F3A (text, message, file)</term>
 <listitem>
 <para>Modifies the input text, which is one of the strings in the given PO message, which belongs to the given PO file. The difference between F1A and F3A hooks is that an F1A hook can process text based only on the text itself, while an F3A hook can process text by taking into account the information elsewhere in the PO message (e.g. in comments) and the PO file (e.g. in header). This holds for all *1* and *3* hook types.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term>V3A (text, message, file)</term>
 <listitem>
 <para>Validates the input text, which is one of the strings in the given PO message, which belongs to the given PO file.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term>S3A (text, message, file)</term>
 <listitem>
 <para>Side-effects based on the input text, which is one of the strings in the given PO message, which belongs to the given PO file.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term>F3B (original, message, file)</term>
 <listitem>
 <para>Modifies the input text, which is the <varname>msgid</varname> (or <varname>msgid_plural</varname>) string in the given PO message, which belongs to the given PO file. The difference between F3A and F3B hooks is that the input text of an F3B hook is expected to be precisely the original string in the message, while giving anything else will lead to undefined results. This holds for all *3A, *3B, *3C hook types.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term>V3B (original, message, file)</term>
 <listitem>
 <para>Validates the input text, which is the <varname>msgid</varname> (or <varname>msgid_plural</varname>) string in the given PO message, which belongs to the given PO file.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term>S3B (original, message, file)</term>
 <listitem>
 <para>Side-effects based on the input text, which is the <varname>msgid</varname> (or <varname>msgid_plural</varname>) string in the given PO message, which belongs to the given PO file.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term>F3C (translation, message, file)</term>
 <listitem>
 <para>Modifies the input text, which is one of the <varname>msgstr</varname> strings in the given PO message, which belongs to the given PO file.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term>V3C (translation, message, file)</term>
 <listitem>
 <para>Validates the input text, which is one of the <varname>msgstr</varname> strings in the given PO message, which belongs to the given PO file.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term>S3C (translation, message, file)</term>
 <listitem>
 <para>Side-effects based on the input text, which is one of the <varname>msgstr</varname> strings in the given PO message, which belongs to the given PO file.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term>F4A (message, file)</term>
 <listitem>
 <para>Modifies the input PO message, which belongs to the given PO file. The difference between F4A and F3A hooks is that an F3A hook can modify only the given string in the message, while an F4A hook can modify any number of strings, comments, etc. in the message. This holds for all *3* and *4* hook types.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term>V4A (message, file)</term>
 <listitem>
 <para>Validates the input PO message, which belongs to the given PO file.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term>S4A (message, file)</term>
 <listitem>
 <para>Side-effects based on the input PO message, which belongs to the given PO file.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term>F4B (header, file)</term>
 <listitem>
 <para>Modifies the input PO header, which belongs to the given PO file.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term>V4B (header, file)</term>
 <listitem>
 <para>Validates the input PO header, which belongs to the given PO file.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term>S4B (header, file)</term>
 <listitem>
 <para>Side-effects based on the input PO header, which belongs to the given PO file.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term>F5A (file)</term>
 <listitem>
 <para>Modifies the input PO file. As opposed to F1* and F3* hooks, which can modify only elements within PO messages, F5* hooks can also add, remove, and change positions of messages within the PO file.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term>V5A (file)</term>
 <listitem>
 <para>Validates the input PO file. As opposed to V1* and V3* hooks, which report only problems confined to PO messages, V5* hooks can also report problems due to relation between several PO messages each of which is valid in itself.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term>S5A (file)</term>
 <listitem>
 <para>Side-effects based on the input PO file.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term>F6A (any file)</term>
 <listitem>
 <para>Modifies the input file, whether in PO or another format, on the level of pure text lines. This is unlike F5A hooks which operate on the level of entries in the PO file; F6A hooks are also typically limited to certain types of files, perhaps even only PO files. This holds for all *6* hook types.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term>V6A (raw file)</term>
 <listitem>
 <para>Validates the input file.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term>S6A (raw file)</term>
 <listitem>
 <para>Side-effects based on the input file.</para>
 </listitem>
 </varlistentry>
 
 </variablelist>
 </para>
 
 </sect2>
 
 <sect2 id="sec-cminthooks">
 <title>List of Internal Hooks</title>
 
 <para>Pology does not establish strict separation between users and programmers, but presents a continuum between pure use and pure programming, so that users can engage according to their needs and abilities. Hooks, in particular, occupy the middle of this range. On the one hand side, they can be used even from command line; on the other hand side, they are actually Python functions, and hook specifications (in command line and elsewhere) sometimes require Python argument lists (the part after the tilde). This makes it hard both to list all available hooks<footnote>
 <para>For example, any Python function in Pology that takes one string and returns the modified version of that string can be considered an F1A hook!</para>
 </footnote>, and to decide where and how to document them, in the user manual or in the library programming interface (API) documentation. Therefore, the following will be done. Here, in the user manual, only functions written specifically to be used as hooks will be listed (sometimes grouped by similarity), with their types and short descriptions. To that the link to the complete hook description in the API documentation will be added.<footnote>
 <para>In the API documentation, the very first line of the function description will show if the function is a direct hook or a hook factory, the function header will list the inputs for a direct hook (which conform to the declared hook type) or the factory parameters for a hook factory, and the rest of the description will explain the operation of the hook and the meaning of factory parameters.</para>
 </footnote></para>
 
 <sect3 id="sec-cmghooks">
 <title>General Hooks</title>
 
 <para>
 <variablelist>
 
 <varlistentry id="hk-bpatterns-bad-patterns">
 <term><ulink url="&ap;bpatterns&am;bad_patterns"><literal>bpatterns/bad-patterns</literal></ulink> (S3A)</term>
 <term><ulink url="&ap;bpatterns&am;bad_patterns_msg"><literal>bpatterns/bad-patterns-msg</literal></ulink> (S4A)</term>
 <term><ulink url="&ap;bpatterns&am;bad_patterns_msg_sp"><literal>bpatterns/bad-patterns-msg-sp</literal></ulink> (V4A)</term>
 <listitem>
 <para>Detects unwanted patterns in text, by regular expression matching. Patterns can be specified either as direct arguments, or listed in file given as argument.</para>
 
 <caution><para>This hook is deprecated. Use <link linkend="sec-lgrules">validation rules</link> instead, which are much a richer method of defining and checking for problems.</para></caution>
 </listitem>
 </varlistentry>
 
 <varlistentry id="hk-gtxtools-msgfilter">
 <term><ulink url="&ap;gtxtools&am;msgfilter"><literal>gtxtools/msgfilter</literal></ulink> (F6A)</term>
 <listitem>
 <para>Pipes the PO file through Gettext's <command>msgfilter(1)</command>. The filter argument and options to <command>msgfilter</command> can be specified as parameters to hook factory. (May be used to wrap the PO file canonically, as Pology does not produce exactly the same wrapping as Gettext tools.)</para>
 </listitem>
 </varlistentry>
 
 <varlistentry id="hk-gtxtools-msgfmt">
 <term><ulink url="&ap;gtxtools&am;msgfmt"><literal>gtxtools/msgfmt</literal></ulink> (S6A)</term>
 <listitem>
 <para>Pipes the PO file through Gettext's <command>msgfmt(1)</command>, discarding output and reporting any errors as warnings. Useful for hard check of the PO file syntax, and extended checks performed when <command>msgfmt</command> is run with <option>--check</option> option.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry id="hk-markup-check-xml">
 <term><ulink url="&ap;markup&am;check_xml"><literal>markup/check-xml</literal></ulink> (S3C)</term>
 <term><ulink url="&ap;markup&am;check_xml_sp"><literal>markup/check-xml-sp</literal></ulink> (V3C)</term>
 <listitem>
 <para>Checks whether general XML markup in translation is well-formed, and possibly also whether entities are defined. Checks can be performed either only when the original text itself is valid or unconditionally.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry id="hk-markup-check-xml-spec">
 <term><ulink url="&ap;markup&am;check_docbook4"><literal>markup/check-docbook4</literal></ulink> (S3C)</term>
 <term><ulink url="&ap;markup&am;check_docbook4_sp"><literal>markup/check-docbook4-sp</literal></ulink> (V3C)</term>
 <term><ulink url="&ap;markup&am;check_docbook4_msg"><literal>markup/check-docbook4-msg</literal></ulink> (V4A)</term>
 <term><ulink url="&ap;markup&am;check_html"><literal>markup/check-html</literal></ulink> (S3C)</term>
 <term><ulink url="&ap;markup&am;check_html_sp"><literal>markup/check-html-sp</literal></ulink> (V3C)</term>
 <term><ulink url="&ap;markup&am;check_qtrich"><literal>markup/check-qtrich</literal></ulink> (S3C)</term>
 <term><ulink url="&ap;markup&am;check_qtrich_sp"><literal>markup/check-qtrich-sp</literal></ulink> (V3C)</term>
 <term><ulink url="&ap;markup&am;check_kde4"><literal>markup/check-kde4</literal></ulink> (S3C)</term>
 <term><ulink url="&ap;markup&am;check_kde4_sp"><literal>markup/check-kde4-sp</literal></ulink> (V3C)</term>
 <term><ulink url="&ap;markup&am;check_pango"><literal>markup/check-pango</literal></ulink> (S3C)</term>
 <term><ulink url="&ap;markup&am;check_pango_sp"><literal>markup/check-pango-sp</literal></ulink> (V3C)</term>
 <listitem>
 <para>Specializations of <link linkend="hk-markup-check-xml"><literal>markup/check-xml</literal></link> hook for various XML formats. Aside from well-formedness, these hooks can also check whether used tags really exist in the format, whether tags are properly nested, etc. (Full conformance to DTD or schema cannot be checked due to chunking into messages.)</para>
 </listitem>
 </varlistentry>
 
 <varlistentry id="hk-markup-check-xmlents">
 <term><ulink url="&ap;markup&am;check_xmlents"><literal>markup/check-xmlents</literal></ulink> (S3C)</term>
 <term><ulink url="&ap;markup&am;check_xmlents_sp"><literal>markup/check-xmlents-sp</literal></ulink> (V3C)</term>
 <listitem>
 <para>Checks whether XML-like entities (<literal>&amp;foo;</literal>) are defined. This can be used when the markup is not trully XML-like but it uses XML-like entities, or simply to have separate checking of tagging (by <link linkend="hk-markup-check-xml-spec"><literal>markup/check-xml-*</literal></link> hooks) and entities for convenience.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry id="hk-noop">
 <term><ulink url="&ap;noop&am;text"><literal>noop/text</literal></ulink> (F1A)</term>
 <term><ulink url="&ap;noop&am;textm"><literal>noop/textm</literal></ulink> (F3A)</term>
 <term><ulink url="&ap;noop&am;msg"><literal>noop/msg</literal></ulink> (F4A)</term>
 <term><ulink url="&ap;noop&am;hdr"><literal>noop/hdr</literal></ulink> (F4B)</term>
 <term><ulink url="&ap;noop&am;cat"><literal>noop/cat</literal></ulink> (F5A)</term>
 <term><ulink url="&ap;noop&am;path"><literal>noop/path</literal></ulink> (F6A)</term>
 <listitem>
 <para>Filtering hooks that do nothing ("no-operation"). These are useful in contexts where a filtering hook is required, but input should not be really modified.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry id="hk-normalize-demangle-srcrefs">
 <term><ulink url="&ap;normalize&am;demangle_srcrefs"><literal>normalize/demangle-srcrefs</literal></ulink> (F4A)</term>
 <listitem>
 <para>In some message extraction scenarios, the source references end up pointing to dummy files which existed only during the extraction, but true source references can still be reconstructed (based on dummy file names or extracted comments). This hook will reconstruct true source references and replace dummy references with them.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry id="hk-normalize-uniq-source">
 <term><ulink url="&ap;normalize&am;uniq_source"><literal>normalize/uniq-source</literal></ulink> (F4A)</term>
 <listitem>
 <para>Sometimes source references in PO message end up doubled (e.g. one prefixed with <filename>./</filename> and the other not) due to perculiarities of the extraction process. This hook will make source references unique.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry id="hk-normalize-uniq-auto-comment">
 <term><ulink url="&ap;normalize&am;uniq_auto_comment"><literal>normalize/uniq-auto-comment</literal></ulink> (F4A)</term>
 <listitem>
 <para>When extracted comments are automatically added to messages by the extraction tool, if the message is repeated in several source files it may end up containing multiple equal extracted comments. This hook can be used to make extracted comments unique (either all or those matching some criteria).</para>
 </listitem>
 </varlistentry>
 
 <varlistentry id="hk-normalize-canonical-header">
 <term><ulink url="&ap;normalize&am;canonical_header"><literal>normalize/canonical-header</literal></ulink> (F4B)</term>
 <listitem>
 <para>Rearranges content of the PO header into canonical form. For example, translator comments will be sorted according to years of contribution, any repeated translator comments will be merged, etc.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry id="hk-remove-remove-accel">
 <term><ulink url="&ap;remove&am;remove_accel_text"><literal>remove/remove-accel-text</literal></ulink> (F3A)</term>
 <term><ulink url="&ap;remove&am;remove_accel_text_greedy"><literal>remove/remove-accel-text-greedy</literal></ulink> (F3A)</term>
 <term><ulink url="&ap;remove&am;remove_accel_msg"><literal>remove/remove-accel-msg</literal></ulink> (F4A)</term>
 <term><ulink url="&ap;remove&am;remove_accel_msg_greedy"><literal>remove/remove-accel-msg-greedy</literal></ulink> ()</term>
 <listitem>
 <para>Removes accelerator marker from one or all strings in the message. They will check if the PO file <link linkend="hdr-x-accelerator-marker">specifies the accelerator marker</link>; if not, non-greedy variants will do nothing, while greedy variants will remove everything that is frequently used as accelerator marker.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry id="hk-remove-remove-markup">
 <term><ulink url="&ap;remove&am;remove_markup_text"><literal>remove/remove-markup-text</literal></ulink> (F3A)</term>
 <term><ulink url="&ap;remove&am;remove_markup_msg"><literal>remove/remove-markup-msg</literal></ulink> (F4A)</term>
 <listitem>
 <para>Converts markup (e.g. XML tags) in one or all strings in the message to plain text. The PO file will be asked for <link linkend="hdr-x-text-markup">the expected markup types in text</link>; if no markup type is specified, these hooks will do nothing.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry id="hk-remove-remove-fmtdirs">
 <term><ulink url="&ap;remove&am;remove_fmtdirs_text"><literal>remove/remove-fmtdirs-text</literal></ulink> (F3A)</term>
 <term><ulink url="&ap;remove&am;remove_fmtdirs_text_tick"><literal>remove/remove-fmtdirs-text-tick</literal></ulink> (F3A)</term>
 <term><ulink url="&ap;remove&am;remove_fmtdirs_msg"><literal>remove/remove-fmtdirs-msg</literal></ulink> (F4A)</term>
 <term><ulink url="&ap;remove&am;remove_fmtdirs_msg_tick"><literal>remove/remove-fmtdirs-msg-tick</literal></ulink> (F4A)</term>
 <listitem>
 <para>Removes <link linkend="sec-poformdir">format directives</link>
 in one or all strings in the message, or replaces them with a fixed placeholder. The type of format directives is determined by <literal>*-format</literal> message flags.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry id="hk-remove-remove-literals">
 <term><ulink url="&ap;remove&am;remove_literals_text"><literal>remove/remove-literals-text</literal></ulink> (F3A)</term>
 <term><ulink url="&ap;remove&am;remove_literals_text_tick"><literal>remove/remove-literals-text-tick</literal></ulink> (F3A)</term>
 <term><ulink url="&ap;remove&am;remove_literals_msg"><literal>remove/remove-literals-msg</literal></ulink> (F4A)</term>
 <term><ulink url="&ap;remove&am;remove_literals_msg_tick"><literal>remove/remove-literals-msg-tick</literal></ulink> (F4A)</term>
 <listitem>
 <para>Removes "literal" segments from one or all strings in the message, or replaces them wih a fixed placeholder. Literal segments are those which are used as computer input somewhere along the line, such as URLs, email addresses, command line options, etc. and therefore generally do not conform to human language rules. Translator can also explicitly declare literal segments, by adding a special translator comment.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry id="hk-remove-remove-marlits">
 <term><ulink url="&ap;remove&am;remove_marlits_text"><literal>remove/remove-marlits-text</literal></ulink> (F3A)</term>
 <term><ulink url="&ap;remove&am;remove_marlits_msg"><literal>remove/remove-marlits-msg</literal></ulink> (F4A)</term>
 <listitem>
 <para><link linkend="hk-remove-remove-literals"><literal>remove/remove-literals-*</literal></link> hooks can positively determine only certain types of literals based on the text alone. If the text contains semantic markup, such as Docbook, literal segments can also be determined based on tags, and these hooks will remove both such tags and their text. The markup type will be taken <link linkend="hdr-x-text-markup">from the PO file</link>. (When these hooks are used, <literal>remove/remove-literals-*</literal> is not needed.)</para>
 </listitem>
 </varlistentry>
 
 <varlistentry id="hk-remove-rewrite-msgid">
 <term><ulink url="&ap;remove&am;rewrite_msgid"><literal>remove/rewrite-msgid</literal></ulink> (F4A)</term>
 <listitem>
 <para><link linkend="sec-lgrules">Checks are sometimes defined</link> such that something is first looked up in the original text, and if it is found, something is expected in the translation. No matter how well written these checks are, the original text will sometimes be a bit out of the ordinary, and the check will fail the translation although everything is fine. This can usually be corrected by the translator manually adding a directive, in a special translator comment, to "rewrite" the problematic part of the original before the check is applied.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry id="hk-remove-rewrite-inverse">
 <term><ulink url="&ap;remove&am;rewrite_inverse"><literal>remove/rewrite-inverse</literal></ulink> (F4A)</term>
 <listitem>
 <para>The original text in the message needs to be modified for the same reasons as described in <link linkend="hk-remove-rewrite-msgid"><literal>remove/rewrite-msgid</literal></link>, but it is actually easiest to replace the original text entirely with the original text from another message sharing the same translation (i.e. by "inverse" pairing of messages over translation).</para>
 </listitem>
 </varlistentry>
 
 <varlistentry id="hk-remove-remove-paired-ents">
 <term><ulink url="&ap;remove&am;remove_paired_ents"><literal>remove/remove-paired-ents</literal></ulink> (F4A)</term>
 <term><ulink url="&ap;remove&am;remove_paired_ents_tick"><literal>remove/remove-paired-ents-tick</literal></ulink> (F4A)</term>
 <listitem>
 <para>Removes all XML-like entities (<literal>&amp;foo;</literal>) from the original text, and all XML-like entities from the translation that were encountered in the original. This may be useful prior to markup validity checks, when the list of defined entities cannot be provided.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry id="hk-spell">
 <term><ulink url="&ap;spell&am;check_spell"><literal>spell/check-spell</literal></ulink> (S3A)</term>
 <term><ulink url="&ap;spell&am;check_spell_sp"><literal>spell/check-spell-sp</literal></ulink> (V3A)</term>
 <listitem>
 <para>Spell-checking hooks for Aspell, as one element of <link linkend="sec-lgspell">Pology's spell-checking functionality</link>.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry id="hk-spell-ec">
 <term><ulink url="&ap;spell&am;check_spell_ec"><literal>spell/check-spell-ec</literal></ulink> (S3A)</term>
 <term><ulink url="&ap;spell&am;check_spell_ec_sp"><literal>spell/check-spell-ec-sp</literal></ulink> (V3A)</term>
 <listitem>
 <para>Spell-checking hooks for various spell checkers through the Enchant wrapper, as one element of <link linkend="sec-lgspell">Pology's spell-checking functionality</link>.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry id="hk-uiref-resolve-ui">
 <term><ulink url="&ap;uiref&am;resolve_ui"><literal>uiref/resolve-ui</literal></ulink> (F3C)</term>
 <term><ulink url="&ap;uiref&am;resolve_ui_docbook4"><literal>uiref/resolve-ui-docbook4</literal></ulink> (F3C)</term>
 <term><ulink url="&ap;uiref&am;resolve_ui_kde4"><literal>uiref/resolve-ui-kde4</literal></ulink> (F3C)</term>
 <listitem>
 <para>When translating program documentation, using these hooks it is possible to leave UI references (button labels, menu items, etc.) untranslated and let them be <link linkend="sec-lguirefs">automatically inserted into translation later on</link>. The basic hook requires UI references to be manually wrapped in translation in order to be detected, while specialized versions will also use semantic markup for detection (e.g. <literal>&lt;guilabel&gt;</literal> element in Docbook).</para>
 </listitem>
 </varlistentry>
 
 <varlistentry id="hk-uiref-check-ui">
 <term><ulink url="&ap;uiref&am;check_ui"><literal>uiref/check-ui</literal></ulink> (V3C)</term>
 <term><ulink url="&ap;uiref&am;check_ui_docbook4"><literal>uiref/check-ui-docbook4</literal></ulink> (V3C)</term>
 <term><ulink url="&ap;uiref&am;check_ui_kde4"><literal>uiref/check-ui-kde4</literal></ulink> (V3C)</term>
 <listitem>
 <para>While <link linkend="hk-uiref-resolve-ui"><literal>uiref/resolve-ui</literal></link> hooks will complain when they cannot find a translation for a UI reference, when checking the overall validity of translation it is more convenient to use specialized check-only hooks which will not modify the PO file on succesfully resolved UI references.</para>
 </listitem>
 </varlistentry>
 
 </variablelist>
 </para>
 
 </sect3>
 
 <sect3 id="sec-cmlshooks">
 <title>Language-Specific Hooks</title>
 
 <para>
 <variablelist>
 
 <varlistentry id="hk-lang-ja-katakana">
 <term><ulink url="&ap;lang.ja.katakana&am;katakana"><literal>ja:katakana</literal></ulink> (F1A)</term>
 <listitem>
 <para>Removes everything but Katakana words from Japanese text, and separates retained words with spaces. (Used as filter prior to spell-checking words in Katakana.)</para>
 </listitem>
 </varlistentry>
 
 <varlistentry id="hk-lang-nn-exclusion-inofficial-forms">
 <term><ulink url="&ap;lang.nn.exclusion&am;inofficial_forms"><literal>nn:exclusion/inofficial-forms</literal></ulink> (V3C)</term>
 <listitem>
 <para>Checks if there are any inofficial word forms in Norwegian Nynorsk translation.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry id="hk-lang-sr-accents-resolve-agraphs">
 <term><ulink url="&ap;lang.sr.accents&am;resolve_agraphs"><literal>sr:accents/resolve-agraphs</literal></ulink> (F1A)</term>
 <listitem>
 <para>Converts "accent graphs" to proper accented letters in Serbian Cyrillic text (e.g. <literal>^а</literal> becomes <literal>а̂</literal>).</para>
 </listitem>
 </varlistentry>
 
 <varlistentry id="hk-lang-sr-accents-remove-accents">
 <term><ulink url="&ap;lang.sr.accents&am;remove_accents"><literal>sr:accents/remove-accents</literal></ulink> (F1A)</term>
 <listitem>
 <para>Replaces accented letters in Serbian Cyrillic text with their non-accented counterparts. (Useful as filter prior to spell-checking.)</para>
 </listitem>
 </varlistentry>
 
 <varlistentry id="hk-lang-sr-limit-charset">
 <term><ulink url="&ap;lang.sr.charsets&am;limit_to_isocyr"><literal>sr:charsets/limit-to-isocyr</literal></ulink> (F1A)</term>
 <term><ulink url="&ap;lang.sr.charsets&am;limit_to_isolat"><literal>sr:charsets/limit-to-isolat</literal></ulink> (F1A)</term>
 <listitem>
 <para>In situations where it is necessary to use an 8-bit encoding instead of Unicode for Serbian text, these hooks can be used to constrain characters in text to only those representable by the target 8-bit encoding.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry id="hk-lang-sr-checks-naked-latin">
 <term><ulink url="&ap;lang.sr.checks&am;naked_latin"><literal>sr:checks/naked-latin</literal></ulink> (V3C)</term>
 <term><ulink url="&ap;lang.sr.checks&am;naked_latin_origui"><literal>sr:checks/naked-latin-origui</literal></ulink> (V3C)</term>
 <term><ulink url="&ap;lang.sr.checks&am;naked_latin_se"><literal>sr:checks/naked-latin-se</literal></ulink> (S3C)</term>
 <term><ulink url="&ap;lang.sr.checks&am;naked_latin_origui_se"><literal>sr:checks/naked-latin-origui-se</literal></ulink> (S3C)</term>
 <listitem>
 <para>In translations into Serbian using Cyrillic script, ordinary segments in Latin script may indicate error or omission in translation. These hooks will look for such stray Latin segments, while ignoring recognizable literal segments such as URLs, commands, options, etc.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry id="hk-lang-sr-nobr-to-nobr-hyphens">
 <term><ulink url="&ap;lang.sr.nobr.to_nobr_hyphens&am;"><literal>sr:nobr/to-nobr-hyphens</literal></ulink> (F1A)</term>
 <listitem>
 <para>The ordinary hyphen (-) is normally treated as a character on which the text can be split into the next line. In Serbian texts, hyphens are sometimes used to attach case endings to nouns (especially acronyms), which should not be split into the next line. This hooks guesses such positions and replaces the ordinary hyphen with no-break hyphen.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry id="hk-lang-sr-reduce">
 <term><ulink url="&ap;lang.sr.reduce&am;words_ec"><literal>sr:reduce/words-ec</literal></ulink> (F1A)</term>
 <term><ulink url="&ap;lang.sr.reduce&am;words_ec_lw"><literal>sr:reduce/words-ec-lw</literal></ulink> (F1A)</term>
 <term><ulink url="&ap;lang.sr.reduce&am;words_ic"><literal>sr:reduce/words-ic</literal></ulink> (F1A)</term>
 <term><ulink url="&ap;lang.sr.reduce&am;words_ic_lw"><literal>sr:reduce/words-ic-lw</literal></ulink> (F1A)</term>
 <term><ulink url="&ap;lang.sr.reduce&am;words_ic_lw_dlc"><literal>sr:reduce/words-ic-lw-dlc</literal></ulink> (F1A)</term>
 <listitem>
 <para>Various reductions of Serbian text to a subset of words of certain type, possibly rearranged in a particular way.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry id="hk-lang-sr-trapres-froments">
 <term><ulink url="&ap;lang.sr.trapres&am;froments"><literal>sr:trapres/froments</literal></ulink> (F3C)</term>
 <term><ulink url="&ap;lang.sr.trapres&am;froments_t1"><literal>sr:trapres/froments-t1</literal></ulink> (F3C)</term>
 <term><ulink url="&ap;lang.sr.trapres&am;froments_t1db"><literal>sr:trapres/froments-t1db</literal></ulink> (F3C)</term>
 <listitem>
 <para>Hooks which resolve grammatical inserts in form of XML entities in Serbian text, based on the "trapnakron" contained within Pology. See the documentation in Serbian section for details.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry id="hk-lang-sr-uiref">
 <term><ulink url="&ap;lang.sr.uiref&am;"><literal>sr:uiref/mod_entities</literal></ulink> (F1A)</term>
 <listitem>
 <para>When UI references are <link linkend="hk-uiref-resolve-ui">automatically resolved</link> in documentation, and the UI texts may contain <link linkend="hk-lang-sr-trapres-froments">grammatical inserts in form of XML entities</link>, these inserts may need to be slightly modified to keep the documentation structure valid.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry id="hk-lang-sr-wconv">
 <term><ulink url="&ap;lang.sr.wconv&am;ctol"><literal>sr:wconv/ctol</literal></ulink> (F1A)</term>
 <term><ulink url="&ap;lang.sr.wconv&am;cltoa"><literal>sr:wconv/cltoa</literal></ulink> (F1A)</term>
 <term>and many more</term>
 <listitem>
 <para>Hooks for various transliterations and hybridizations of Serbian text, by script (Cyrillic, Latin) and dialect (Ekavian, Ijekavian). See the documentation in Serbian section for details.</para>
 </listitem>
 </varlistentry>
 
 </variablelist>
 </para>
 
 </sect3>
 
 <sect3 id="sec-cmpshooks">
 <title>Project-Specific Hooks</title>
 
 <para>
 <variablelist>
 
 <varlistentry id="hk-proj-kde-header-equip-header">
 <term><ulink url="&ap;proj.kde.header&am;equip_header"><literal>kde%header/equip-header</literal></ulink> (F4B)</term>
 <listitem>
 <para>Adds assorted header fields to PO files within the KDE Translation Project, with values based on their name and position in the repository tree, so that Pology and other tools are better informed how to process them.</para>
 </listitem>
 </varlistentry>
 
 </variablelist>
 </para>
 
 </sect3>
 
 </sect2>
 
 <sect2 id="sec-cmexthooks">
 <title>Using External Hooks</title>
 
 <para>[Not implemented yet.]</para>
 
 <para>See <xref linkend="sec-prhooks"/> for instructions on how to write and contribute hooks.</para>
 
 </sect2>
 
 </sect1>
 
 <!-- ======================================== -->
 <sect1 id="sec-cmskipcheck">
 <title>Skipping and Selecting Checks</title>
 
 <para>With all the different heuristic checks and rules that Pology can apply, false positives -- messages proclaimed invalid when they are actually valid -- are inevitable. False positivies are <emphasis>very</emphasis> inconvenient in serious automatic quality control effort. They make it harder for translators to spot real problems, which in turn demotivates them to apply automatic checks at all. If there is one or few dedicated persons in the translation team to tweak and apply automatic checks, they would be particularly hard-hit with this negative feedback. False positives can reduce automatic quality control from a strong normative element in the workflow, to merely advisory "run-if-you-have-the-time" extra.</para>
 
 <para>For this reason, most checks in Pology provide a way for them to be disabled on certain messages, files, or the processing batch, such that it is possible to methodically cancel false positives. From the other side, it is usually possible to run one or few checks on their own, in order to be easier to define and debug. Each checking tool and element documents such functionality, and in the following only some general patterns are described.</para>
 
 <para>The simplest method to disable or enable some checks is "dynamically", for single validation run, through an option to the tool which is being run. For example, <link linkend="sv-check-rules">the <command>check-rules</command> sieve</link> provides several parameters to select and deselect validation rules which are to be applied. The important point here is that checks in Pology usualy have some sort of a unique identifier, a keyword, by which they can be referred to.</para>
 
 <para>"Static" methods to disable or enable checks are those where the instruction is written down somewhere, in a specific format, and automatically taken into account by the validation tool in subsequent runs. There may be several static methods to disable a certain check, differing in their reach: a group of PO files, single PO file, single message, or even a part of the text in the message. Within one PO file, the following methods are common:
 <itemizedlist>
 
 <listitem>
 <para>The PO header is a natural place to disable or enable checks for the complete PO file, by adding a custom <literal>X-</literal> header field.</para>
 </listitem>
 
 <listitem>
 <para>On the single message level, the only place where it is possible to add a manual processing instruction is a <link linkend="sec-pomancmnt">translator comment</link>. This is because if it would put anywhere else (e.g. as extracted comment or a flag), it would be removed on subsequent merging with template. These instructions are usualy kept simple, like this:
 <programlisting language="po">
 # <replaceable>some-instruction</replaceable>: <replaceable>arguments</replaceable>
 #: ...
 msgid "..."
 msgstr "..."
 </programlisting>
 Instructions are always composed of two or more words, separated by hyphens, ended by colon, and followed by an arbitrary argument string (e.g. a list of identifiers of checks to skip on this message). This makes it sufficiently unlikely that another, free-form translator comment will be accidentally interpreted as a known instruction.<footnote>
 <para>Especially considering that free-form translator comments are more usually written in the language of the translation.</para>
 </footnote></para>
 </listitem>
 
 <listitem>
 <para id="p-trflag">A special type of translator comment with processing instructions is a comment of the following form:
 <programlisting language="po">
 # |, <replaceable>flag1</replaceable>, <replaceable>flag2</replaceable>, ...
 </programlisting>
 This is a "translator flag" comment, which is used to set processing instructions too simple to occupy one whole comment line (e.g. those of the switch type, never needing arguments). It starts with <literal>|,</literal>, and continues with comma-separated list of flag-like keywords.</para>
 </listitem>
 
 </itemizedlist>
 </para>
 
 </sect1>
 
 </chapter>