Warning, /sdk/pology/doc/user/sieving.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-sieve">
 
 <title>Sieving</title>
 
 <para>Translator may want to apply batch-type operations to every message in a single PO file or in collection of PO files, such as searching and replacing text, computing statistics, or validating. However, batch-processing tools for general plain text (<command>grep</command>, <command>sed</command>, <command>awk</command>, etc.) are not very well suited to processing PO files. For example, when looking for a particular word, a generic search tool will not see it if it contains an <link linkend="sec-poaccel">accelerator marker</link>; or, if looking for a two-word phrase, a generic tool will miss it if it is <link linkend="sec-powrap">wrapped</link>. Therefore many tools tailored specifically for batch-processing messages in PO files have been developed, such as those bundled with <ulink url="http://www.gnu.org/software/gettext/">Gettext</ulink> (<command>msggrep</command>, <command>msgfilter</command>, <command>msgattrib</command>...), or from <ulink url="http://translate.sourceforge.net/wiki/toolkit/index">Translate Toolkit</ulink> (<command>pocount</command>, <command>pogrep</command>, <command>pofilter</command>...).</para>
 
 <para>Pology also provides a per-message batch-processing tool, the <command>posieve</command>. What was the need for it, given the myriad of other previously available and powerful tools? In accordance with philosophy of Pology, <command>posieve</command> goes deeper than these other tools. <command>posieve</command> makes easy that which is possible but awkward by combining generic command line tools. <command>posieve</command> is modular from the ground up, such that it is never a design problem to add new functionality to it, even when it is of narrow applicability. Users who know some Python can even write own "plugins" for it. Several processing modules can be applied in a single run of <command>posieve</command>, possibly affecting each other, in ways not possible by generic shell piping and not requiring temporary intermediate files.</para>
 
 <!-- ======================================== -->
 <sect1 id="sec-svbasics">
 <title>Basic Usage of <command>posieve</command></title>
 
 <para>The <command>posieve</command> script itself is actually a simple shell for applying various processing modules, called <emphasis>sieves</emphasis>, to every message in one or more PO files. Some sieves can also request to operate on the header of the PO file, which <command>posieve</command> will then feed to them. A sieve can both examine and modify messages; if any message is modified, by default the modified PO file will be written out in place. Naturally, <command>posieve</command> has a number of options, but more interestingly, each sieve can define some parameters which determine its behavior. Pology comes with many internal sieves, which do things from general to obscure (possibly language or project specific), and users can define their own sieves.</para>
 
 <para>Here is how you would run the <link linkend="sv-stats"><command>stats</command></link> sieve to collect statistics on all PO files in <filename>frobaz/</filename> directory:
 <programlisting language="bash">
 $ posieve stats frobaz/
 </programlisting>
 While PO files in <filename>frobaz/</filename> are being processed, you will see a progress bar with the current file and the number of files to process, and after some time the <command>stats</command> sive will present its findings in a table.</para>
 
 <para>The first non-option argument in the <command>posieve</command> command line is the sieve name, and then any number of directory or file paths can be specified.
 <command>posieve</command> will consider file path arguments to be PO files, and recursively search directory paths to collect all files ending with <filename>.po</filename> or <filename>.pot</filename>. If no paths are specified, PO files to process will be collected from the current working directory.</para>
 
 <para>If the sieve modifies a message and the new PO file is written out in place of the old, the user will be informed by an exclamation mark followed by the file path. An example of a sieve which modifies messages is the <link linkend="sv-tag-untranslated"><command>tag-untranslated</command></link> sieve; it adds
 the <literal>untranslated</literal> flag to every untranslated message, so that you can look them up in a plain text editor (as opposed to <link linkend="sec-poedlist">dedicated PO editor</link>):
 <programlisting language="bash">
 $ posieve tag-untranslated frobaz/
 ! frobaz/alfa.po
 ! frobaz/bravo.po
 ! frobaz/charlie.po
 Tagged 42 untranslated messages.
 </programlisting>
 <command>posieve</command> itself tracks message modifications and informs about modified PO files, whereas the final line in this example has been output by the <command>tag-untranslated</command> sieve. Sieves will frequently issue such final reports of their actions.</para>
 
 <para id="p-svparam">If a sieve defines some parameters to control its behavior, these can be issued using the <option>-s</option>. This option takes the parameter specification as the argument, which is of the form <literal><replaceable>name</replaceable>:<replaceable>value</replaceable></literal> or just <literal><replaceable>name</replaceable></literal> for switch-type parameters. More than one parameter can be issued by repeating the <option>-s</option>. For example, the <command>stats</command> sieve can be instructed to take into account only messages with at most 5 words:
 <programlisting language="bash">
 $ posieve stats -s maxwords:5 frobaz/
 </programlisting>
 to show statistics in greater detail:
 <programlisting language="bash">
 $ posieve stats -s detail frobaz/
 </programlisting>
 or to ignore a certain accelerator marker and show bar-type statistics instead of tabular:
 <programlisting language="bash">
 $ posieve stats -s accel:_ -s msgbar frobaz/
 </programlisting>
 </para>
 
 <para><command>posieve</command> lists and shows descriptions of its options by the usual <option>-h</option>/<option>--help</option> option. Help for a sieve can be requested by issuing the <option>-H</option>/<option>--help-sieves</option> while a sieve name is present in the command line. All available internal sieves with short descriptions are listed using <option>-l</option>/<option>--list-sieves</option>.</para>
 
 <para>Some sieves are language-specific, which can be seen by their names being of the form <command><replaceable>langcode</replaceable>:<replaceable>name</replaceable></command>. These sieves are primarily intendedfor use on PO files translated to indicated language, but depending on particularities, may be applicable to several more closely related languages. (A sieve which is doing language-specific things, but which is applicable to many languages, is more likely to be named as a general sieve.)</para>
 
 <para>If <link linkend="sec-cmshellcomp">shell completion</link> is active, it can be used to complete sieve names and their parameters.</para>
 
 </sect1>
 
 <!-- ======================================== -->
 <sect1 id="sec-svchains">
 <title>Sieve Chains</title>
 
 <para>It is possible to issue several sieves at once, by passing a comma-separated list of sieve names to <command>posieve</command> in place of single sieve name. This is called a <emphasis>sieve chain</emphasis>.</para>
 
 <para>At minimum, chaining sieves is a performance improving measure, since each PO file is opened (and possibly written out) only once, instead of on each sieve run. For example, you can in one run compute the statistics to see how many messages need to be update and tag all untranslated messages:
 <programlisting language="bash">
 $ posieve stats,tag-untranslated frobaz/
 ! frobaz/alfa.po
 ! frobaz/bravo.po
 ! frobaz/charlie.po
 ... (table with statistics) ...
 Tagged 42 untranslated messages.
 </programlisting>
 A message in the PO file is passed through each sieve in turn, in the order in which they are issued, before proceding to the next message. If a sieve modifies the message, the next sieve in the chain will operate on that modified version of the message. This means that the ordering of sieves in the command line is significant in general, and that it is interchangable only if the sieves in the chain are independent of each other (as in this example). Chain order also determines the order in which sieve reports are shown; if in this example the order had been <literal>tag-untranslated,stats</literal>, then first the tagged messages line would be written out, followed by the statistics table.</para>
 
 <para>Other than for performance, sieve chains are useful when messages should be modified in a particular way before a sieve gets to operate on it. A good example is when statistics is to be computed on PO files which contain old <link linkend="p-embctxt">embedded contexts</link>, where if nothing would be done, contexts would add to the word count of the original text. To avoid this, a <link linkend="sv-normctxt-sep">context normalization</link> sieve (which converts embedded contexts to <varname>msgctxt</varname>) can be chained with statistics sieve, and the <command>posieve</command> instructed not to write modifications to the PO file. If the embedded context is of the single-separator type, with separator character <literal>|</literal>, the sieve chain is:
 <programlisting language="bash">
 $ posieve --no-sync normctxt-sep,stats -s sep:'|' frobaz/
 Converted 21 separator-embedded contexts.
 ... (table with statistics) ...
 </programlisting>
 The <option>--no-sync</option> option prevents writing modified messages in the PO file on disk. Note that <literal>|</literal> as parameter value is quoted, because it would be interpreted as a shell pipe otherwise.</para>
 
 <para>Finally, some sieves can stop messages from being pushed further through the sieve chain, so they can be used as a prefilter to other sieves. The     archetypal example of this the <link linkend="sv-find-messages"><command>find-messages</command></link>, which stops non-matched messages from further sieving. For example, to include into statistics only the messages containing the word "quasar", this would be executed:
 <programlisting language="bash">
 $ posieve find-messages,stats -s msgid:quasar -s nomsg
 Found 12 messages satisfying the conditions.
 ... (table with statistics) ...
 </programlisting>
 The <option>msgid:</option> parameter specifies the word (actually, a regular expression) to be looked up in the original text, while <option>nomsg</option> parameter tells <command>find-messages</command> not to write out matched messages to standard output, which it would by default do. Note that no path was specified, meaning that all PO files in current working directory and below will be sieved.</para>
 
 <para>Examples of sieve chaining so far should have raised the following question: when several sieves are issued, to which of them are the parameters specified by <option>-s</option> options passed? The answer is that a parameter is sent to all sieves which accept parameter of that name. Continuing the previous example, if message texts can contain accelerator marker <literal>&amp;</literal>, this would be specified like this:
 <programlisting language="bash">
 $ posieve find-messages,stats -s msgid:quasar -s nomsg -s accel:'&amp;'
 </programlisting>
 <command>find-messages</command> will accept <option>accel</option> in order to also match messages like <literal>"Charybdis Q&amp;uasar"</literal>, while <command>stats</command> will use it to properly split text into words for counting them.</para>
 
 </sect1>
 
 <!-- ======================================== -->
 <sect1 id="sec-svoptions">
 <title>Command Line Options</title>
 
 <para>
 Options specific to <command>posieve</command>:
 <variablelist>
 
 <varlistentry>
 <term><option>-a</option>, <option>--announce-entry</option></term>
 <listitem>
 <para>A sieve may be buggy and crash or keep <command>posieve</command> in infinite loop on a particular PO entry (header or message). When this option is given, each PO entry will be announced before sieving it, so that you can see exactly where the problem occurs.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term><option>-b</option>, <option>--skip-obsolete</option></term>
 <listitem>
 <para>By default <command>posieve</command> will process all messages in the PO file, including the obsolete. Sometimes sieving obsolete messages is not desired, for example when running translation validation sieves. This option can then be used to skip obsolete messages.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term><option>-c</option>, <option>--msgfmt-check</option></term>
 <listitem>
 <para>For <command>posieve</command> to process the PO file, it is only necessary that basic PO syntax is valid, i.e. that <command>msgfmt</command> can compile the file. <command>msgfmt</command> also offers stricter validation mode: to have <command>posieve</command> run this stricter validation on the PO file, issue this option. Invalid files will be reported and will not be sieved.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term><option>--force-sync</option></term>
 <listitem>
 <para>When some messages in the PO file are modified, by default only those messages will be reformatted (e.g. strings wrapped as selected) when the PO file is modified on disk. This makes <command>posieve</command> friendly to version control systems. Sometimes, however, you may want that all messages are reformatted, modified or not, and then you can issue this option.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term><option>-h</option>, <option>--help</option></term>
 <listitem>
 <para>General help on <command>posieve</command>.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term><option>-H</option>, <option>--help-sieves</option></term>
 <listitem>
 <para><option>-h</option>/<option>--help</option> shows only description of <command>posieve</command> and its options, while this option shows the descriptions and available parameters of issued sieves. For example:
 <programlisting language="bash">
 $ posieve find-messages,stats -H
 </programlisting>
 would output help for <command>find-messages</command> and <command>stats</command> sieves.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term><option>--issued-params</option></term>
 <listitem>
 <para>List of all sieve parameters and their values that would be issued. Used to check <link linkend="p-svparconfcmd">the interplay of command line and configuration</link> on sieve parameters.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term><option>-l</option>, <option>--list-sieves</option></term>
 <listitem>
 <para>List of all internal sieves, with short descriptions.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term><option>--list-options</option>; <option>--list-sieve-names</option>; <option>--list-sieve-params</option></term>
 <listitem>
 <para>Simple listings of global options, internal sieve names, and parameters of issued sieves. Intended mainly for writting shell completion definitions.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term><option>-m <replaceable>OUTFILE</replaceable></option>, <option>--output-modified=<replaceable>OUTFILE</replaceable></option></term>
 <listitem>
 <para>If some PO files were modified by sieving, you may want to follow up with a command to process only those files. <command>posieve</command> will by default output the paths of modified PO files, but also other information, which makes parsing this output for modified paths ungainly. Instead, this option can be used to specify a file to which path of all modified PO files will be written to, one per line.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term><option>--no-skip</option></term>
 <listitem>
 <para>If a sieve reports an error, <command>posieve</command> normally skips the problematic message and continues sieving the rest of the PO file, if possible. This is sometimes not desired, when this option will tell <command>posieve</command> to abort with an error message in such cases.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term><option>--no-sync</option></term>
 <listitem>
 <para>All messages modified by sieves are by default written back to disk, i.e. their PO files modifed. This option prevents modification of PO files. This comes handy in two cases. One is when you want to check what effect a modifying sieve will have before actually accepting it (a "dry" run). The other case is when you use a modifying sieve as a filter for the next sieve in chain, which only needs to examine messages.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term><option>-q</option>, <option>--quiet</option></term>
 <listitem>
 <para><command>posieve</command> normally shows the progress of sieving, which can be cancelled by this option. (Sieves will still output their own lines.)</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term><option>-s <replaceable>PARAM</replaceable>[:<replaceable>VALUE</replaceable>]</option></term>
 <listitem>
 <para>The central option of <command>posieve</command>, which is used to issue parameters to sieves.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term><option>-S <replaceable>PARAM</replaceable></option></term>
 <listitem>
 <para>When a sieve parameter is issued <link linkend="p-confsvpar">through user configuration</link>, this option can be used to cancel it for one particular run.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term><option>--version</option></term>
 <listitem>
 <para>Release and copyright information on <command>posieve</command>.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term><option>-v</option>, <option>--verbose</option></term>
 <listitem>
 <para>More verbose output, where <command>posieve</command> shows the sieving modes, lists files which are being sieved, etc.</para>
 </listitem>
 </varlistentry>
 
 </variablelist>
 </para>
 
 <para>
 Options common with other Pology tools:
 <variablelist>
 
 <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
             href="stdopt-filesfrom.docbook"/>
 
 <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
             href="stdopt-incexc.docbook"/>
 
 <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
             href="stdopt-colors.docbook"/>
 
 </variablelist>
 </para>
 
 </sect1>
 
 <!-- ======================================== -->
 <sect1 id="sec-svconfig">
 <title>User Configuration</title>
 
 <para>The following <link linkend="sec-cmconfig">configuration</link> fields can be used to modify general behavior of <command>posieve</command>:
 <variablelist>
 
 <varlistentry>
 <term><literal>[posieve]/skip-on-error=[*yes|no]</literal></term>
 <listitem>
 <para>Setting to <literal>no</literal> is counterpart to <option>--no-skip</option> command line option.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term><literal>[posieve]/msgfmt-check=[yes|*no]</literal></term>
 <listitem>
 <para>Setting to <literal>yes</literal> is counterpart to <option>-c</option>/<option>--msgfmt-check</option> command line option.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term><literal>[posieve]/skip-obsolete=[yes|*no]</literal></term>
 <listitem>
 <para>Setting to <literal>yes</literal> is counterpart to <option>-b</option>/<option>--skip-obsolete</option> command line option.</para>
 </listitem>
 </varlistentry>
 
 </variablelist>
 For configuration fields that have counterpart command line options, the command line option always takes precedence if issued.</para>
 
 <para id="p-confsvpar">Configuration can also be used to issue sieve parameters, by specifying <literal>[posieve]/param-<replaceable>name</replaceable></literal> fields. For example, parameters <option>transl</option> (a switch) and <option>accel</option> (with value <literal>&amp;</literal>) are issued to all sieves that accept them by writing:
 <programlisting language="ini">
 [posieve]
 param-transl = yes
 param-accel = &amp;
 </programlisting>
 </para>
 
 <para>To issue parameters only to certain sieves, parameter name can be followed
 by a sieve list of the form <literal>/<replaceable>sieve1</replaceable>,<replaceable>sieve2</replaceable>,...</literal>; to <emphasis>prevent</emphasis> the parameter from being issued only to certain sieves, prepend <literal>~</literal> to the sieve list. For example:
 <programlisting language="ini">
 [posieve]
 param-transl/find-messages = yes  # only for find-messages
 param-accel/~stats = &amp;            # not for stats
 </programlisting>
 </para>
 
 <para>Same parameters can sometimes be repeated in the command line, when it is logically meaningfull to provide several values of that type to a sieve. However, same-name fields cannot be used in configuration to supply several values, because they override each other. Instead, a dot and a unique string (within the sequence) can be appended to the parameter name to make it a unique configuration field:
 <programlisting language="ini">
 [posieve]
 param-accel.0 = &amp;
 param-accel.1 = _
 </programlisting>
 Strings after the dot can be anything, but a sequence of numbers or letters in alphabetical order is the least confusing choice.</para>
 
 <para id="p-svparconfcmd">Sieve parameters should be issued from the configuration only as a matter of convenience, when they are almost always used in sieve runs. But occasionaly the parameter issued from the configuration is not appropriate for the given run. Instead of going to configuration and commenting the parameter out temporarily, it can be cancelled in the command line using the <option>-S</option> option (note capital S) followed by the parameter name. You can use <option>--issued-params</option> option to confirm which parameters will be issued after both the command line and the configuration have been taken into account.</para>
 
 </sect1>
 
 <!-- ======================================== -->
 <sect1 id="sec-svinternal">
 <title>Internal Sieves</title>
 
 <para>This section describes the sieves which are contained in Pology distribution and provides instruction for their use.</para>
 
 <para><!--Some sieve parameters are mandatory, i.e. they have to be issued when the sieve is run. Parameters for which this is the case will have (*) added to their header in the parameter list.--> Parameters which take a value (which are not switches) may or may not have a default value, and when they do, it will be given in square brackets (<literal>[...]</literal>) in the header.</para>
 
 <sect2 id="sv-apply-filter">
 <title><command>apply-filter</command></title>
 
 <para><command>apply-filter</command> is used to pipe translation through one or several <emphasis>hooks</emphasis> (see <xref linkend="sec-cmhooks"/>). The hooks may modify the translation, validate it, or do something else. More precisely, the following hook types are applicable:
 <itemizedlist>
 <listitem>
 <para>F1A, F3A, F3C, to modify the translation and write changes back to the PO file;</para>
 </listitem>
 <listitem>
 <para>V1A, V3A, V3C, to validate the translation, with standard validation output (highlighted spans and problem messages);</para>
 </listitem>
 <listitem>
 <para>S1A, S3A, S3C, for any side-effect processing on translation (but no modification).</para>
 </listitem>
 </itemizedlist>
 </para>
 
 <para>Parameters:
 <variablelist>
 
 <varlistentry>
 <term><option>filter:<replaceable>hookspec</replaceable></option></term>
 <listitem>
 <para>The hook specification. Can be repeated to add several hooks, which are then applied in the order of specification.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term><option>showmsg</option></term>
 <listitem>
 <para>Report every modified message to standard output. (For validation hooks, message is automatically reported if not valid.)</para>
 </listitem>
 </varlistentry>
 
 </variablelist>
 </para>
 
 </sect2>
 
 <sect2 id="sv-apply-header-filter">
 <title><command>apply-header-filter</command></title>
 
 <para><command>apply-header-filter</command> is the counterpart to <command>apply-filter</command> to operate on headers instead of messages. Here the applicable hook types are accordingly F4B, V4B, S4B.</para>
 
 <para>Parameters:
 <variablelist>
 
 <varlistentry>
 <term><option>filter:<replaceable>hookspec</replaceable></option></term>
 <listitem>
 <para>The hook specification. Can be repeated to add several hooks, which are then applied in the order of specification.</para>
 </listitem>
 </varlistentry>
 
 </variablelist>
 </para>
 
 </sect2>
 
 <sect2 id="sv-bad-patterns">
 <title><command>bad-patterns</command></title>
 
 <caution><para>This sieve is deprecated. Use <link linkend="sv-check-rules"><command>check-rules</command></link> instead, which applies Pology's <link linkend="sec-lgrules">validation rules</link>.</para></caution>
 
 <para>Sometimes it is possible to use simple pattern matching to discover things that should never appear in the text, such as common grammar or orthographical errors. <command>bad-patterns</command> can apply such patterns to translation, either as plain substring matching or <link linkend="sec-cmregex">regular expressions</link>. Patterns can be given as parameters, or more conveniently, read from files.</para>
 
 <para>Parameters:
 <variablelist>
 
 <varlistentry>
 <term><option>pattern:<replaceable>string</replaceable></option></term>
 <listitem>
 <para>The pattern to search for. Can be repeated to search for several patterns.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term><option>fromfile:<replaceable>path</replaceable></option></term>
 <listitem>
 <para>Read patterns to search for from the file. Each line contains one pattern. If line starts with <literal>#</literal>, it is treated as comment. Empty lines are ignored. Trailing and leading whitespace is removed from patterns; if it is significant, it can be given inside <literal>[...]</literal> regex operator. This parameter can be repeated to read patterns from several files.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term><option>rxmatch</option></term>
 <listitem>
 <para>By default patterns are treated as plain substrings. This parameter requests to treat patterns as regular expressions.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term><option>casesens</option></term>
 <listitem>
 <para>By default patterns are case-sensitive. This parameter make them case-insensitive.</para>
 </listitem>
 </varlistentry>
 
 </variablelist>
 </para>
 
 </sect2>
 
 <sect2 id="sv-check-docbook4">
 <title><command>check-docbook4</command></title>
 
 <para><command>check-docbook4</command> checks PO files extracted from Docbook 4.x files. Docbook is an XML format, typically used for documenting software.</para>
 
 <para>Parameters:
 <variablelist>
 
 <varlistentry>
 <term><option>showmsg</option></term>
 <listitem>
 <para>Instead of just showing the message location and problem description, also show the complete message with problematic segments higlighted.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term><option>lokalize</option></term>
 <listitem>
 <para>Open the PO file on reported messages in Lokalize. Lokalize must be already running with the project that contains the PO file opened.</para>
 </listitem>
 </varlistentry>
 
 </variablelist>
 </para>
 
 <para>Currently performed checks:
 <itemizedlist>
 
 <listitem>
 <para>Markup validity. Docbook is a complex XML format, and nothing short of full validation of XML files generated from translated PO files can show if the translation is technically valid. Therefore <command>check-docbook4</command> checks only well-formedness, whether tags are defined by Docbook, and some nesting constraints, and that on the level of single message. But this is already enough to catch great majority of usual translation errors.</para>
 
 <para>This check can be skipped on a message by adding to it the <literal>no-check-markup</literal> <link linkend="p-trflag">translator flag</link>.</para>
 </listitem>
 
 <listitem>
 <para>Message insertion placeholders. Some extractors of Docbook split out into standalone messages contextually separate units that are found in the middle of flowing paragraphs (e.g. footnotes). When that happens, a special placeholder is left in the originating message, so that the markup can be reconstructed when the translated Docbook file is built. Such placeholders must be carried into translation.</para>
 </listitem>
 
 </itemizedlist>
 </para>
 
 </sect2>
 
 <sect2 id="sv-check-grammar">
 <title><command>check-grammar</command></title>
 
 <para><command>check-grammar</command> checks translation with LanguageTool, an open source grammar and style checker (<ulink url="http://www.languagetool.org/">http://www.languagetool.org/</ulink>). LanguageTool supports a number of languages to greater or smaller extent, which you can check on <ulink url="http://www.languagetool.org/languages/">its web site</ulink>.</para>
 
 <para>LanguageTool can be run as standalone program or in client-server mode, and this sieve expects the latter. This means that LanguageTool has to be up and running before this sieve is run. Messages in which problems are discovered are reported to standard output.</para>
 
 <para>Parameters:
 <variablelist>
 
 <varlistentry>
 <term><option>lang:<replaceable>code</replaceable></option></term>
 <listitem>
 <para>The language code for which to apply the rules. If not given, it will be read from each PO file in turn, and if not found there either, an error will be signaled.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term><option>host:<replaceable>hostname</replaceable></option> [<literal>localhost</literal>]</term>
 <listitem>
 <para>Name of the host where the LanguageTool server is running. The default value of <literal>localhost</literal> means that it is running on the same computer where the sieve is run.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term><option>port:<replaceable>number</replaceable></option> [<literal>8081</literal>]</term>
 <listitem>
 <para>TCP port of the host on which the LanguageTool server listens for queries.</para>
 </listitem>
 </varlistentry>
 
 </variablelist>
 </para>
 
 </sect2>
 
 <sect2 id="sv-check-kde4">
 <title><command>check-kde4</command></title>
 
 <para><command>check-kde4</command> checks PO files extracted from program code based on KDE4 library and its translation system. Note that this really means what it says; this sieve should <emphasis>not</emphasis> be used to check just any PO file which happens to be part of the KDE project (e.g. PO files covering .desktop files, pure Qt code, etc.).</para>
 
 <para>Parameters:
 <variablelist>
 
 <varlistentry>
 <term><option>strict</option></term>
 <listitem>
 <para>Partly due to historical reasons, and partly due to programmers being sloppy, the original text itself is sometimes not valid by some checks. By default, when the original is not valid, the translation is not expected to be valid either, i.e. it is not checked. This parameter requires that the translation is always checked, regardless of the validity of the original (problems can almost always be avoided in the translation).</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term><option>lokalize</option></term>
 <listitem>
 <para>Open the PO file on reported messages in Lokalize. Lokalize must be already running with the project that contains the PO file opened.</para>
 </listitem>
 </varlistentry>
 
 </variablelist>
 </para>
 
 <para>Currently performed checks:
 <itemizedlist>
 
 <listitem>
 <para>Markup validity. KDE4 messages can contain a mix of <ulink url="http://techbase.kde.org/Development/Tutorials/Localization/i18n_Semantics">KUIT</ulink> and <ulink url="http://doc.qt.nokia.com/4.6/richtext-html-subset.html">Qt rich text</ulink> markup. Although Qt rich text does not have to be well-formed in XML sense, this check expects well-formedness to be preserved in translation if the original is such (also see the <option>strict</option> parameter).</para>
 
 <para>This check can be skipped on a message by adding to it the <literal>no-check-markup</literal> <link linkend="p-trflag">translator flag</link>.</para>
 </listitem>
 
 </itemizedlist>
 </para>
 
 </sect2>
 
 <sect2 id="sv-check-rules">
 <title><command>check-rules</command></title>
 
 <para><command>check-rules</command> applies language- and project-dependent Pology <emphasis>validation rules</emphasis> to translation. See <xref linkend="sec-lgrules"/> for detailed discussion on writing and applying rules.</para>
 
 <para>Parameters:
 <variablelist>
 
 <varlistentry>
 <term><option>lang:<replaceable>code</replaceable></option></term>
 <listitem>
 <para>The language code for which to apply the rules. If not given, it will be read from each PO file in turn, and if not found there either, an error will be signaled.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term><option>env:<replaceable>environment</replaceable></option></term>
 <listitem>
 <para>The language environment for which to apply the rules (see <xref linkend="sec-lglangenv"/>). Several environments can be given as comma-separated list, in which case the later environment in the list takes precedence on conflicted rules. If not given, it may also be read from PO files (see <link linkend="hdr-x-environment"><literal>X-Environment</literal></link> in <xref linkend="sec-cmheader"/>).</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term><option>envonly</option></term>
 <listitem>
 <para>When language environment is given, only the rules explicitly belonging to it are applied, while general rules for the selected language are ignored.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term><option>rule:<replaceable>identifiers</replaceable></option></term>
 <listitem>
 <para>Comma-separated list of rule identifiers, to apply only those rules. If a rule selected in this way is disabled in its definition, this enables it.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term><option>rulerx:<replaceable>regexes</replaceable></option></term>
 <listitem>
 <para>Like <option>rule</option>, but the values are interpreted as regular expressions by which to match rule identifiers.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term><option>norule:<replaceable>identifiers</replaceable></option></term>
 <listitem>
 <para>Inverse of the <option>rule</option> parameter: selected rules are not applied, and all other are applied.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term><option>norulerx:<replaceable>regexes</replaceable></option></term>
 <listitem>
 <para>Inverse of the <option>rulerx</option> parameter: selected rules are not applied, and all other are applied.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term><option>stat</option></term>
 <listitem>
 <para>Rules can take time to apply to all sieved PO files, and this parameter requests to write out some statistics of rule application at the end of sieving.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term><option>accel:<replaceable>characters</replaceable></option></term>
 <listitem>
 <para>Characters to consider as <link linkend="sec-poaccel">accelerator markers</link>. If not given, they may be read from sieved PO files. Note that this parameter in itself does nothing: it only makes it possible for a particular rule or group of rules to remove the accelerator before matching.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term><option>markup:<replaceable>types</replaceable></option></term>
 <listitem>
 <para>The type of text markup used in messages, by keyword. It can also be a comma-separated list of keywords. If not given, it may be read from sieved PO files. See description of <link linkend="hdr-x-text-markup"><literal>X-Text-Markup</literal></link> in <xref linkend="sec-cmheader"/> for the list of markup keywords currently known to Pology. Similarly to <option>accel</option> parameter, this parameter only enables rules to remove the markup (or do something else) before matching.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term><option>xml:<replaceable>file</replaceable></option></term>
 <listitem>
 <para>By default, messages failed by rules are reported to standard output, and this parameter requests that they be written into a custom (but simple) XML format. This also causes results to be cached: on subsequent runs of <command>check-rules</command> only modified PO files will be checked again, and results for non-modified files will be pulled from the cache. The cache can be found in <filename>$HOME/.pology-check_rules-cache/</filename> directory.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term><option>rfile:<replaceable>file</replaceable></option></term>
 <listitem>
 <para>By default internal Pology rules are applied, and this parameter can be used to apply external rules instead, defined in the given rule file.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term><option>rdir:<replaceable>directory</replaceable></option></term>
 <listitem>
 <para>Like <option>rfile</option>, but external rules are read from a directory containing any number of rule files.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term><option>branch:<replaceable>branch</replaceable></option></term>
 <listitem>
 <para>Apply rules only to messages from given branch (<link linkend="ch-summit">summit</link>). Several branches may be given as comma-separated list.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term><option>showfmsg</option></term>
 <listitem>
 <para>Rules are sometimes applied to the filtered instead of the original message, and when such message is failed, it may not be obvious what triggered the rule. This parameter requests that the filtered message is written out too when the original message is reported.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term><option>nomsg</option></term>
 <listitem>
 <para>When a message is failed, by default it is output in full together with the problem description. This parameter requests that only the problem description is output.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term><option>lokalize</option></term>
 <listitem>
 <para>Open the PO file on reported messages in Lokalize. Lokalize must be already running with the project that contains the PO file opened.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term><option>mark</option></term>
 <listitem>
 <para>To each failed message a <literal>failed-rule</literal> flag is added, modifying the PO file. Modified files can then be opened in the editor, and failed messages looked up by this flag.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term><option>byrule</option></term>
 <listitem>
 <para>As usual for sieving, by default each failed message is output as soon as it is processed. This parameter makes the failed messages output ordered by rules instead, where rules are sorted alphabetically by their identifiers. Note that this will cause there to be no output until all messages have been sieved.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term><option>ruleinfo</option></term>
 <listitem>
 <para>Shows information on loading of rules during sieving, including switching of environments and listing manually selected rules.</para>
 </listitem>
 </varlistentry>
 
 </variablelist>
 </para>
 
 <para>One or more rules can be disabled on a particular message in the PO file itself, by adding a special translator comment that starts with <literal>skip-rule:</literal> and continues with comma-separated list of rule identifiers:
 <programlisting language="po">
 # skip-rule: <replaceable>ruleid1</replaceable>, <replaceable>ruleid2</replaceable>, ...
 </programlisting>
 </para>
 
 </sect2>
 
 <sect2 id="sv-check-spell">
 <title><command>check-spell</command></title>
 
 <para><command>check-spell</command> checks spelling of translation by splitting it into words and passing them through GNU Aspell (<ulink url="http://aspell.net/">http://aspell.net/</ulink>). This sieve is a more specific counterpart to <link linkend="sv-check-spell-ec"><command>check-spell-ec</command></link>, which exposes some options specific to Aspell and requires no external Python modules, only the Aspell installation. Also read <xref linkend="sec-lgspell"/> for details on spell-checking in Pology.</para>
 
 <para><command>check-spell</command> behaves mostly the same as <command>check-spell-ec</command>, and accepts all the same parameters with same meanings; the exception is the <option>provider</option> parameter, which is not present here since Aspell is the fixed provider. Only the parameters specific to this sieve are described in the following:
 <variablelist>
 
 <varlistentry>
 <term><option>enc:<replaceable>encoding</replaceable></option></term>
 <listitem>
 <para>The encoding in which the text should be sent to Aspell.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term><option>var:<replaceable>variety</replaceable></option></term>
 <listitem>
 <para>The variety of the Aspell dictionary, if any.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term><option>skip:<replaceable>regex</replaceable></option></term>
 <listitem>
 <para>Words matched by this regular expression are not sent to spell-checker.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term><option>case</option></term>
 <listitem>
 <para>Matching patterns given as parameter values (e.g. with <option>skip:</option>) are by default case-insensitive, and this parameter switches them to case-sensitive.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term><option>xml:<replaceable>file</replaceable></option></term>
 <listitem>
 <para>By default, messages with unknown words are reported to standard output, and this parameter requests that they be written into a custom (but simple) XML format.</para>
 </listitem>
 </varlistentry>
 
 </variablelist>
 </para>
 
 <para>Aspell can be configured for use in Pology through user configuration, so that it is not necessary to issue some parameters on every run. See <xref linkend="sec-cmcfgaspell"/>.</para>
 
 <caution><para>This sieve is deprecated. Use <link linkend="sv-check-spell-ec"><command>check-spell-ec</command></link> instead, which can apply various spell-checking backends through Enchant.</para></caution>
 
 </sect2>
 
 <sect2 id="sv-check-spell-ec">
 <title><command>check-spell-ec</command></title>
 
 <para><command>check-spell-ec</command> uses the Enchant library (<ulink url="http://www.abisource.com/projects/enchant/">http://www.abisource.com/projects/enchant/</ulink>) through PyEnchant Python module (<ulink url="http://pyenchant.sourceforge.net">http://pyenchant.sourceforge.net</ulink>) to provide uniform access to different spell-checkers, such as Aspell, Ispell, Hunspell, etc. Translation is first split into words, possibly eliminating markup and other literal content, and the words are then fed to spell-checker. Messages containing unknown words are reported to standard output, with list of replacement suggestions.</para>
 
 <para>Parameters:
 <variablelist>
 
 <varlistentry>
 <term><option>provider:<replaceable>keyword</replaceable></option></term>
 <listitem>
 <para>The spell-checker that Enchant should use. The value is one of keywords defined by Enchant (e.g. <literal>aspell</literal>, <literal>myspell</literal>...), and can be seen by running <command>enchant-lsmod</command> command (only providers available on the system are shown). If not given either by this parameter or in user configuration, Enchant will try to select a provider on its own.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term><option>lang:<replaceable>code</replaceable></option></term>
 <listitem>
 <para>The language code for which the spelling is checked. If not given, it will be read from each PO file in turn, and if not found there either, an error will be signaled.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term><option>env:<replaceable>environment</replaceable></option></term>
 <listitem>
 <para>The language environment for which to include supplemental dictionaries (see <xref linkend="sec-lglangenv"/>). Several environments can be given as comma-separated list, in which case the union of their dictionaries is used. If not given, environments may be read from PO files (see <link linkend="hdr-x-environment"><literal>X-Environment</literal></link> in <xref linkend="sec-cmheader"/>) or from user configuration.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term><option>accel:<replaceable>characters</replaceable></option></term>
 <listitem>
 <para>Characters to consider as <link linkend="sec-poaccel">accelerator markers</link>, to remove them before splitting text into words. If not given, they may be read from PO files (see <link linkend="hdr-x-accelerator-marker"><literal>X-Acclerator-Marker</literal></link> in <xref linkend="sec-cmheader"/>).</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term><option>markup:<replaceable>types</replaceable></option></term>
 <listitem>
 <para>The type of text markup used in messages, by keyword. It can also be a comma-separated list of keywords. If not given, it may be read from PO files (see <link linkend="hdr-x-text-markup"><literal>X-Text-Markup</literal></link> in <xref linkend="sec-cmheader"/>; there the list of markup keywords currently known to Pology is given as well).</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term><option>skip:<replaceable>regex</replaceable></option></term>
 <listitem>
 <para>Words matched by this regular expression are not sent to spell-checker.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term><option>case</option></term>
 <listitem>
 <para>Matching patterns given as parameter values (e.g. with <option>skip:</option>) are by default case-insensitive, and this parameter switches them to case-sensitive.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term><option>filter:<replaceable>hookspec</replaceable></option></term>
 <listitem>
 <para>The hook to modify the text before splitting into words and spell-checking them (see <xref linkend="sec-cmhooks"/>). The hook type must be F1A, F3A, or F3C. The parameter can be repeated to add several hooks, which are then applied in the order of specification.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term><option>suponly</option></term>
 <listitem>
 <para>By default, internal supplemental spelling dictionaries are added to the system dictionary of the selected spell-checker. This parameter can be issued to instead use only internal dictionaries and not the system dictionary.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term><option>list</option></term>
 <listitem>
 <para>By default, when an unknown word is found, the complete message is output, with the problematic word highlighted and possibly the replacement suggestions. With this parameter, only a plain sorted list of unknown words, one per line, is output at the end of sieving. This is useful when a lot of false positives are expected, to quickly add them to the supplemental dictionary.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term><option>lokalize</option></term>
 <listitem>
 <para>Open the PO file on messages containing unknown words in Lokalize. Lokalize must be already running with the project that contains the PO file opened.</para>
 </listitem>
 </varlistentry>
 
 </variablelist>
 </para>
 
 <para><command>check-spell-ec</command> may be told to skip checking specific messages and words, and it may use internal supplemental spelling dictionaries. See <xref linkend="sec-lgspell"/> for these and other details on spell-checking in Pology.</para>
 
 <para>Enchant can be configured for use in Pology through user configuration, so that it is not necessary to issue some parameters on every run. See <xref linkend="sec-cmcfgenchant"/>.</para>
 
 </sect2>
 
 <sect2 id="sv-check-tp-kde">
 <title><command>check-tp-kde</command></title>
 
 <para>The <ulink url="http://l10n.kde.org/">KDE Translation Project</ulink> contains a great number of PO files extracted from various types of sources. This results in that for each message, there are things that the translation can, must or must not contain, for the translation to be technically valid. When run over PO files within the KDE TP, <command>check-tp-kde</command> will first try to determine the type of each message and then apply appropriate technical checks to it. Message type is determined based on file location, file header, message flags and contexts; even a particular message in a particular file may be checked for some very specific issue.</para>
 
 <para id="p-techprob">"Technical" issues are those which should be fixed regardless of the language and style of translation, because they can lead to loss of functionality, information or presentation to the user. For example, a technical issue would be badly paired XML tags in translation, when in the original they were well paired; a non-technical issue (and thus not checked) would be when the original ends with a certain punctuation, but translation does not -- whether such details are errors or not, depends on the target language and translation style.</para>
 
 <para>For the sieve to function properly, it needs to detect the project subdirectory of each PO file up to topmost division within the branch, e.g. <filename>messages/kdebase</filename> <filename>docmessages/kdegames</filename>. This means that the local copy of the repository tree needs to follow the repository layout up to that point, e.g. <filename>kde-trunk-ui/kdebase</filename> and <filename>kde-trunk-doc/kdegames</filename> would not be valid local paths.</para>
 
 <para>Parameters:
 <variablelist>
 
 <varlistentry>
 <term><option>strict</option></term>
 <listitem>
 <para>Sometimes the original text itself may not be valid against a certain check. When this is the case, by default the translation is not expected to be valid either, and the check is skipped. Issuing this parameter will force all checks on translation, regardless of whether the original is valid or not. It may still be possible to avoid some checks on those messages that just cannot be repared through translation, if those checks define their own mechanism of cancelation (like adding a special translator comment).</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term><option>check:<replaceable>keywords</replaceable></option></term>
 <listitem>
 <para>Comma-separated list of checks to apply, by keyword, instead of all. Available checks are listed below.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term><option>showmsg</option></term>
 <listitem>
 <para>By default, when the message does not pass a check, only its location and the problem are reported. This parameter requests that message is reported in total, possibly with problematic segments of translation highlighted.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term><option>lokalize</option></term>
 <listitem>
 <para>Open the PO file on reported messages in Lokalize. Lokalize must be already running with the project that contains the PO file opened.</para>
 </listitem>
 </varlistentry>
 
 </variablelist>
 </para>
 
 <para>Currently available checks (keyword in parenthesis):
 <itemizedlist>
 
 <listitem>
 <para>KDE4 markup checking (<literal>kde4markup</literal>).</para>
 </listitem>
 
 <listitem>
 <para>Qt markup checking (<literal>qtmarkup</literal>).</para>
 </listitem>
 
 <listitem>
 <para>Docbook markup checking (<literal>dbmarkup</literal>)</para>
 </listitem>
 
 <listitem>
 <para>HTML markup checking (<literal>htmlmarkup</literal>).</para>
 </listitem>
 
 <listitem>
 <para>No translation scripting in "dumb" messages (<literal>nots</literal>). Translations fetched at runtime by KDE4 translation system may use <ulink url="http://techbase.kde.org/Localization/Concepts/Transcript">translation scripting</ulink>. This check will make sure that scripting is not attempted for other types of messages (used by Qt-only code, for .desktop files, etc.).</para>
 </listitem>
 
 <listitem>
 <para>Qt datetime format messages (<literal>qtdt</literal>). A message is considered to be in this format if it contains the string <literal>qtdt-format</literal> in its <varname>msgctxt</varname> string or among flags.</para>
 </listitem>
 
 <listitem>
 <para>Validity of translator credits (<literal>trcredits</literal>). PO files may contain meta-messages to input translator credits, which should have both valid translations on their own and some congruence between them.</para>
 </listitem>
 
 <listitem>
 <para>Query placeholders in Plasma runners (<literal>plrunq</literal>). Messages in Plasma runners may contain special query placeholder <literal>:q:</literal>, which should be present in translation too.</para>
 </listitem>
 
 <listitem>
 <para>File-specific checking (<literal>catspec</literal>). Certain messages in certain PO files have special validity requirements, and this check activates all such file-specific checks.</para>
 </listitem>
 
 </itemizedlist>
 </para>
 
 <para>All markup checks can be skipped on a message by adding the <literal>no-check-markup</literal> <link linkend="p-trflag">translator flag</link>.</para>
 
 </sect2>
 
 <sect2 id="sv-check-tp-wesnoth">
 <title><command>check-tp-wesnoth</command></title>
 
 <para>PO files of <ulink url="http://www.wesnoth.org/">The Battle of Wesnoth</ulink> contain a mix of well-known and custom markup and format directives. <command>check-tp-wesnoth</command> heuristically determines the type of each message in a Wesnoth PO file and applies appropriate technical checks to it (where "technical" has the same meaning as in <link linkend="p-techprob">the <command>check-tp-kde</command> sieve</link>).</para>
 
 <para>Parameters:
 <variablelist>
 
 <varlistentry>
 <term><option>check:<replaceable>keywords</replaceable></option></term>
 <listitem>
 <para>Comma-separated list of checks to apply, by keyword, instead of all. Available checks are listed below.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term><option>showmsg</option></term>
 <listitem>
 <para>Instead of just showing the message location and problem description, also show the complete message, possibly with higlighted problematic segments.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term><option>lokalize</option></term>
 <listitem>
 <para>Open the PO file on reported messages in Lokalize. Lokalize must be already running with the project that contains the PO file opened.</para>
 </listitem>
 </varlistentry>
 
 </variablelist>
 </para>
 
 <para>Currently available checks (keyword in parenthesis):
 <itemizedlist>
 
 <listitem>
 <para>Stray context separators in translation (<literal>ctxtsep</literal>). Wesnoth is still embedding disambiguating context into <varname>msgid</varname>, by putting it in front of the actual text and separated by <literal>^</literal>. An unwary translator will sometimes mistakes such context for part of the original text, and translate it too.</para>
 </listitem>
 
 <listitem>
 <para>Congruence of WML interpolations (<literal>interp</literal>). WML interpolations look like <literal>"...side $side_number is..."</literal> and normally must match between the original and translation, or else the player would loose information. Only in very rare cases (e.g. some plurals and Markov chain generators) some interpolations may be missing in translation, and then they can be listed space-separated in a translator comment to silence the check:
 <programlisting language="po">
 # ignore-interpolations: <replaceable>interp1</replaceable> <replaceable>interp2</replaceable> ...
 </programlisting>
 (the <literal>$</literal> character is not necessary in the list).
 </para>
 </listitem>
 
 <listitem>
 <para>WML markup checking (<literal>wml</literal>). If WML in translation is not valid, player may see some visual artifacts. Also, links in WML must match between original and translation, to avoid loss of information.</para>
 </listitem>
 
 <listitem>
 <para>Pango markup checking (<literal>pango</literal>). Pango is used in some places for visual text markup instead of WML.</para>
 </listitem>
 
 <listitem>
 <para>Congruence of leading and trailing space (<literal>space</literal>). For many languages, significant leading and trailing space from the original should be preserved. A heuristic is used to determine when leading or trailing space is significant. Only languages explicitly specified internally are checked for this.</para>
 </listitem>
 
 <listitem>
 <para>Docbook validity (<literal>docbook</literal>). Docbook is actually not used as a source format anywhere in Wesnoth, but the Wesnoth manual is converted into Docbook specifically to facilitate translation (weird as it may sound).</para>
 </listitem>
 
 <listitem>
 <para>Man page validity (<literal>man</literal>).</para>
 </listitem>
 
 </itemizedlist>
 </para>
 
 </sect2>
 
 <sect2 id="sv-collect-pmap">
 <title><command>collect-pmap</command></title>
 
 <para><emphasis>Property maps</emphasis> (or <emphasis>pmaps</emphasis> for short) are one way in which arbitrary properties of language phrases can be defined for use in scripted translations, such as provided by <ulink url="http://techbase.kde.org/Localization/Concepts/Transcript">Transcript</ulink>, the translation scripting system in KDE 4.</para>
 
 <para>A property map is a text file with a number of entries, each defining the properties of a certain phrase. A pmap entry starts with one or more keys and continues with arbitrary number of key-value properties. An example entry would be grammar declinations of a noun:
 <programlisting>
 =/Athens/Atina/nom=Atina/gen=Atine/dat=Atini/acc=Atinu//
 </programlisting>
 The first two characters define, in order, the key-value separator (here <literal>=</literal>) and the property separator (here <literal>/</literal>) for the current entry. The two separators can be any non-alphanumeric characters, and must be different. Then follows a number of entry keys, delimited by property separators, and then a number of key-value properties, each internaly delimited by the key-value separator. The entry is terminated by double property separator. Properties of an entry can be fetched in the translation scripting system by any of the entry keys; keys are case- and whitespace-insensitive.</para>
 
 <para><command>collect-pmap</command> will parse pmap entries from manual comments in messages, collect them, and write out a property map file. It is not necessary to explicitly specify entry keys, since the contents of <varname>msgid</varname> and <varname>msgstr</varname> are automatically added as keys. Since each manual comment is one line, it is also allowed to drop
 the final double separator which would normally terminate the entry.
 The above example would thus look like this in a PO message:
 <programlisting language="po">
 # pmap: =/nom=Atina/gen=Atine/dat=Atini/acc=Atinu/
 msgctxt "Greece/city"
 msgid "Athens"
 msgstr "Atina"
 </programlisting>
 The manual comment starts with <literal>pmap:</literal> keyword, which is followed by a normal pmap entry, except for missing keys (but additional keys can be specified when <varname>msgid</varname> and <varname>msgstr</varname> are not sufficient). It is also possible to split the entry into several comments,
 with only condition that all share the same set of separators:
 <programlisting language="po">
 # pmap: =/nom=Atina/gen=Atine/
 # pmap: =/dat=Atini/acc=Atinu/
 </programlisting>
 After collecting pmap entries from all processed PO files, if two or more entries end up having same keys, they are all removed from the collection and a warning is reported.</para>
 
 <para>Pmap entries are collected only from translated, non-plural messages.</para>
 
 <para>Parameters:
 <variablelist>
 
 <varlistentry>
 <term><option>outfile:<replaceable>file</replaceable></option></term>
 <listitem>
 <para>File path into which the property map should be written. If not given, nothing is written out; this is useful for validating entries.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term><option>propcons:<replaceable>file</replaceable></option></term>
 <listitem>
 <para>Path to the file which defines constraints on property keys and values, used to validate parsed entries (see <xref linkend="sec-svvalpmap"/>).</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term><option>extrakeys</option></term>
 <listitem>
 <para>By default, it is actually not possible to add any aditional entry keys besides the automatically added <varname>msgid</varname> and <varname>msgstr</varname>. This gives extra safety against errors, such as translator mistyping the key-value pair. If additional keys are actually needed, this parameter can be issued to accept them.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term><option>derivs:<replaceable>file</replaceable></option></term>
 <listitem>
 <para>Path to the file which defines derivators for synder entries (see <xref linkend="sec-svsynder"/>).</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term><option>pmhead:<replaceable>string</replaceable></option></term>
 <listitem>
 <para>Default <literal>pmap:</literal> as entry prefix may not be the most convenient; for example, when the language of translation is not written with Latin script. This parameter makes makes it possibly to use an arbitrary string for the entry prefix.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term><option>sdhead:<replaceable>string</replaceable></option></term>
 <listitem>
 <para>Like <option>pmhead</option>, but for prefix to synder entries, instead of the default <literal>synder:</literal> (see <xref linkend="sec-svsynder"/>).</para>
 </listitem>
 </varlistentry>
 
 </variablelist>
 </para>
 
 <sect3 id="sec-svsynder">
 <title>Derivating Entries</title>
 
 <para>There is another, more succint way to define pmap entries in comments. Instead of writting out all key-value combinations, it is possible instead to generate them by using <emphasis>syntagma derivators</emphasis> (or <emphasis>synders</emphasis>) for short. From the earlier example:
 <programlisting language="po">
 # pmap: =/nom=Atina/gen=Atine/dat=Atini/acc=Atinu/
 </programlisting>
 it can be observed that each form has the same root, <literal>Atin</literal>, followed by the appropriate ending for that form type. This makes it convenient
 to reformulate it as a syntagma derivation:
 <programlisting language="po">
 # synder: Atin|a
 </programlisting>
 Here <literal>|a</literal> is a <emphasis>derivator</emphasis>; all derivators are defined in a separate synder file (with <filename>.sd</filename> extension by convention) and made known to the sieve through the <option>derivs</option> parameter. The derivator in this example would be defined like this:
 <programlisting>
 |a: nom=a, gen=e, dat=i, acc=u
 </programlisting>
 First comes the derivator name, starting with <literal>|</literal> and ending with <literal>:</literal>, and then the comma-separated list of key-value pairs  similar as in the pmap entry, except that now only the endings for the given form are specified. Synders are actually a standalone subsystem of Pology, see <xref linkend="sec-lgsynder"/> for all details.</para>
 
 <para>It is possible to mix pmap (<literal># pmap: ...</literal>) and synder (<literal># synder: ...</literal>) entries in translator comments. For example, synder entries may be used to cover majority of cases, which follow the general language rules, while pmap entries can be used for exceptions.</para>
 
 <para>On the other hand, every pmap entry can be reformulated as a synder entry which does not refer to an external derivator:
 <programlisting language="po">
 # synder: nom=Atina, gen=Atine, dat=Atini, acc=Atinu
 </programlisting>
 This begs the question of what is the need for pmap entries at all, if synder entries can be used in the same capacity and beyond? Pmap entries are still useful because synders have a lot of special syntax and rules to keep in mind (e.g. what if the phrase itself contains a comma?), while raw pmaps have none past what was described above.</para>
 
 </sect3>
 
 <sect3 id="sec-svvalpmap">
 <title>Validating Entries</title>
 
 <para>The <literal>propcons</literal> parameter can be used to specify a file which defines constraints on acceptable property keys, and on values by each key. Its format is the following:
 <programlisting>
 # Full-line comment.
 /key_regex_1/value_regex_1/flags # a trailing comment
 /key_regex_2/value_regex_2/flags
 :key_regex_3:value_regex_3:flags # different separator
 # etc.
 </programlisting>
 Regular expressions for keys and values are delimited by a separator defined by first non-whitespace character in the line, which must also be non-alphanumeric. Before being compiled, regular expressions are automatically wrapped as <literal>^(<replaceable>regex</replaceable>)$</literal>, so that an expression to require a certain prefix is given as <literal><replaceable>prefix</replaceable>.*</literal> and a suffix as <literal>.*<replaceable>suffix</replaceable></literal>. A property key must match one of the key regexs, or else it is considered invalid. Value to that property must then match the value regexes attached to all matched key regexes.</para>
 
 <para>For example, a constraint file defining no constraints on either
 property keys or values is:
 <programlisting>
 /.*/.*/
 </programlisting>
 while a file explicitly listing all allowed property keys, and constraining values to some of them, would be:
 <programlisting>
 /nom|gen|dat|acc/.*/
 /gender/m|f|n/
 /number/s|p/
 </programlisting>
 </para>
 
 <para>The last separator in the constraint can be followed by a string of single-character flags. These flags are currently defined:
 <itemizedlist>
 <listitem>
 <para><literal>i</literal>: case-insensitive matching for the value.</para>
 </listitem>
 <listitem>
 <para><literal>I</literal>: case-insensitive matching for the key.</para>
 </listitem>
 <listitem>
 <para><literal>t</literal>: the value must both match the regular expression and be equal to <varname>msgstr</varname>. If <literal>i</literal> flag is added too, equality check is also case-insensitive.</para>
 </listitem>
 <listitem>
 <para><literal>r</literal>: regular expression for the key must match at least one key among all defined properties.</para>
 </listitem>
 </itemizedlist>
 </para>
 
 <para>Constraint definition file must be encoded with UTF-8.</para>
 
 </sect3>
 
 </sect2>
 
 <sect2 id="sv-diff-previous">
 <title><command>diff-previous</command></title>
 
 <para>When PO files are merged with <option>--previous</option> option to <command>msgmerge</command>, fuzzy messages will retain the previous version of original text (<varname>msgctxt</varname>, <varname>msgid</varname> and <varname>msgid_plural</varname>) under <literal>#|</literal> comments. Then <command>diff-previous</command> can be used to embedded differences from previous to current original into previous original strings. For example, the message:
 <programlisting language="po">
 #: main.c:110
 #, fuzzy
 #| msgid "The Record of The Witch River"
 msgid "Records of The Witch River"
 msgstr "Beleška o Veštičjoj reci"
 </programlisting>
 will become after sieving:
 <programlisting language="po">
 #: main.c:110
 #, fuzzy
 #| msgid "{-The Record-}{+Records+} of The Witch River"
 msgid "Records of The Witch River"
 msgstr "Beleška o Veštičjoj reci"
 </programlisting>
 Text editors may even provide highlighting for the wrapped difference segments
 (e.g. Kwrite/Kate).</para>
 
 <para>This sieve is very useful if your PO editor does not show differences in the original by itself. To be able to easily see exactly what was changed in the original is important both for efficiency and for quality. Think of a long paragraph in which only one word was changed: without a diff it will take you time to reread it, and you may even miss that changed word.</para>
 
 <para>Parameters:
 <variablelist>
 
 <varlistentry>
 <term><option>strip</option></term>
 <listitem>
 <para>Instead of embedding diffs, remove them from messages, recovering the original form of previous strings. This is useful if you did not update all fuzzy messages but you anyway want to send the PO file away (commit it to the repository, etc.).</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term><option>branch:<replaceable>branch</replaceable></option></term>
 <listitem>
 <para>Embed diffs only into messages from given branch (<link linkend="ch-summit">summit</link>). Several branches may be given as comma-separated list.</para>
 </listitem>
 </varlistentry>
 
 </variablelist>
 </para>
 
 </sect2>
 
 <sect2 id="sv-empty-fuzzies">
 <title><command>empty-fuzzies</command></title>
 
 <para>For every fuzzy message, <command>empty-fuzzies</command> removes the translation and fuzzy data (the <literal>fuzzy</literal> flag, previous strings). Translator comments are kept by default, but they can be removed as well. Obsolete fuzzy messages are completely removed.</para>
 
 <para>Parameters:
 <variablelist>
 
 <varlistentry>
 <term><option>rmcomments</option></term>
 <listitem>
 <para>Also remove translator comments from fuzzy messages.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term><option>noprev</option></term>
 <listitem>
 <para>Empty only those fuzzy messages which do not have previous strings (i.e. when the PO file was merged without <option>--previous</option> option to <command>msgmerge</command>).</para>
 </listitem>
 </varlistentry>
 
 </variablelist>
 </para>
 
 </sect2>
 
 <sect2 id="sv-equip-header-tp-kde">
 <title><command>equip-header-tp-kde</command></title>
 
 <para><command>equip-header-tp-kde</command> applies <link linkend="hk-proj-kde-header-equip-header">the <literal>kde%header/equip-header</literal> hook</link> to headers of PO files within the KDE Translation Project.</para>
 
 <para>There are no parameters.</para>
 
 </sect2>
 
 <sect2 id="sv-fancy-quote">
 <title><command>fancy-quote</command></title>
 
 <para>Ordinary ASCII quotes are easy to type on most keyboard layouts, and these quotes are frequently encountered in non-typeset English texts, rather than proper English quotes. These proper quotes are sometimes called "fancy" quotes. When translating from English, translators can thus be easily moved to use ASCII quotes themselves, instead of the fancy quotes appropriate for their language. To somewhat correct this, <command>fancy-quote</command> can be used to replace ASCII quotes in the translation with selected pairs of fancy quotes.</para>
 
 <para>ASCII quotes that are part of text markup (e.g. attribute values in XML-like tags) must not be replaced, and this sieve will use heuristics to determine such places. In fact, it will replace quotes rather conservatively. Nevertheless, unless some sort of automatic validation is available, converted text should be manually inspected for correctness.</para>
 
 <para>Parameters:
 <variablelist>
 
 <varlistentry>
 <term><option>single:<replaceable>quotes</replaceable></option></term>
 <listitem>
 <para>Opening and closing quote to replace ASCII single quotes (i.e. <replaceable>quotes</replaceable> is a two-character string). If not given, single quotes are not replaced (but see the <option>longsingle</option> parameter).</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term><option>single:<replaceable>quotes</replaceable></option></term>
 <listitem>
 <para>Opening and closing quote to replace ASCII double quotes. If not given, double quotes are not replaced (but see the <option>longdouble</option> parameter).</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term><option>longsingle:<replaceable>open</replaceable>,<replaceable>close</replaceable></option></term>
 <listitem>
 <para>Alternative to <option>single</option>, if opening and closing quotes are not single characters. The value are the opening quote string and the closing quote string, separated by comma.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term><option>longdouble:<replaceable>open</replaceable>,<replaceable>close</replaceable></option></term>
 <listitem>
 <para>Alternative to <option>double</option>, if opening and closing quotes are not single characters.</para>
 </listitem>
 </varlistentry>
 
 </variablelist>
 </para>
 
 </sect2>
 
 <sect2 id="sv-find-messages">
 <title><command>find-messages</command></title>
 
 <para><command>find-messages</command> is the search and replace workhorse of Pology. It applies one or several conditions to different parts of the PO message, with selectable boolean linking between them. If the message is matched as whole, it is reported and possibly some replacements are done. Messages are by default reported to standard output, with full location reference (PO file path, line and entry number), but can also be opened directly in one of supported PO editors (see <xref linkend="sec-cmsupped"/>).</para>
 
 <para>When used in a sieve chain, <command>find-messages</command> will stop further sieving of messages which did not satisfy the conditions. This makes it useful as a filter for selecting subsets of messages on which other sieves should operate.</para>
 
 <para>There are three logical groups of parameters: matching parameters, replacement parameters, and general parameters. Matching and replacement parameters have certain relationships between themselves, while general parameters have mutually independent effects (i.e. as usual for sieve parameters).</para>
 
 <sect3 id="sec-svfmmpar">
 <title>Matching Parameters</title>
 
 <para>Matching parameters specify patterns for matching by parts of the message, or represent binary conditions (whether the message is translated, etc.). For example:
 <programlisting language="bash">
 $ posieve find-messages -s msgid:'foo bar'
 </programlisting>
 will report all messages which contain the phrase "foo bar" in their <varname>msgid</varname> (or <varname>msgid_plural</varname>) string. When several matching parameters are given, by default the message is matched if all patterns match; that is, boolean linking of conditions is AND. This:
 <programlisting language="bash">
 $ posieve find-messages -s msgid:'foo bar' -s transl
 </programlisting>
 will report all messages that contain "foo bar" in original <emphasis>and</emphasis> are translated. Boolean linking can be switched to OR by issuing the <option>or</option> parameter. To find all messages that contain the word "tooltip" in <emphasis>either</emphasis> context or comments:
 <programlisting language="bash">
 $ posieve find-messages -s msgctxt:tooltip -s comment:tooltip -s or
 </programlisting>
 (Actually, the effect of <option>or</option> is somewhat more specific, see its description below.) String matching is by default case insensitive, which can be changed globally by issuing the <option>case</option> parameter.</para>
 
 <para>Every matching parameter has a negative counterpart, named by prepending <literal>n</literal> to the original parameter, which matches when the original parameter does not. Running:
 <programlisting language="bash">
 $ posieve find-messages -s msgid:'hello' -s nmsgstr:'zdravo'
 </programlisting>
 would find all messages that contain "hello" in the original and do <emphasis>not</emphasis> contain "zdravo" in the translation (a typical usage pattern in quick terminology checks).</para>
 
 <para>To find all messages not matching a set of conditions, in principle it would be possible to negate the whole condition set by switching between positive/negative parameters and AND/OR-linking, but this can be cumbersome. Instead, the <option>invert</option> parameter can be issued to report messages that are not matched by the condition set.</para>
 
 <para>Sometimes neither simple AND nor simple OR boolean linking is sufficient to form the search. Therefore the <option>fexpr</option> parameter is provided, which can be used to specify a search expression with explicit boolean operators and parentheses for controlling the evaluation order. With <option>fexpr</option>, the previous example could be reformulated as:
 <programlisting language="bash">
 $ posieve find-messages -s fexpr:'msgid/hello/ and not msgstr/zdravo/'
 </programlisting>
 For details, see the description of <option>fexpr</option> below.</para>
 
 <para>Currently defined matching parameters:
 <variablelist>
 
 <varlistentry>
 <term><option>(n)msgctxt:<replaceable>regex</replaceable></option></term>
 <listitem>
 <para>Regular expression to match the <varname>msgctxt</varname> string.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term><option>(n)msgid:<replaceable>regex</replaceable></option></term>
 <listitem>
 <para>Regular expression to match the <varname>msgid</varname> and <varname>msgid_plural</varname> strings. The condition is satisfed as whole if <emphasis>either</emphasis> of these strings matches.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term><option>(n)msgstr:<replaceable>regex</replaceable></option></term>
 <listitem>
 <para>Regular expression to match <varname>msgstr</varname> strings. The condition is satisfed as whole if any of the <varname>msgstr</varname> strings matches.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term><option>(n)comment:<replaceable>regex</replaceable></option></term>
 <listitem>
 <para>Regular expression to match extracted and translator comments and source reference comments. The condition is satisfed as whole if any of these comments matches.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term><option>(n)flag:<replaceable>regex</replaceable></option></term>
 <listitem>
 <para>Regular expression to match flags. This matches each flag in turn, and not the flag comment as a monolithic string. The condition is satisfed as whole if any flag matches.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term><option>(n)transl</option></term>
 <listitem>
 <para>The message must be translated.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term><option>(n)obsol</option></term>
 <listitem>
 <para>The message must be obsolete.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term><option>(n)active</option></term>
 <listitem>
 <para>The message must be active, i.e. translated and not obsolete.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term><option>(n)plural</option></term>
 <listitem>
 <para>The message must be a plural message.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term><option>(n)maxchar:<replaceable>number</replaceable></option></term>
 <listitem>
 <para>Original and translation can have at most this many characters. The condition is satisfied as whole if all these strings satisfy it.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term><option>(n)lspan:<replaceable>start</replaceable>:<replaceable>end</replaceable></option></term>
 <listitem>
 <para>The referent line number of the message (the line in which its <varname>msgid</varname> string starts) must fall within given range. The starting number is included in the range, the ending number is not.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term><option>(n)espan:<replaceable>start</replaceable>:<replaceable>end</replaceable></option></term>
 <listitem>
 <para>Like <option>lspan</option>, but instead of line numbers it applies to entry numbers. These are the numbers that dedicated PO editors usually report in their user interfaces.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term><option>(n)branch:<replaceable>branch</replaceable></option></term>
 <listitem>
 <para>The message must belong to this branch (<link linkend="ch-summit">summit</link>). Several branches may be given as comma-separated list.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry id="p-fexprdesc">
 <term><option>(n)fexpr:<replaceable>expression</replaceable></option></term>
 <listitem>
 
 <para>Boolean expression with explict boolean operators and parenthesis for priority, constructed out of any of the other matching parameters. If a match parameter needs a value (like a regular expression), in the expression it is given as <literal><replaceable>match</replaceable>/<replaceable>value</replaceable>/</literal>, where any nonalphanumeric character can be used consistently instead of <literal>/</literal> (in case the value itself contains <literal>/</literal>). For example, the expression:
 <programlisting>
 fexpr:'(msgctxt/foo/ or comment/foo/) and msgid/bar/'
 </programlisting>
 is satisfied if either the context or comments contain "foo", and the original text contains "bar".</para>
 
 <para>If matching is influenced by a general parameter (e.g. case sensitivity), in the expression it may be able to take overriding modifiers in form of single characters after the value, i.e. <literal><replaceable>match</replaceable>/<replaceable>value</replaceable>/<replaceable>modifiers</replaceable></literal>. Assuming that <option>case</option> parameter has not been issued, the expression:
 <programlisting>
 fexpr:'msgid/quuk/ and msgstr/Qaak/c'
 </programlisting>
 will be satisfied if the original text contains "quuk" in any casing, and translation contains exactly "Qaak". Currently available modifiers are:
 <itemizedlist>
 <listitem>
 <para><literal>c</literal>: matching is case-sensitive.</para>
 </listitem>
 <listitem>
 <para><literal>i</literal>: matching is case-insensitive. May be needed when string matching is globally case-sensitive due to <option>case</option> being issued.</para>
 </listitem>
 </itemizedlist>
 </para>
 
 </listitem>
 </varlistentry>
 
 </variablelist>
 </para>
 
 </sect3>
 
 <sect3 id="sec-svfmrpar">
 <title>Replacement Parameters</title>
 
 <para>Replacement is done in pair with matching the appropriate string in the message. For example, to replace each appearance of "foobar" with "fumbar" in translation, this would be run:
 <programlisting language="bash">
 $ posieve find-messages -s msgstr:foobar -s replace:fumbar
 </programlisting>
 The <option>replace</option> parameter works in pair with <option>msgstr</option>, i.e. <option>replace</option> cannot be issued without issuing <option>msgstr</option> as well. There are two possible problems with replacement as straightforward as this. The first is that if "foobar" was a whole word (or start of a word), and this word in the text started with upper-case letter, the replacement would make it lower-case. This can be avoided by executing replacement twice with case sensitivity:
 <programlisting language="bash">
 $ posieve find-messages -s msgstr:foobar -s replace:fumbar -scase
 $ posieve find-messages -s msgstr:Foobar -s replace:Fumbar -scase
 </programlisting>
 The other problem is if the word is split by an accelerator marker, for example:
 <programlisting language="po">
 msgstr "... f_oobar ..."
 </programlisting>
 The search may still find the word (see the <option>accel</option> parameter below), but direct replacement would cause the loss of accelerator marker, and therefore it is not done.<footnote>
 <para>Some heuristics for reinsertion of the accelerator marker may be implemented in the future.</para>
 </footnote> To see such cases, you should monitor the output of <command>find-messages</command> (always a good idea when doing batch replacement), where matched and replaced parts of the text will be highlighted.</para>
 
 <para>As usual for replacement based on regular expression, the replacement string may contain <literal>\<replaceable>number</replaceable></literal> references to groups defined in the matching pattern. For example, the previous example of case-aware replacement could be more efficiently and more elegantly performed with:
 <programlisting language="bash">
 $ posieve find-messages -s msgstr:'(f)oobar' -s replace:'\1umbar'
 </programlisting>
 (Though this is possible only if the original and the replacement start with the same letter.)</para>
 
 <para>Currently defined replacement parameters:
 <variablelist>
 
 <varlistentry>
 <term><option>replace:<replaceable>string</replaceable></option></term>
 <listitem>
 <para>The string to replace the match by <option>msgstr</option> parameter. Can contain regular expression group references.</para>
 </listitem>
 </varlistentry>
 
 </variablelist>
 </para>
 
 </sect3>
 
 <sect3 id="sec-svfmgpar">
 <title>General Parameters</title>
 
 <para>Parameters influencing general behavior of <command>find-messages</command> are as follows:
 <variablelist>
 
 <varlistentry>
 <term><option>or</option></term>
 <listitem>
 <para>Boolean OR instead of AND linking of conditions, but only for string matchers: <option>msgctxt</option>, <option>msgid</option>, <option>msgstr</option>, <option>comment</option>. This restriction may seem odd, but it is what is mostly needed in practice. For example, the set of conditions:
 <programlisting language="bash">
 -s msgctxt:tooltip -s comment:tooltip -s transl -s or
 </programlisting>
 would match all translated messages which have "tooltip" in context or in comments, and not messages which are either translated or have "tooltip" in context or in comments. For full control over the expression, use the <option>fexpr</option> parameter.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term><option>invert</option></term>
 <listitem>
 <para>Inverts the selection: messages satisfying the condition set are <emphasis>not</emphasis> selected.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term><option>accel:<replaceable>characters</replaceable></option></term>
 <listitem>
 <para>Characters to consider as <link linkend="sec-poaccel">accelerator markers</link>, to remove before applying matching patterns. If not given, they may be read from PO files (see <link linkend="hdr-x-accelerator-marker"><literal>X-Acclerator-Marker</literal></link> in <xref linkend="sec-cmheader"/>).</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term><option>case</option></term>
 <listitem>
 <para>Matching patterns for strings and comments are by default case-insensitive, and this parameter switches them to case-sensitive.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term><option>mark</option></term>
 <listitem>
 <para>To each selected message a <literal>match</literal> flag is added, modifying the PO file. Modified files can then be opened in the editor,
 and selected messages looked up by this flag. This is typically done when something should be modified in selected messages, but doing that automatically (using <option>replace</option> parameter) is not possible or safe enough. Also useful here is the option <option>-m</option>/<option>--output-modified</option> of <command>posieve</command>, to write out the paths of modified PO files into a separate file, which can then be fed to the editor.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term><option>filter:<replaceable>hookspec</replaceable></option></term>
 <listitem>
 <para>The hook to modify the translation before applying the <option>msgstr</option> matcher to it. The hook type must be F1A. The parameter can be repeated to add several hooks.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term><option>nomsg</option></term>
 <listitem>
 <para>Do not report selected messages, either to standard output or to PO editors. Useful when <command>find-messages</command> is a pre-filter in the sieve chain.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term><option>lokalize</option></term>
 <listitem>
 <para>Open the PO file on selected messages in Lokalize (unless <option>nomsg</option> is in effect). Lokalize must be already running with the project that contains the PO file opened.</para>
 </listitem>
 </varlistentry>
 
 </variablelist>
 </para>
 
 </sect3>
 
 </sect2>
 
 <sect2 id="sv-generate-xml">
 <title><command>generate-xml</command></title>
 
 <para><command>generate-xml</command> creates a partial XML representation of a group of PO files.</para>
 
 <!-- TODO: Document the format in more detail. -->
 <para>The output XML format is as follows. Each PO file in the group is represented by a <literal>&lt;po&gt;</literal> element, which contains a list of <literal>&lt;msg&gt;</literal> elements, one for each message. The C<literal>&lt;msg&gt;</literal> element contains the usual parts of a PO message:
 <itemizedlist>
 <listitem>
 <para><literal>&lt;line&gt;</literal>: referent line number of the message</para>
 </listitem>
 <listitem>
 <para><literal>&lt;refentry&gt;</literal>: referent entry number of the message</para>
 </listitem>
 <listitem>
 <para><literal>&lt;status&gt;</literal>: current status of the message (obsolete, translated, untranslated, fuzzy)</para>
 </listitem>
 <listitem>
 <para><literal>&lt;msgid&gt;</literal>: the original text</para>
 </listitem>
 <listitem>
 <para><literal>&lt;msgstr&gt;</literal>: the translation</para>
 </listitem>
 <listitem>
 <para><literal>&lt;msgctxt&gt;</literal>: disambiguating context</para>
 </listitem>
 </itemizedlist>
 If the PO message contains plural forms, they will be represented with <literal>&lt;plural&gt;</literal> subelements of <literal>&lt;msgstr&gt;</literal>.</para>
 
 <para>Parameters:
 <variablelist>
 
 <varlistentry>
 <term><option>xml:<replaceable>file</replaceable></option></term>
 <listitem>
 <para>By default the XML content is written to standard output, and this parameter can be used to send it to a file instead</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term><option>translatedOnly</option></term>
 <listitem>
 <para>Only translated messages are exported to XML (i.e. fuzzy, untranslated and obsolete are ignored).</para>
 </listitem>
 </varlistentry>
 
 </variablelist>
 </para>
 
 </sect2>
 
 <sect2 id="sv-merge-corr-tree">
 <title><command>merge-corr-tree</command></title>
 
 <para>When doing corrections on a copy of PO files tree, it is not possible to easily merge back just the updated translations, because word wrapping in PO file can be different, generating much more difference than it should.</para>
 
 <para>Additionally, tools like <command>pogrep</command> from <ulink url="http://translate.sourceforge.net/wiki/toolkit/index">Translate Toolkit</ulink> will create new partial tree as output, containing matched messages only. <command>merge-corr-tree</command> will help you to merge changes made in that partial tree back into the main tree.</para>
 
 <para>The main PO files tree is the input, and the <option>pathdelta</option> parameter is used to provide the path difference to where the partial correction tree is located.</para>
 
 <para>Parameters:
 <variablelist>
 
 <varlistentry>
 <term><option>pathdelta:<replaceable>search</replaceable>:<replaceable>replace</replaceable></option></term>
 <listitem>
 <para>Specifies that the partial tree is located at path obtained when <literal><replaceable>search</replaceable></literal> is replaced with <literal><replaceable>replace</replaceable></literal> in the input path.</para>
 </listitem>
 </varlistentry>
 
 </variablelist>
 </para>
 
 </sect2>
 
 <sect2 id="sv-normalize-header">
 <title><command>normalize-header</command></title>
 
 <para><command>normalize-header</command> applies <link linkend="hk-normalize-canonical-header">the <literal>normalize/canonical-header</literal> hook</link> to PO file headers.</para>
 
 <para>There are no parameters.</para>
 
 </sect2>
 
 <sect2 id="sv-normctxt-delim">
 <title><command>normctxt-delim</command></title>
 
 <para>In older PO files, disambiguating contexts may be embedded into <varname>msgid</varname> strings, as the initial part of the string delimited from the actual text with predefined substrings, here called the "head" and the "tail". For example, in:
 <programlisting language="po">
 msgid ""
 "_:this-is-context\n"
 "This is original text"
 msgstr "This is translated text"
 </programlisting>
 the head is the underscore-colon sequence (<literal>_:</literal>), and the tail the newline (<literal>\n</literal>). <command>normctxt-delim</command> will convert embedded contexts of the delimiter-type to proper <varname>msgctxt</varname> strings.</para>
 
 <para>Parameters:
 <variablelist>
 
 <varlistentry>
 <term><option>head:<replaceable>string</replaceable></option></term>
 <listitem>
 <para>The head of the delimiter-type embedded context.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term><option>tail:<replaceable>string</replaceable></option></term>
 <listitem>
 <para>The tail of the delimiter-type embedded context.</para>
 </listitem>
 </varlistentry>
 
 </variablelist>
 </para>
 
 </sect2>
 
 <sect2 id="sv-normctxt-sep">
 <title><command>normctxt-sep</command></title>
 
 <para>In older PO files, disambiguating contexts may be embedded into <varname>msgid</varname> strings, as the initial part of the string separated from the actual text by a predefined substring. For example, in:
 <programlisting language="po">
 msgid "this-is-context|This is original text"
 msgstr "This is translated text"
 </programlisting>
 the separator string is the pipe character (<literal>|</literal>). <command>normctxt-sep</command> will convert embedded contexts of the separator-type to proper <varname>msgctxt</varname> strings.</para>
 
 <para>Parameters:
 <variablelist>
 
 <varlistentry>
 <term><option>sep:<replaceable>string</replaceable></option></term>
 <listitem>
 <para>The string that separates the context and the text in separator-type embedded context.</para>
 </listitem>
 </varlistentry>
 
 </variablelist>
 </para>
 
 </sect2>
 
 <sect2 id="sv-remove-fuzzy-comments">
 <title><command>remove-fuzzy-comments</command></title>
 
 <para>Being translator's input, translator comments are copied verbatim to fuzzy messages created on merging with template. Depending on the purpose of translator comments (e.g. see <xref linkend="sec-cmskipcheck"/> for some special types), it may be better to automatically remove some of them from fuzzy messages (and then possibly add them back manually when updating the translation). If run without any parameters <command>remove-fuzzy-comments</command> will do nothing, so one or more parameters need to be given to actually remove any comment.</para>
 
 <para>Parameters:
 <variablelist>
 
 <varlistentry>
 <term><option>all</option></term>
 <listitem>
 <para>Simply all translator comments in fuzzy messages are removed.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term><option>nopipe</option></term>
 <listitem>
 <para>Translator comments containing <link linkend="p-trflag">translator flags</link> (see <xref linkend="sec-cmskipcheck"/>) are removed.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term><option>pattern:<replaceable>regex</replaceable></option></term>
 <listitem>
 <para>Translator comment must match the given regular expression to be removed.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term><option>exclude:<replaceable>regex</replaceable></option></term>
 <listitem>
 <para>Translator comment is removed if it does not match the given regular expression.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term><option>case</option></term>
 <listitem>
 <para>Matching patterns are by default case-insensitive, and this parameter switches to case-sensitivity.</para>
 </listitem>
 </varlistentry>
 
 </variablelist>
 </para>
 
 <para>When several removal criteria are specified, first those other than <option>pattern</option> and <option>exclude</option> are applied in unspecified order, then the <option>pattern</option> match, and finally the <option>exclude</option> match.</para>
 
 </sect2>
 
 <sect2 id="sv-remove-obsolete">
 <title><command>remove-obsolete</command></title>
 
 <para><command>remove-obsolete</command> simply removes all obsolete messages, whether fuzzy or translated, from the PO file.</para>
 
 <para>There are no parameters.</para>
 
 </sect2>
 
 <sect2 id="sv-remove-previous">
 <title><command>remove-previous</command></title>
 
 <para><command>remove-previous</command> removes previous strings, i.e. <literal>#| ...</literal> comments, from messages.</para>
 
 <para>Parameters:
 <variablelist>
 
 <varlistentry>
 <term><option>all</option></term>
 <listitem>
 <para>Previous strings are by default removed only from non-fuzzy messages. This parameter specifies to remove previous strings from all messages, including fuzzy.</para>
 </listitem>
 </varlistentry>
 
 </variablelist>
 </para>
 
 </sect2>
 
 <sect2 id="sv-resolve-aggregates">
 <title><command>resolve-aggregates</command></title>
 
 <para>In its default mode of operation, <command>msgcat(1)</command> produces an aggregate message when in different catalogs it encounters a message with the same key but different translation or translator or extracted comments. A general aggregate message looks like this:
 <programlisting language="po">
 # #-#-#-#-#  po-file-name-1 (project-version-id-1)  #-#-#-#-#
 # manual-comments-1
 # #-#-#-#-#  po-file-name-2 (project-version-id-2)  #-#-#-#-#
 # manual-comments-2
 # ...
 # #-#-#-#-#  po-file-name-n (project-version-id-n)  #-#-#-#-#
 # manual-comments-n
 #. #-#-#-#-#  po-file-name-1 (project-version-id-1)  #-#-#-#-#
 #. automatic-comments-1
 #. #-#-#-#-#  po-file-name-2 (project-version-id-2)  #-#-#-#-#
 #. automatic-comments-2
 #. ...
 #. #-#-#-#-#  po-file-name-n (project-version-id-n)  #-#-#-#-#
 #. automatic-comments-n
 #: source-refs-1 source-refs-2 ... source-refs-n
 #, fuzzy, other-flags
 msgctxt "context"
 msgid "original-text"
 msgstr ""
 "#-#-#-#-#  po-file-name-1 (project-version-id-1)  #-#-#-#-#\n"
 "translated-text-1\n"
 "#-#-#-#-#  po-file-name-2 (project-version-id-2)  #-#-#-#-#\n"
 "translated-text-2\n"
 "..."
 "#-#-#-#-#  po-file-name-n (project-version-id-n)  #-#-#-#-#\n"
 "translated-text-n"
 </programlisting>
 Each message part is aggregated only if different in at least one message
 in the group. For example, extracted comments may be aggregated while translations not.</para>
 
 <para><command>resolve-aggregates</command> is used to resolve aggregate messages of this kind into normal messages, by picking one variant from each aggregated part.</para>
 
 <para>Parameters:
 <variablelist>
 
 <varlistentry>
 <term><option>first</option></term>
 <listitem>
 <para>By default, the picked variant is the one with most occurences, or the first of the several with same number of occurences. If this parameter is issued, the first variant is picked unconditionally.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term><option>unfuzzy</option></term>
 <listitem>
 <para>Aggregated messages are always made fuzzy, leaving no way to determine
 if and which of the original messages were fuzzy. Therefore, by default, the resolved message is left fuzzy too. If, however, it is known beforehand that none of the original messages were fuzzy, resolved messages can be unfuzzied by issuing this parameter.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term><option>keepsrc</option></term>
 <listitem>
 <para>Since there is no information based on which the aggregated source references can be split into originating groups, they are entirely removed unless this parameter is issued.</para>
 </listitem>
 </varlistentry>
 
 </variablelist>
 </para>
 
 </sect2>
 
 <sect2 id="sv-resolve-alternatives">
 <title><command>resolve-alternatives</command></title>
 
 <para><command>resolve-alternatives</command> resolves <emphasis>alternatives directives</emphasis> found in the translation into one of the alternatives.</para>
 
 <para>An alternative directive is a substring of the form <literal>~@/.../.../...</literal>, for example:
 <programlisting language="po">
 msgstr "I see a ~@/pink/white/ elephant."
 </programlisting>
 <literal>~@</literal> is the directive head, which is followed by a character that defines the delimiter of alternatives (can be arbitrary), and then by alternatives themselves. The number of alternatives per directive is not defined by the directive itself, but it is provided as the sieve parameter (i.e. all alternative directives must have some number of alternatives).</para>
 
 <para>Parameters:
 <variablelist>
 
 <varlistentry>
 <term><option>alt:<replaceable>N</replaceable>,<replaceable>M</replaceable>t</option></term>
 <listitem>
 <para>Specifies how to resolve alternatives. <literal><replaceable>N</replaceable></literal> is the index (starting from 1) of the alternative to take from each directive, and <literal><replaceable>M</replaceable></literal> is the number of alternatives per directive. Example: <literal>alt:1,2t</literal>.</para>
 </listitem>
 </varlistentry>
 
 </variablelist>
 </para>
 
 <para>If an alternatives directive is invalid (e.g. too little alternatives), it is reported to standard output. If at least one alternatives directive in the text is not valid, the text is not modifed.</para>
 
 </sect2>
 
 <sect2 id="sv-resolve-entities">
 <title><command>resolve-entities</command></title>
 
 <para>XML entities are substrings of the form <literal>&lt;<replaceable>entityname</replaceable>&gt;</literal>, typically encountered in XML-like text markups, but elsewhere too. They are resolved into underlying, human-readable values at build time (when translated text documents are created) or at run time (in translated user interfaces). Sometimes it may be better to have them resolved already in the PO file itself, and that is what <command>resolve-entities</command> does.</para>
 
 <para>Parameters:
 <variablelist>
 
 <varlistentry>
 <term><option>entdef:<replaceable>file</replaceable></option></term>
 <listitem>
 <para>Path to the file which contains entitiy definitions. It can be repeated to add several files.</para>
 
 <para>Entity definition files are plain text files of the following format:
 <programlisting>
 &lt;!-- This is a commment. --&gt;
 &lt;!ENTITY name1 'value1'&gt;
 &lt;!ENTITY name2 'value2'&gt;
 &lt;!ENTITY name3 'value3'&gt;
 ...
 </programlisting>
 </para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term><option>ignore:<replaceable>entitynames</replaceable></option></term>
 <listitem>
 <para>Entities which should be ignored during resolution. Standard XML entities (<literal>&amp;lt;</literal>, <literal>&amp;gt;</literal>, <literal>&amp;apos;</literal>, <literal>&amp;quot;</literal>, <literal>&amp;amp;</literal>) are ignored by default.</para>
 </listitem>
 </varlistentry>
 
 </variablelist>
 </para>
 
 </sect2>
 
 <sect2 id="sv-set-header">
 <title><command>set-header</command></title>
 
 <para>Sometimes a PO header field or comment needs to be updated in many PO files at once, and <command>set-header</command> serves that purpose.</para>
 
 <para>Parameters for setting and removing header fields:
 <variablelist>
 
 <varlistentry>
 <term><option>field:<replaceable>name</replaceable>:<replaceable>value</replaceable></option></term>
 <listitem>
 <para>Set the field with given name to given value. This parameter can be repeated to set several fields in one run.</para>
 
 <para>By default, <option>field</option> will actually set the field only if it is already present in the header. To add the field if not present, the <option>create</option> parameter must be issued as well. If the field is being added, parameters <option>after</option> and <option>before</option> can be used to specify where to insert it, or else the new field is appended at the end of the header. If the field is present but not positioned according to <option>after</option> and <option>before</option>, the <option>reorder</option> parameter can be issued to move the field within the header.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term><option>create</option></term>
 <listitem>
 <para>The field should be added if it is not present in the header.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term><option>after</option></term>
 <listitem>
 <para>When a field is added, it should be inserted after this field.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term><option>before</option></term>
 <listitem>
 <para>When a field is added, it should be inserted before this field.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term><option>reorder</option></term>
 <listitem>
 <para>If the field is present, but it is in the wrong place according to <option>after</option> and <option>before</option>, this parameter will cause it to be reinserted in proper place.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term><option>remove:<replaceable>field</replaceable></option></term>
 <listitem>
 <para>Remove the field with this name. If there are several fileds of that name, all are removed.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term><option>removerx:<replaceable>regex</replaceable></option></term>
 <listitem>
 <para>Remove all fields matched by the given regular expression.</para>
 </listitem>
 </varlistentry>
 
 </variablelist>
 </para>
 
 <para>Parameters for setting and removing header comments:
 <variablelist>
 
 <varlistentry>
 <term><option>title:<replaceable>value</replaceable></option></term>
 <listitem>
 <para>Set the title comment to the given value. It can be repeated, since the title can be composed of multiple comment lines.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term><option>rmtitle</option></term>
 <listitem>
 <para>Remove title comments.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term><option>copyright:<replaceable>value</replaceable></option></term>
 <listitem>
 <para>Set the copyright comment to the given value.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term><option>rmcopyright</option></term>
 <listitem>
 <para>Remove the copyright comment.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term><option>license:<replaceable>value</replaceable></option></term>
 <listitem>
 <para>Set the license comment to the given value.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term><option>rmlicense</option></term>
 <listitem>
 <para>Remove the license comment.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term><option>author:<replaceable>value</replaceable></option></term>
 <listitem>
 <para>Set the author comment to the given value. It can be repeated, since there may be more authors (i.e. translators).</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term><option>rmauthor</option></term>
 <listitem>
 <para>Remove author comments.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term><option>comment:<replaceable>value</replaceable></option></term>
 <listitem>
 <para>Set the free comment to the given value. It can be repeated, since there can be any number of free comment lines.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term><option>rmcomment</option></term>
 <listitem>
 <para>Remove free comments.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term><option>rmallcomm</option></term>
 <listitem>
 <para>Remove all header comments.</para>
 </listitem>
 </varlistentry>
 
 </variablelist>
 </para>
 
 <para>Note that all existing comments of given type are removed before setting the new ones, i.e. the new comments are <emphasis>not</emphasis> appended to the existing. For example, if single <option>author</option> parameter is issued, with a translator name and email address as value, this one translator will replace all existing translators in the header comments.</para>
 
 <para>Comment values are checked for some minimal consistency, e.g. author comments must contain email addresses, licence comments the word "licence", etc.</para>
 
 <para>Value strings (both of fields and comments) may contain %-directives,
 which are expanded to catalog-dependent substrings prior to setting the value.
 Currently available directive are:
 <itemizedlist>
 <listitem>
 <para><literal>%poname</literal>: PO domain name (equal to file name without <filename>.po</filename> extension)</para>
 </listitem>
 </itemizedlist>
 If literal % character is needed (e.g. when setting the <literal>Plural-Forms</literal> field), it can be escaped by doubling it, <literal>%%</literal>. The directive can also be given inside braces, as <literal>%{...}</literal> when it would be ambiguous otherwise.</para>
 
 </sect2>
 
 <sect2 id="sv-stats">
 <title><command>stats</command></title>
 
 <para><command>stats</command> collects statistics on PO files, such as message and word counts, and more. Statistics can be presented in several ways and on several levels.</para>
 
 <para>Parameters:
 <variablelist>
 
 <varlistentry>
 <term><option>accel:<replaceable>characters</replaceable></option></term>
 <listitem>
 <para>Characters to consider as <link linkend="sec-poaccel">accelerator markers</link>, to remove them when splitting text to count words. If not given, they may be read from PO files (see <link linkend="hdr-x-accelerator-marker"><literal>X-Acclerator-Marker</literal></link> in <xref linkend="sec-cmheader"/>), or else some usual accelerator marker characters are removed.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term><option>detail</option></term>
 <listitem>
 <para>In table views, by default only message, word, and character counts are given. This parameter requests additional derived data, such as expansion factors (ratio of words in translation to words in original), number of words per message, etc.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term><option>incomplete</option></term>
 <listitem>
 <para>When run over a collection of PO files, all non-fully translated PO files are listed separately, with very brief statistics of incompleteness.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term><option>incompfile:<replaceable>file</replaceable></option></term>
 <listitem>
 <para>Write a file with paths of all non-fully translated PO files, one per line. This file can then be fed with <option>-f</option>/<option>--from-files</option> back to <command>posieve</command> or another script, to process only incomplete PO files.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term><option>templates:<replaceable>search</replaceable>:<replaceable>replace</replaceable></option></term>
 <listitem>
 <para>If there exists both a directory with translated PO files and with POT (template) files, and not every POT file has the corresponding PO file, this parameter can be used to count POT files without PO counterpart as fully untranslated in statistics. Value to the parameter are two strings separated by colon: the first string will be searched for in directory paths of processed PO files, and replaced with the second string to construct corresponding directory paths of POT files. For example:
 <programlisting language="bash">
 $ cd $MYTRANSLATIONS
 $ ls
 my_lang  templates
 $ posieve stats -s templates:my_lang:templates my_lang/
 </programlisting>
 </para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term><option>minwords:<replaceable>number</replaceable></option></term>
 <listitem>
 <para>Only messages with at least this many words (in any of original or translation strings) are counted into statistics.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term><option>maxwords:<replaceable>number</replaceable></option></term>
 <listitem>
 <para>Only messages with at most this many words (in any of original or translation strings) are counted into statistics.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term><option>lspan:<replaceable>start</replaceable>:<replaceable>end</replaceable></option></term>
 <listitem>
 <para>Only messages with referent line numbers (line number of <varname>msgid</varname>) in this range are counted into statistics. The starting line is included in the range, the ending line is not. If start is omitted (e.g. <option>lspan::500</option>) it is assumed 0, and if end is omitted (e.g. <option>lspan:300</option> or <option>lspan:300:</option>) it is assumed the total number of lines.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term><option>espan:<replaceable>start</replaceable>:<replaceable>end</replaceable></option></term>
 <listitem>
 <para>Only messages with entry numbers (as reported by PO editors) in this range are counted into statistics. Same boundary inclusion and omission rules as for <option>lspan</option> apply; e.g. <option>espan:4:8</option> means to count messages with entry numbers 4, 5, 6, and 7.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term><option>branch:<replaceable>branch</replaceable></option></term>
 <listitem>
 <para>Only messages from given branch are counted into statistics (<link linkend="ch-summit">summit</link>). Several branches may be given as comma-separated list.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term><option>bydir</option></term>
 <listitem>
 <para>Statistics is broken by directories, that is a report is displayed for each group of PO files in the same directory (and not below it). More usually used with bar displays than with tabular displays.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term><option>byfile</option></term>
 <listitem>
 <para>Statistics is broken by files, that is a report is displayed for each PO file. Usually used with bar displays.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term><option>msgbar</option></term>
 <listitem>
 <para>Instead of a table with detailed statistics, only message counts are shown, accompanied with a text-art bar. Mostly useful in combination with <option>bydir</option> and <option>byfile</option>.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term><option>wbar</option></term>
 <listitem>
 <para>Like <option>msgbar</option>, but to have word instead of message counts.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term><option>msgfmt</option></term>
 <listitem>
 <para>Like <option>msgbar</option>, but a msgfmt-style plain-text summary is printed.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term><option>absolute</option></term>
 <listitem>
 <para>Bar displays (on <option>msgbar</option> and <option>wbar</option>) are normaly relative, meaning that when <option>byfile</option> or <option>bydir</option> is in effect, each bar is of same length. This parameter makes bars scaled to sizes of PO files or directories. For example, if <option>msgbar</option> and <option>byfile</option> are issued, then the bar of a PO file with twice as many messages as another PO file will be twice as long.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term><option>ondiff</option></term>
 <listitem>
 <para>Fuzzy messages are often very easy to correct (e.g. a typo fixed), which may make their word count misleading when estimating translation effort. This can be amended by issuing this parameter, to split word and character counts of fuzzy messages into translated and untranslated counts. The split is based on the difference ratio between current and previous original text, and a threshold. If the difference ratio is larger than the threshold, everything is counted as untranslated. The fuzzy count is left at zero. If previous original text is missing, the correction is not made, and counts are assigned to fuzzy as usual.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term><option>mincomp:<replaceable>fraction</replaceable></option></term>
 <listitem>
 <para>Only those PO files which have translation completeness (measured by the ratio of translated to all messages, excluding obsolete) equal to or higher than the given fraction are included into statistics. This is especially useful when for each new template an empty PO file is automatically produced (instead of translators having to start work from a template), to include into statistics only those files which have actually seen some translation (using a small non-zero number for the fraction, e.g. <option>fraction:1e-6</option>).</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term><option></option></term>
 <listitem>
 <para>The hook to modify the translation before splitting it to count words and characters (see <xref linkend="sec-cmhooks"/>). The hook type must be F1A. The parameter can be repeated to add several hooks, which are then applied in the order of specification.</para>
 </listitem>
 </varlistentry>
 
 </variablelist>
 </para>
 
 <sect3 id="sec-svstemctxt">
 <title>Handling Embedded Contexts</title>
 
 <para>Some older PO files will have disambiguating contexts embedded into the <varname>msgid</varname> string, instead of using the newer standard <varname>msgctxt</varname> string. There are several customary ways in which this is done, but in general it depends on the translation environment where such PO files are used.</para>
 
 <para>Embedded contexts will skew the statistics. Pology contains several sieves for converting embedded contexts into <varname>msgctxt</varname> contexts, named <command>normctxt-*</command>. When statistics on such PO files is computed, a sieve chain should be used in which the <command>stats</command> sieve is preceeded by the context conversion sieve. For example, if the embedded context starts the <varname>msgid</varname> and ends with <literal>|</literal>, statistics should be computed with:
 <programlisting language="bash">
 $ posieve --no-sync normctxt-sep,stats -s sep:'|' ...
 </programlisting>
 Note that <command>normctxt-*</command> sieves, since they modify messages, would by default cause PO files to be modified on disk. Option <option>--no-sync</option> is therefore issued to prevent modifications to sieved files.</para>
 
 </sect3>
 
 <sect3 id="sec-svstoutleg">
 <title>Output Legend</title>
 
 <para>The default output from <command>stats</command> is a table where rows present statistics for a category of messages, and columns the particular categories of data:
 <programlisting language="bash">
 $ posieve stats frobaz/
 -              msg  msg/tot  w-or  w/tot-or  w-tr  ch-or  ch-tr
 translated     ...    ...    ...     ...     ...    ...    ...
 fuzzy          ...    ...    ...     ...     ...    ...    ...
 untranslated   ...    ...    ...     ...     ...    ...    ...
 total          ...    ...    ...     ...     ...    ...    ...
 obsolete       ...    ...    ...     ...     ...    ...    ...
 </programlisting>
 The <literal>total</literal> row is the sum of <literal>translated</literal>, <literal>fuzzy</literal>, and <literal>untranslated</literal> rows, whereas <literal>obsolete</literal> row is excluded. The columns are as follows:
 <itemizedlist>
 <listitem>
 <para><literal>msg</literal>: number of messages</para>
 </listitem>
 <listitem>
 <para><literal>msg/tot</literal>: percentage of messages relative to total</para>
 </listitem>
 <listitem>
 <para><literal>w-or</literal>: number of words in the original</para>
 </listitem>
 <listitem>
 <para><literal>w/tot-or</literal>: percentage of words in the original relative to total</para>
 </listitem>
 <listitem>
 <para><literal>w-tr</literal>: number of words in the translation</para>
 </listitem>
 <listitem>
 <para><literal>ch-or</literal>: number of characters in original</para>
 </listitem>
 <listitem>
 <para><literal>ch-tr</literal>: number of characters in the translation</para>
 </listitem>
 </itemizedlist>
 </para>
 
 <para>The output with <option>detail</option> parameter in effect is the same as default, with several columns of derived data appended to the table:
 <itemizedlist>
 <listitem>
 <para><literal>w-ef</literal>: word expansion factor (increase in words from the original to the translation)</para>
 </listitem>
 <listitem>
 <para><literal>ch-ef</literal>: character expansion factor (increase in characters from the original to the translation)</para>
 </listitem>
 <listitem>
 <para><literal>w/msg-or</literal>: average of number words per message in the original</para>
 </listitem>
 <listitem>
 <para><literal>w/msg-tr</literal>: average number of words per message in the translation</para>
 </listitem>
 <listitem>
 <para><literal>ch/w-or</literal>: average number of characters per message in the original</para>
 </listitem>
 <listitem>
 <para><literal>ch/w-tr</literal>: average number of characters per message in the translation</para>
 </listitem>
 </itemizedlist>
 </para>
 
 <para>If any of the sieve parameters that restrict or modify counting (such as <option>ondiff</option>, <option>lspan</option>, etc.) have been issued, this is indicated in the output by a <literal>modifiers: ...</literal> line:
 <programlisting language="bash">
 $ posieve stats -s maxwords:5 -s ondiff frobaz/
 (...the statistics table...)
 modifiers: at most 5 words and scaled fuzzy counts
 </programlisting>
 </para>
 
 <para>When the <option>incomplete</option> parameter is given, the statistics table is followed by a table of non-fully translated PO files, with counts of fuzzy and untranslated messages and words:
 <programlisting language="bash">
 $ posieve stats -s incomplete frobaz/
 (...the overall statistics table...)
 catalog              msg/f   msg/u   msg/f+u   w/f   w/u   w/f+u
 frobaz/foxtrot.po        0      11        11     0   123     123
 frobaz/november.po      19      14        33    85    47     132
 frobaz/sierra.po        22       0        22   231     0     231
 </programlisting>
 In the column names, <literal>msg/*</literal> and <literal>w/*</literal> stand for messages and words; <literal>*/f</literal>, <literal>*/u</literal>, and <literal>*/f+u</literal> stand for fuzzy, untranslated, and the two summed.</para>
 
 <para>When parameters <option>msgbar</option> or <option>wbar</option> are in effect, statistics is presented in the form of a text-art bar, giving visual relation between numbers of translated, fuzzy, and untranslated messages or words:
 <programlisting language="bash">
 $ posieve stats -s wbar frobaz/
 4572/1829/2533 w-or |¤¤¤¤¤¤¤¤¤¤¤¤¤¤¤¤¤¤¤×××××××××············|
 </programlisting>
 A typical condensed overview of translation state is obtained by:
 <programlisting language="bash">
 $ posieve stats -s byfile -s msgbar frobaz/
 frobaz/foxtrot.po   34/ -/11 msgs |¤¤¤¤¤¤¤¤¤¤¤¤¤¤¤·····|
 frobaz/november.po  58/19/14 msgs |¤¤¤¤¤¤¤¤¤¤¤×××××····|
 frobaz/sierra.po    65/22/ - msgs |¤¤¤¤¤¤¤¤¤¤¤¤¤¤××××××|
 (overall)          147/41/25 msgs |¤¤¤¤¤¤¤¤¤¤¤¤¤××××···|
 </programlisting>
 Note that while message counts are the classic for bar overviews (<option>msgbar</option>), you are probably better off looking at word counts (<option>wbar</option>) instead, because word counts represent more closely the amount of work needed to complete the translation. Rounding of fractions for bars is such that as long as there is at least one fuzzy or untranslated message (or word), the bar will show one incomplete cell.</para>
 
 </sect3>
 
 <sect3 id="sec-svstnotes">
 <title>Notes on Counting</title>
 
 <para>Word and character counts for a message string are obtained by processing it in the following order:
 <itemizedlist>
 <listitem>
 <para>Accelerator markers are removed.</para>
 </listitem>
 <listitem>
 <para>Text markup is eliminated (e.g. XML-like tags).</para>
 </listitem>
 <listitem>
 <para>Other special substrings, such as format directives, are also eliminated (e.g. <literal>%s</literal> in messages with <literal>c-format</literal> flag).</para>
 </listitem>
 <listitem>
 <para>Text is split into words by taking all contiguous sequences of "word characters", which include letters, numbers, and underscore.</para>
 </listitem>
 <listitem>
 <para>All words not starting with a letter are eliminated.</para>
 </listitem>
 <listitem>
 <para>Words that remain are counted into statistics. Whitespace is not included in character count.</para>
 </listitem>
 </itemizedlist>
 </para>
 
 <para>In plural messages, counts for the original are the average of <varname>msgid</varname> and <varname>msgid_plural</varname> strings, and likewise the average of all <varname>msgstr</varname> strings for the translation. In this way, the comparative statistics between the original and the translation is not skewed for languages that have more or less than two plural forms.</para>
 
 </sect3>
 
 </sect2>
 
 <sect2 id="sv-tag-untranslated">
 <title><command>tag-untranslated</command></title>
 
 <para>Some translators like to edit PO files with a plain text editor, which may provide no special support for editing PO files, other than perhaps PO syntax highlighting. In this scenario, <command>tag-untranslated</command> can be used to equip untranslated messages with <literal>untranslated</literal> flag, so that they can be easily looked up in the editor.</para>
 
 <para>Since <literal>untranslated</literal> is not one of defined PO flags, it will be lost if the PO file is merged with the template. This is intentional: the only purpose of this flag is to facilitate immediate editing of the PO file, and you may miss to remove some of them while editing. There is no reason for <literal>untranslated</literal> flags to persist in that case. Also, if the flag is not removed after the message has been translated, a subsequent run of this sieve will remove the flag.</para>
 
 <para>Parameters:
 <variablelist>
 
 <varlistentry>
 <term><option>strip</option></term>
 <listitem>
 <para>Instead of being added, <literal>untranslated</literal> flags are stripped. This is useful when you had no time to translate all messages but you want to send the PO file away.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term><option>wfuzzy</option></term>
 <listitem>
 <para><literal>untranslated</literal> flags are added to fuzzy messages as well. This can be useful to be able to jump in the text editor through all incomplete message by just giving <userinput>, untranslated</userinput><footnote>
 <para>Alternatively, if the editor provides regular expressions for searches, you can search for <userinput>, fuzzy|, untranslated</userinput>.</para>
 </footnote>, or when the set of messages to be updated has been limited somehow (e.g. by the <option>branch</option> parameter).</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term><option>branch:<replaceable>branch</replaceable></option></term>
 <listitem>
 <para>Tag only untranslated messages from given branch (<link linkend="ch-summit">summit</link>). Several branches may be given as comma-separated list.</para>
 </listitem>
 </varlistentry>
 
 </variablelist>
 </para>
 
 </sect2>
 
 <sect2 id="sv-unfuzzy-context-only">
 <title><command>unfuzzy-context-only</command></title>
 
 <para>Sometimes the message is made fuzzy during merging only due to change in the <varname>msgctxt</varname> string, or its addition or removal. Some translators and languages may be less dependent on contexts than the other, or they may be in a hurry prior to the release of the translation, and then <command>unfuzzy-context-only</command> can be used to unfuzzy these messages in which only the context was modified. This state can be detected by comparing the current and the previous strings in the fuzzy message, i.e. the PO file must have been merged with <option>--previous</option> option to <command>msgmerge</command>.</para>
 
 <para>Parameters:
 <variablelist>
 
 <varlistentry>
 <term><option>noreview</option></term>
 <listitem>
 <para>By default, unfuzzied messages will also be given a translator comment
 with <literal>unreviewed-context</literal> string, so that you may find and review these messages at a later time. This parameter will prevent the addition of such comment, but it is usually safer to review automatically unfuzzied messages when you find the time.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term><option>eqmsgid</option></term>
 <listitem>
 <para>Sometimes a lot of messages in the code may be semi-automatically equipped with contexts (e.g. to group items by a common property), and then it may be necessary to review only those messages which got split into two or more messages due to newly added contexts. This parameter may be issued to specifically report all translated messages which have the their <varname>msgid</varname> string equal to an unfuzzied message, including unfuzzied messages themselves. Depending on exactly what kind of contexts have been added, the <option>noreview</option> parameter may be useful here as well.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term><option>lokalize</option></term>
 <listitem>
 <para>Open the PO file on reported messages in Lokalize. Lokalize must be already running with the project that contains the PO file opened.</para>
 </listitem>
 </varlistentry>
 
 </variablelist>
 </para>
 
 </sect2>
 
 <sect2 id="sv-unfuzzy-ctxmark-only">
 <title><command>unfuzzy-ctxmark-only</command></title>
 
 <para><command>unfuzzy-ctxmark-only</command> has a similar but less wide effect compared to the <command>unfuzzy-context-only</command> sieve. It unfuzzies a message only if the only change that caused fuzzyness is in a specific part of <varname>msgctxt</varname> string, the <emphasis>UI context marker</emphasis>.</para>
 
 <para>UI context markers are en element of <ulink url="http://techbase.kde.org/Development/Tutorials/Localization/i18n_Semantics">KUIT markup</ulink> (KDE user interface text), which state more formally the user interface context in which the text given by the PO message is used. This may be important for translation, since style guidelines will typically somewhat depend on where in the UI the text is seen. For example, there may be two messages in the code which have exactly the same text in English, but one is used as a menu item, and the other as a dialog title; with KUIT, they would be marked as:
 <programlisting language="po">
 msgctxt "@action:inmenu File"
 msgid "Export as HTML"
 msgstr ""
 ⁠
 msgctxt "@title:window"
 msgid "Export as HTML"
 msgstr ""
 </programlisting>
 The UI context marker here is the leading part of <varname>msgctxt</varname>, starting with <literal>@...</literal> and ending with first whitespace. <command>unfuzzy-ctxmark-only</command> will unfuzzy the message if only this marker has changed (or was added or removed), but not if the change was in the rest of the context (after the first whitespace).</para>
 
 <para>Parameters:
 <variablelist>
 
 <varlistentry>
 <term><option>noreview</option></term>
 <listitem>
 <para>See the same-name parameter of <command>unfuzzy-ctxmark-only</command>. Using it here is probably somewhat safer, but this in general it depends on translation style guidelines.</para>
 </listitem>
 </varlistentry>
 
 </variablelist>
 </para>
 
 </sect2>
 
 <sect2 id="sv-unfuzzy-inplace-only">
 <title><command>unfuzzy-inplace-only</command></title>
 
 <para>Some text markups may have a "permissible" or "sloppy" mode, where some tags do not have to be explicitly terminated. The typical example is HTML, where <literal>&lt;br&gt;</literal>, <literal>&lt;hr&gt;</literal>, etc. do not have to be written as <literal>&lt;br/&gt;</literal>. (This is unlike XHTML, which is an XML instance and therefore strict in this respect.) When this permissible markup was used in the code, a programmer revisiting that code at a later time may consider it a poor style, and go about fixing it. This may cause some messages in the PO file to become fuzzy. <command>unfuzzy-inplace-only</command> will recognize some of these situations in a fuzzy message (by comparing the current and previous strings) and automatically modify the translation accordingly and unfuzzy the message.</para>
 
 <para>There are no parameters.</para>
 
 </sect2>
 
 <sect2 id="sv-unfuzzy-qtclass-only">
 <title><command>unfuzzy-qtclass-only</command></title>
 
 <para>PO messages obtained by conversion from Qt Linguist translation files can contain in the <varname>msgctxt</varname> an automatically extracted C++ class name, referring to the class where the message is located in the code. In the following two example messages, the C++ class name is the text before the <literal>|</literal> character:
 <programlisting language="po">
 #: ui/configdialog.cpp:50
 msgctxt "Sonnet::ConfigDialog|"
 msgid "Spell Checking Configuration"
 msgstr ""
 
 #: core/loader.cpp:206
 #, qt-format
 msgctxt "Sonnet::Loader|%1 = language name, %2 = country name"
 msgid "%1 (%2)"
 msgstr ""
 </programlisting>
 If the programmer later changes a class name in the code, all messages inside that class will become fuzzy. The <command>unfuzzy-qtclass-only</command> sieve can be used to unfuzzy such messages, by verifying that the only difference between the old and the new message is in the part of <varname>msgctxt</varname> before the <literal>|</literal> character. For this to work, the PO file must have been merged with <option>--previous</option> option to <command>msgmerge</command>.</para>
 
 <para>There are no parameters.</para>
 
 </sect2>
 
 <sect2 id="sv-update-header">
 <title><command>update-header</command></title>
 
 <para>When translation on a PO file starts for the first time, or when a previously translated PO file is being updated after merging, <command>update-header</command> can be used to automatically set and update PO header fields to proper values. The revision date is taken as current, while other pieces of information are read from the user configuration (see <xref linkend="sec-cmconfig"/>). Note that this sieve is normally only of use when you are translating with a plain text editor, while dedicated PO editors should do this automatically when the PO file is saved after editing.</para>
 
 <para>Parameters:
 <variablelist>
 
 <varlistentry>
 <term><option>proj:<replaceable>projectid</replaceable></option></term>
 <listitem>
 <para>The ID of the project to which the PO files to be updated belong. This ID is used to construct the name of the configuration section as <literal>[project-<replaceable>projectid</replaceable>]</literal>, which contains the project data fields. Also used are the fields from the <literal>[user]</literal>, whenever they are not overriden in project's section. See <xref linkend="sec-cmcfguser"/> and <xref linkend="sec-cmcfgproj"/>.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term><option>init</option></term>
 <listitem>
 <para>By default, the sieve tries to detect if the header has been initialized before or not, because it differs somewhat what should be changed in the header on initialization and on update. This parameter can be issued to unconditionally treat the header as not initialized, i.e. overwrite any existing content.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term><option>onmod</option></term>
 <listitem>
 <para>The header should be updated only if the PO file was otherwise modified. This parameter makes sense only in a sieve chane, when this sieve is preceded by a potentially modifying sieve.</para>
 </listitem>
 </varlistentry>
 
 </variablelist>
 </para>
 
 <para>An example of a user configuration appropriate for this sieve would be:
 <programlisting language="ini">
 [user]
 name = Chusslove Illich
 original-name = Часлав Илић
 email = caslav.ilic@gmx.net
 po-editor = Kate
 
 [project-kde]
 language = sr
 language-team = Serbian
 team-email = kde-i18n-sr@kde.org
 plural-forms = nplurals=4; plural=n==1 ? 3 : n%%10==1 &amp;&amp; \
                n%%100!=11 ? 0 : n%%10>=2 &amp;&amp; n%%10&lt;=4 &amp;&amp; \
                (n%%100&lt;10 || n%%100>=20) ? 1 : 2;
 </programlisting>
 Note that percent characters in the <literal>plural-forms</literal> field are escaped by doubling, because single <literal>%</literal> in configuration has special meaning. Also note splitting into several lines by trailing <literal>\</literal> (only for better looks, since configuration lines can be arbitrarily long).</para>
 
 </sect2>
 
 <sect2 id="sv-fr:setUbsp">
 <title><command>fr:setUbsp</command></title>
 
 <para>In French language, some punctuation characters are separated with an unbreakable space from the preceding word. This is unlike in English, so unwary French translators sometimes miss to add the required unbreable space after or before such punctuation when translating from English. <command>fr:setUbsp</command> will heuristically detect such places and insert an unbreakable space.</para>
 
 <para>There are no parameters.</para>
 
 </sect2>
 
 <sect2 id="sv-fr:setApostrophe">
 <title><command>fr:setApostrophe</command></title>
 
 <para>In French language, the <literal>’</literal> character is the apostrophe. A rule in the French team is to use directly <literal>'</literal>. <command>fr:setApostrophe</command> will detect the <literal>’</literal> and transform them to <literal>'</literal>.</para>
 
 <para>There are no parameters.</para>
 
 </sect2>
 
 <sect2 id="sv-ru:fill-doc-date-kde">
 <title><command>ru:fill-doc-date-kde</command></title>
 
 <para>Each translation file for a docbook in KDE has a string for documentation last update date in the format 'yyyy-mm-dd'. This sieve automatically translated those strings into Russian. The sieve uses <command>date</command> command in order to change date formatting. But Russian names of months are hardcoded, so that you do not need to set up Russian locale to use the sieve.</para>
 
 <para>There are no parameters.</para>
 
 </sect2>
 
 </sect1>
 
 <!-- ======================================== -->
 <sect1 id="sec-svexternal">
 <title>Using External Sieves</title>
 
 <para>Each internal sieve is a single Python file in <filename>sieve/</filename> subdirectory (and in <filename>lang/<replaceable>langcode</replaceable>/sieve/</filename> for language-specific sieves). The Python file is named like the sieve, only with hyphens replaced with underscores and with <filename>.py</filename> extension. <command>posieve</command> therefore knows how to find which file to execute when an internal sieve name is given as its first argument.</para>
 
 <para>However, instead of an internal sieve name, the first argument to <command>posieve</command> can also be an explicit path (relative or absolute) to a Python file which implements a sieve. Explicit paths can also be part of a sieve chain, mixed with internal sieve names. This is all there is to running external sieves; see <xref linkend="sec-prsieves"/> for instructions on how to write one.</para>
 
 </sect1>
 
 </chapter>