'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