From kde-commits Tue Aug 31 22:33:19 2010 From: Chusslove Illich Date: Tue, 31 Aug 2010 22:33:19 +0000 To: kde-commits Subject: l10n-support/pology/doc/user Message-Id: <20100831223319.98B6AAC857 () svn ! kde ! org> X-MARC-Message: https://marc.info/?l=kde-commits&m=128329379515151 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 @@ -Filtering Hooks +Processing Hooks Pology enables the user to insert special processing elements, called hooks, 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 hook types. Finally, some hooks can be adapted to a given context through their hook factories. Pology defines many hooks internally, and users can add their own external hooks. @@ -800,6 +800,8 @@ bpatterns/bad-patterns-msg-sp (V4A) Detects unwanted patterns in text, by regular expression matching. Patterns can be specified either as direct arguments, or listed in file given as argument. + +This hook is deprecated. Use validation rules instead, which are much a richer method of defining and checking for problems. --- trunk/l10n-support/pology/doc/user/sieving.docbook #1170443:1170444 @@ -315,41 +315,284 @@ Internal Sieves - +This section describes the sieves which are contained in Pology distribution and provides instruction for their use. +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 ([...]) in the header. + <command>apply-filter</command> - +apply-filter is used to pipe translation through one or several hooks (see ). The hooks may modify the translation, validate it, or do something else. More precisely, the following hook types are applicable: + + +F1A, F3A, F3C, to modify the translation and write changes back to the PO file; + + +V1A, V3A, V3C, to validate the translation, with standard validation output (highlighted spans and problem messages); + + +S1A, S3A, S3C, for any side-effect processing on translation (but no modification). + + + +Parameters: + + + + + +The hook specification. Can be repeated to add several hooks, which are then applied in the order of specification. + + + + + + +Report every modified message to standard output. (For validation hooks, message is automatically reported if not valid.) + + + + + + <command>apply-header-filter</command> - +apply-header-filter is the counterpart to apply-filter to operate on headers instead of messages. Here the applicable hook types are accordingly F4B, V4B, S4B. +Parameters: + + + + + +The hook specification. Can be repeated to add several hooks, which are then applied in the order of specification. + + + + + + <command>bad-patterns</command> - +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. bad-patterns can apply such patterns to translation, either as plain substring matching or regular expressions. Patterns can be given as parameters, or more conveniently, read from files. +Parameters: + + + + + +The pattern to search for. Can be repeated to search for several patterns. + + + + + + +Read patterns to search for from the file. Each line contains one pattern. If line starts with #, 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 [...] regex operator. This parameter can be repeated to read patterns from several files. + + + + + + +By default patterns are treated as plain substrings. This parameter requests to treat patterns as regular expressions. + + + + + + +By default patterns are case-sensitive. This parameter make them case-insensitive. + + + + + + +This sieve is deprecated. Use check-rules instead, which applies Pology's validation rules. + <command>check-grammar</command> - +check-grammar checks translation with LanguageTool, an open source grammar and style checker (http://www.languagetool.org/). LanguageTool supports a number of languages to greater or smaller extent, which you can check on its web site. +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. + +Parameters: + + + + + +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. + + + + + [localhost] + +Name of the host where the LanguageTool server is running. The default value of localhost means that it is running on the same computer where the sieve is run. + + + + + [8081] + +TCP port of the host on which the LanguageTool server listens for queries. + + + + + + <command>check-rules</command> - +check-rules applies language- and project-dependent Pology validation rules to translation. See for detailed discussion on writing and applying rules. +Parameters: + + + + + +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. + + + + + + +The language environment for which to apply the rules (see ). 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 X-Environment in ). + + + + + + +When language environment is given, only the rules explicitly belonging to it are applied, while general rules for the selected language are ignored. + + + + + + +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. + + + + + + +Like , but the values are interpreted as regular expressions by which to match rule identifiers. + + + + + + +Inverse of the parameter: selected rules are not applied, and all other are applied. + + + + + + +Inverse of the parameter: selected rules are not applied, and all other are applied. + + + + + + +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. + + + + + + +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. + + + + + + +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 X-Text-Markup in for the list of markup keywords currently known to Pology. Similarly to parameter, this parameter only enables rules to remove the markup (or do something else) before matching. + + + + + + +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. + + + + + + +By default internal Pology rules are applied, and this parameter can be used to apply external rules instead, defined in the given rule file. + + + + + + +Like , but external rules are read from a directory containing any number of rule files. + + + + + + +Apply rules only to messages from given branch (summit). + + + + + + +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. + + + + + + +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. + + + + + + +Open the PO file on failed messages in Lokalize. + + + + + + +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 skip-rule: and continues with comma-separated list of rule identifiers: + +# skip-rule: ruleid1, ruleid2, ... + + + @@ -560,13 +803,6 @@ - -<command>es:setUbsp</command> - - - - - <command>fr:setUbsp</command>