'l10n-support/pology/doc/user'

[prev in list] [next in list] [prev in thread] [next in thread] 

List:       kde-commits
Subject:    l10n-support/pology/doc/user
From:       Chusslove Illich <caslav.ilic () gmx ! net>
Date:       2010-08-31 22:33:19
Message-ID: 20100831223319.98B6AAC857 () svn ! kde ! org
[Download RAW message or body]

SVN commit 1170444 by ilic:

Documentation updates.

 M  +3 -1      common.docbook  
 M  +249 -13   sieving.docbook  


--- trunk/l10n-support/pology/doc/user/common.docbook #1170443:1170444
@@ -579,7 +579,7 @@
 
 <!-- ======================================== -->
 <sect1 id="sec-cmhooks">
-<title>Filtering Hooks</title>
+<title>Processing Hooks</title>
 
 <para>Pology enables the user to insert special processing elements, called \
<emphasis>hooks</emphasis>, at many places in the processing chain. Hooks are Python \
functions with certain prescribed input, output, and behavior. Depending on the exact \
combination of these three ingredients, there are various <emphasis>hook \
types</emphasis>. Finally, some hooks can be adapted to a given context through their \
<emphasis>hook factories</emphasis>. Pology defines many hooks internally, and users \
can add their own external hooks.</para>  
@@ -800,6 +800,8 @@
 <term><ulink url="&ap;bpatterns&am;bad_patterns_msg_sp"><literal>bpatterns/bad-patterns-msg-sp</literal></ulink> \
(V4A)</term>  <listitem>
 <para>Detects unwanted patterns in text, by regular expression matching. Patterns \
can be specified either as direct arguments, or listed in file given as \
argument.</para> +
+<caution><para>This hook is deprecated. Use <link linkend="sec-lgrules">validation \
rules</link> instead, which are much a richer method of defining and checking for \
problems.</para></caution>  </listitem>
 </varlistentry>
 
--- trunk/l10n-support/pology/doc/user/sieving.docbook #1170443:1170444
@@ -315,41 +315,284 @@
 <sect1 id="sec-svinternal">
 <title>Internal Sieves</title>
 
-<para></para>
+<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. Optional 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></para>
+<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></para>
+<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>
 
-<para></para>
+<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>
+
+<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> +
 </sect2>
 
 <sect2 id="sv-check-grammar">
 <title><command>check-grammar</command></title>
 
-<para></para>
+<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-rules">
 <title><command>check-rules</command></title>
 
-<para></para>
+<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 each \
PO file in turn, and if not found there either, an 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 environment 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 accelerator markers. 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 and obvious) XML \
format.</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>).</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 failed messages in Lokalize.</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>
+# skip-rule: <replaceable>ruleid1</replaceable>, <replaceable>ruleid2</replaceable>, \
... +</programlisting>
+</para>
+
 </sect2>
 
 <sect2 id="sv-check-spell">
@@ -560,13 +803,6 @@
 
 </sect2>
 
-<sect2 id="sv-es:setUbsp">
-<title><command>es:setUbsp</command></title>
-
-<para></para>
-
-</sect2>
-
 <sect2 id="sv-fr:setUbsp">
 <title><command>fr:setUbsp</command></title>
 


[prev in list] [next in list] [prev in thread] [next in thread]
Configure | About | News | Add a list | Sponsored by KoreLogic