Warning, /sdk/pology/doc/user/ascription.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-ascript">
 <title>Ascribing Modifications and Reviews</title>
 
 <para>It may not be obvious, especially to new translators, to which extent the translation needs to be reviewed. If the translator has exercised due diligence, how "wrong" can the translation be? Even if the translator has good command of the source language -- typically English in context of PO files -- the answer is "very wrong", all aspects considered.</para>
 
 <para>With comparatively simple grammar of English, the meaning of a short English sentence (as typically encountered in program user interfaces) may vary much depend on the surrounding context. This context may not be obvious when the translator is going through isolated messages in the PO file, so he may commit the worst of errors from the reader's viewpoint: the senseless translation. An experienced reviewer will have developed sense for troublesome contexts, and will have at disposal several means to conclusively determine the context (including, for example, running the development version of the program).</para>
 
 <para>Even if the context is correctly established, the translator may use "wrong" terminology, which is the next worse thing for the reader. A term used in translation does not need to be wrong by itself, in fact it may be exactly the correct term -- in another translation project. The reviewer will have more experience with terminology of the present project, and be able to bring the translation in line with it.</para>
 
 <para>Style in the technical sense is a consistent choice between several perfectly valid constructs in target language when applied to text in the given technical context. For example, how to translate menu titles and items, button labels, or tooltips in user interface. Choices may include noun or verb forms, particular grammar categories, tone of address, and so on. There may be a style guide to the project which details such choices, and the reviewer will know it well.</para>
 
 <para>Style in the linguistic sense is especially applicable to longer texts, such as tooltips in user interface or paragraphs in documentation. A typical error of a new translator is to closely adhere to English style and grammar. This may produce translation which is semantically and grammatically valid in the target language, but very out of style. Reviewer then steps in to naturalize such constructs.</para>
 
 <para>Finally, while the reviewer may be an experienced translator, that does not mean that his own translations need no review. Immersion into the source language, distraction, and fatigue, will lead the reviewer into any of the above errors in translation, only with lesser frequency. This means that reviewers should also mutually review their own translations.</para>
 
 <para>This calls for a systematic approach to review in translation workflow.</para>
 
 <!-- ======================================== -->
 <sect1 id="sec-ascrevcomp">
 <title>Review Stages vs. Ascription</title>
 
 <para>Classical review workflow, <emphasis>by stages</emphasis>, seems simple enough. Translator translates a new PO file or updates an existing translation, and declares it ready to review. A reviewer reviews it, and declares it ready to commit into the pool from which PO files are periodically released. A committer finally commits the file. The process is iterative: the reviewer may return the file to the translator, and translator later again declare it as ready for review. There may be several stages of review (such as <emphasis>proof-reading</emphasis>, <emphasis>approving</emphasis>), each of which may return the translation to a previous stage, or forward it to some special stage. The process may also be implemented on the subfile level, where each PO message can go through stages separately.</para>
 
 <para>Regardless of the technical details, review workflows of this kind all have the following in common. Members of the translation team are assigned <emphasis>roles</emphasis> (such as <emphasis>translator</emphasis>, <emphasis>reviewer</emphasis>, <emphasis>committer</emphasis>) by which they step into the workflow. A single person can have more roles. Later review stages must wait for the earlier stages to complete, and the translation cannot be updated again before the current version clears the review pipeline (or the pipeline is aborted). Once the translation is committed, it becomes a part of simply "admitted" translations, with no further qualifiers.</para>
 
 <para>The system of prescribed roles requires that team members assign the roles between themselves, stick to them, and shuffle them along the way. The prescribed review pipeline requires a tool to keep track of the current review stage of translation. This makes the review workflow rigid, with probable bottlenecks. Distribution of roles may become disbalanced by people coming into and leaving the team, or the tracking tool may be prohibitive to some scenarios (e.g. single translator making small adjustments in dozens of files across the project, but having to upload each manually through a web interface).</para>
 
 <para>"Rigid" and "inefficient" are comparative qualifications, so what is it that review by stages can be compared to in this way?</para>
 
 <para>Review <emphasis>by ascriptions</emphasis> is even simpler conceptually, and yet less rigid and more efficient than the review by stages. It obligatory works on the PO message level, rather than PO file level. Anyone can simply translate some PO messages and directly commit modified PO files, without any review, but <emphasis>ascribing</emphasis> modifications to own name. Anyone can review any PO message at any moment, commit modifications made during the review, and ascribe the review to own name (and possibly to a certain class -- review of context, of terminology, style, etc). When the time comes to release the translation, <emphasis>insufficiently</emphasis> reviewed messages are automatically omitted, by evaluating the <emphasis>ascription history</emphasis> of each message.</para>
 
 <para>Based on the ascription history, the reviewer can select a subset of PO messages, and review only the difference between their historical and current versions. For example, Alice can select to review only messages modified since she or Bob had last reviewed them for style. She could see the difference from that last review to current version, e.g. if in the whole paragraph only a single word was changed by Charlie when he reviewed the terminology. Ascription history also propagate through merging of PO files with templates, so the reviewer can compare the change in original to the change in translation since the last review and judge if one fits the other.</para>
 
 <para>Since everyone just commits, translations can be efficiently kept in a version control repository, with the ascription system added on top. After having done some translating, the translator simply substitutes commit command of the version control system (VCS) with "ascribe modifications" command of the ascription system (AS, which calls the underlying VCS internally). After reviewing, the reviewer uses "ascribe reviews" command of the AS to commit reviews to ascription history (as well as any modifications made during the review). To select messages for review, the reviewer issues "diff for review" command of the AS, with suitable parameters to narrow the message set; selected messages are marked in-place in PO files and equipped with <link linkend="ch-diffpatch">embedded differences</link>, and possibly directly opened in a PO editor.</para>
 
 <para id="p-asrel">When the translations are to be released, the release person issues "filter for release" command of the AS, which takes the working PO files and creates final PO files, in which the insufficiently reviewed messages are removed. Here "release time" can be understood figuratively: since filtering for release should be a fully automatic process, it can be performed at any interval of convenience.</para>
 
 <para>What constitutes "sufficient review" can be defined in fine detail. It could be specified that messages modified by Alice need to have only review for terminology, but not necessarily for style; Charlie may belong to the group which needs to be reviewed on style, but not necessarily on context; Bob's reviews for style may be nice to have, but never blocking the release if missing. These decisions do not preclude released messages to be reviewed later on missing points, after higher priority reviews have been completed. The definition of sufficiency may be changed at any point, e.g. as team members get more experienced and require less review, without interfering with direct translation and review activities.</para>
 
 <para>In summary, an AS preserves the operational efficiency of VCS, while at the same time providing great flexibility of review. All team members can be given commit access, no web or email detours are needed. There are no prescribed roles, but a functional equivalent of role assignment happens at the last possible moment (release time), can take into account both translators' and reviewers' abilities, and changing estimates of those over time. There is no staging between completing and committing the translation, which enables a translator to continue polishing the translation undisturbed until a reviewer comes around. There are no bottlenecks when performing small changes in many files, since a single AS command commits all changes just as a single VCS command would. On commit operations, the AS can also apply various checks (e.g. decline to commit syntactically invalid PO files) and modifications (e.g. update translator's data in the PO header).</para>
 
 </sect1>
 
 <!-- ======================================== -->
 <sect1 id="sec-ascsetup">
 <title>Setting up Ascription with <command>poascribe</command></title>
 
 <para>Pology provides an ascription system in the form of the <command>poascribe</command> command.</para>
 
 <para>Let the organization of PO files for the language <literal>nn</literal> in the version control repository be such:
 <programlisting>
 l10n-nn/
     po/
         ui/
             alpha.po
             bravo.po
             ...
         doc/
             alpha.po
             bravo.po
             ...
         ...
 </programlisting>
 Having PO files grouped by language can be taken as a hard prerequisite<footnote>
 <para><emphasis>Technically</emphasis>, PO files could also be grouped by PO domain:
 <programlisting>
 po/
     ui/
         alpha/
             ...
             nn.po
             mm.po
             ...
 </programlisting>
 but this would lead to a host of strange sharings of ascription settings and auxiliary file locations between different languages. In general, it is assumed that each translation team manages its own separate ascription.</para>
 </footnote>. Also necessary is a single top subdirectory for the whole PO file tree (here <filename>po/</filename>), rather than having several PO subdirectories directly in the language directory.</para>
 
 <para>Setting up ascription is now simple. Create the ascription configuration file named exactly <filename>ascription-config</filename> (<command>poascribe</command> expects this name), on the same level as the top PO directory:
 <programlisting>
 l10n-nn/
     ascription-config
     po/
         ui/
             ...
         doc/
             ...
 </programlisting>
 and set in it a few global configuration fields, and data for each known translator:
 <programlisting language="ini">
 # ---------------------------
 # Global ascription settings.
 
 [global]
 
 # Roots of the original and ascription trees.
 catalog-root = po
 ascript-root = po-ascript
 
 # The underlying version control system.
 version-control = svn
 
 # Data for updating PO headers on request.
 language = nn
 language-team = Nevernissian
 team-email = l10n-nn@neverwhere.org
 
 # Default commit message.
 commit-message = Translation updates.
 
 # -----------------------
 # Registered translators.
 
 [user-alice]
 name = Alice Akmalryn
 original-name = Алиса Акмалрин
 email = alice.akmalryn@someplacenice.org
 
 [user-bob]
 name = Bob Bromkin
 original-name = Бобан Бромкин
 email = bob.byomkin@otherplacenice.org
 
 # ...and so on.
 </programlisting>
 The configuration fields used in this example, and other possible configuration fields, are listed and described below.</para>
 
 <para>Global settings in the configuration file:
 <variablelist>
 
 <varlistentry>
 <term><literal>catalog-root</literal></term>
 <listitem>
 <para>The path to top PO subdirectory. This should be a relative path, and relative to the location of the configuration file.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term><literal>ascript-root</literal></term>
 <listitem>
 <para>Relative path to the top directory of <link linkend="p-ascftree">the ascription file tree</link>, which will be created and updated by <command>poascribe</command>.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term><literal>version-control</literal></term>
 <listitem>
 <para>The underlying version control system of the repository. The value is a keyword, see <xref linkend="sec-cmsuppvcs"/> for a list of VCS supported by Pology.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term><literal>language</literal></term> <term><literal>language-team</literal></term> <term><literal>team-email</literal></term> <term><literal>plural-header</literal></term>
 <listitem>
 <para>These fields provide information about the language and the translation team, which <command>poascribe</command> uses to update header fields in modified PO files. <literal>language</literal> is the language code, while <literal>language-team</literal> is usually just the human-readable language name in English. <literal>plural-header</literal> is the exact contents of <literal>Plural-Forms:</literal> PO header field (if it contains a <literal>%</literal> character, you need to escape it as <literal>%%</literal>). For any of these fields that is not set, <command>poascribe</command> will remove the corresponding header field when updating the PO header.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term><literal>title</literal></term>
 <listitem>
 <para>The first comment line in the PO header, set when <command>poascribe</command> updates the header. It can contain the following placeholders for inserting file-dependent information: <literal>%basename</literal> is the base PO file name (e.g. <literal>alpha.po</literal>), <literal>%poname</literal> the PO domain name (e.g. <literal>alpha</literal>), <literal>%langname</literal> the human-readable language name (supplied by the <literal>language-team</literal> field), and <literal>%langcode</literal> the language code (supplied by the <literal>language</literal> field). Note that these placeholders actually must be written as <literal>%%<replaceable>name</replaceable></literal>, to escape the special meaning of single <literal>%</literal> character. If <literal>title</literal> field is not set, <command>poascribe</command> will leave the title comment as it is in the PO file.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term><literal>commit-message</literal></term>
 <listitem>
 <para>The default commit message for the underlying VCS, when <command>poascribe</command> calls upon it to commit modified PO files. If this field is not set, an editor window will pop up to input the commit message, or the <option>-m</option>/<option>--message</option> option can be used to set the message through the command line. If the field is set, <option>-m</option> can still be used to override the default commit message.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term><literal>review-tags</literal></term>
 <listitem>
 <para>The set of accepted <link linkend="sec-ascfgrev">review tags</link>, given as whitespace-separated list of tags. If set, <command>poascribe</command> will abort when trying to use an unknown tag, otherwise it will accept any tag.</para>
 </listitem>
 </varlistentry>
 
 </variablelist>
 </para>
 
 <para>Each known translator is represented by a <literal>[user-<replaceable>name</replaceable>]</literal> configuration section. Translator's user name in the ascription system has no direct relation with the underlying VCS account name (if VCS uses them), but it makes sense for them to be equal. This also means that a translator does not even have to have VCS account (repository commit access), though this is expected for the sake of efficiency. Translator configuration sections can contain the following fields:
 <variablelist>
 
 <varlistentry>
 <term><literal>name</literal></term>
 <listitem>
 <para>Translator's name, in the form supposed to be readable in English. This means that if the name is not originally written in Latin script, some romanized form should be given.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term><literal>original-name</literal></term>
 <listitem>
 <para>Translator's name in its original form, if it differs from the romanized form given by the <literal>name</literal> field.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term><literal>email</literal></term>
 <listitem>
 <para>The email address at which the translator may be contacted.</para>
 </listitem>
 </varlistentry>
 
 </variablelist>
 </para>
 
 <para>As soon as <filename>ascription-config</filename> file is committed to the repository, the ascription system through <command>poascribe</command> is ready for use. The only expected regular modifications to the configuration file are those of adding new translators. On the other hand, translators should never be removed, because even after they go away, their ascription records remain in the system.</para>
 
 <sect2 id="sec-ascinit">
 <title>Initial Ascription</title>
 
 <para>The most common situation at the start of ascription workflow is that there already exists a considerable amount of translations, contributed by many different people over time. These existing translations should be ascribed as initial modifications -- but ascribed to whom? If it is not precisely known who translated what, the solution is to introduce a generic user in the configuration file, appropriately named "Unknown Hero" (or "Lost Translator", you can be inventive):
 <programlisting language="ini">
 [user-uhero]
 name = Unknown Hero
 original-name = Незнани јунак
 </programlisting>
 You should then ascribe all existing translations as modified and reviewed by this dummy translator:
 <programlisting language="bash">
 $ cd $LANGDIR
 $ poascribe commit -u uhero --all-reviewed -C  po/
 </programlisting>
 The <literal>commit</literal> argument is the ascription mode, and the <option>-u</option> option provides the user name to which ascriptions are made. This is an important point: ascriptions are made to a user defined in ascription configuration, and have nothing to do with VCS itself. It is the <option>--all-reviewed</option> option that declares all messages to be reviewed as well (this option is normally used only this once, and not in day to day operation). The <option>-C</option> option prevents automatic VCS adding and committing, which is useful for this initial step.</para>
 
 <para>When this command line is executed, a progress bar will appear and the following output will start to unfold:
 <programlisting>
 doc/alpha.po  (43/43)
 doc/bravo.po  (81/81)
 ...
 ui/alpha.po  (582/582)
 ui/bravo.po  (931/931)
 ...
 ===== Ascription summary:
 -           modified  reviewed
 translated     11775     11775
 fuzzy           2943      2943
 obsolete/t       365       365
 obsolete/f        26        26
 </programlisting>
 The number in parenthesis indicates how many messages have been ascribed in the given PO file (modified/reviewed), and at the end the totals are given.</para>
 
 <para>If, on the contrary, it is known who translated and reviewed what up to that point, ascription can be performed piece-wise with user names of real translators:
 <programlisting language="bash">
 $ cd $LANGDIR
 $ poascribe commit -u alice --all-reviewed -C  po/ui/
 $ poascribe commit -u bob --all-reviewed -C  po/doc/
 $ ...
 </programlisting>
 </para>
 
 <para id="p-ascftree">After the initial ascription has been made, the <emphasis>ascription file tree</emphasis> will appear next to the original file tree. There will be one ascription PO file for each summit PO file, with the same name and relative location within the tree:
 <programlisting>
 l10n-nn/
     po/
         ui/
             alpha.po
             bravo.po
             ...
         ...
     po-ascript/
         ui/
             alpha.po
             bravo.po
             ...
         ...
 </programlisting>
 Ascription PO files are used by <command>poascribe</command> to store the ascription history, rather than e.g. a database of some sort. This has the disadvantage in performance, but advantage in simplicity and robustness. For example, ascription files will be under version control as well.</para>
 
 <para><command>poascribe</command> may also modify original PO files during this run, by removing any previous field comments (<literal>#| ...</literal>) on translated messages. These comments are sometimes erroneously left in when the PO file is translated with an older or less capable PO editor, and leaving them would result in unnecessary additions to ascription PO files.</para>
 
 <para>The newly created ascription tree, any modifications to the original tree, and the ascription configuration file, can now be committed as usual. With Subversion as the VCS:
 <programlisting language="bash">
 $ cd $LANGDIR
 $ svn add ascription-config po-ascript
 $ svn commit ascription-config po po-ascript -m "Initial ascription."
 </programlisting>
 </para>
 
 </sect2>
 
 </sect1>
 
 <!-- ======================================== -->
 <sect1 id="sec-ascdailytr">
 <title>Daily Use for Translators</title>
 
 <para>While this is generally a good idea, with ascription in place translators must always update the complete language directory by VCS, rather than just one particular PO file or subdirectory, so that the original and the ascription PO file trees are kept in sync.<footnote>
 <para>There should be no technical problem here, since VCS updates are inexpensive in terms of network traffic, but there may be a problem of changing one's habits.</para>
 </footnote></para>
 
 <para>In order not to have to report their user name to <command>poascribe</command> all the time (by the <option>-u</option> option), translators can set it in <link linkend="sec-cmconfig">Pology user configuration</link>, the <literal>[poascribe]</literal> section:
 <programlisting language="ini">
 [poascribe]
 user = alice
 </programlisting>
 With this in place, translators can submit updated PO files simply by substituting VCS commit command with <literal>poascribe commit</literal> (or shortened: <literal>co</literal> or <literal>ci</literal>). With Subversion, this would look like:
 <programlisting language="bash">
 $ cd $LANGDIR
 $ poascribe co po/ui/*alpha*.po
 po/ui/alpha.po  (44)
 po/ui/libalpha.po  (15)
 ===== Ascription summary:
 -           modified
 translated       169
 >>>>> VCS is committing catalogs:
 Sending      ui/alpha.po
 Sending      ui/libalpha.po
 Sending      summit-ascript/messages/kdefoo/fooapp.po
 Sending      LANG/summit-ascript/messages/kdefoo/libfooapp.po
 Transmitting file data ....
 Committed revision 1267069.
 $ 
 </programlisting>
 The lines after <literal>>>>>> VCS...</literal> are produce by the underlying VCS, which is Subversion in this example.<footnote>
 <para>If the underlying VCS would a distributed one, such Git, and the push to a designated central repository is expected afterward, it must be performed manually.</para>
 </footnote></para>
 
 <para>As can be seen from the example output, <command>poascribe</command> will add ascription records into ascription PO files corresponding to original PO files, and commit them all. Like a VCS command, <command>poascribe co</command> can take any number of PO file or directory paths. For a directory path, only files with <filename>.po</filename> extension in it will be processed, and any other ignored. <command>poascribe</command> can be run from any working directory with appropriate paths as arguments, and it will always find the associated ascription configuration and files. If a default commit message has not been set in the ascription configuration, <command>poascribe</command> will ask for it; or it can be given in command line through <option>-m</option> option.</para>
 
 <sect2 id="sec-asctrnocomm">
 <title>Translators Without Commit Access</title>
 
 <para>With the ascription system in place, every regular translator should have the commit access to the repository. But, there may be some period of time before new translators are given commit access, or revision control may be too technical for some, and even those who have access may not be able to commit temporarily for some reason.</para>
 
 <para>These translators may send in their work by email or any other informal channel, to <emphasis>any</emphasis> member of the team how does have commit access. This team member can then commit received files without any review, as review can be conducted at any later time. If Bob sends some files to Alice, she can commit them immediately by stating Bob's user name:
 <programlisting language="bash">
 $ poascribe co -u bob <replaceable>files...</replaceable>
 </programlisting>
 For this to work, the translator who sent in the files has to be defined in the ascription configuration. There are no hidden costs or security issues to this (as opposed to giving VCS commit access), so every new translator should be defined there before any work of that person is committed.</para>
 
 </sect2>
 
 </sect1>
 
 <!-- ======================================== -->
 <sect1 id="sec-ascdailyrev">
 <title>Daily Use for Reviewers</title>
 
 <para>An ascription system opens up all sorts of possibilities for review patterns. Reviewers should keep in mind that for each message the full modification and review history is available, so that the translation team can think about how to make good use of it. What follows are some examples to illustrate the review functionality provided by <command>poascribe</command>.</para>
 
 <sect2 id="sec-ascbaserev">
 <title>Basic Reviewing</title>
 
 <para>At the very basic level (which is the only level in <link linkend="sec-ascrevcomp">review by stages</link>), messages can be classified as simply unreviewed or reviewed. Alice now wants to review all unreviewed messages in a subset of PO files, say the <filename>ui/</filename> subdirectory. She issues the following command (<literal>di</literal> is short for <literal>diff</literal>):
 <programlisting language="bash">
 $ poascribe di po/ui/
 po/ui/alpha.po  (2)
 po/ui/foxtrot.po  (7)
 po/ui/november.po  (12)
 ===== Diffed for review: 21
 $ 
 </programlisting>
 With this, all unreviewed messages in listed PO files have been marked, and <emphasis>diffed</emphasis>. If these PO files had already been reviewed before, some of the messages modified since then (those now marked for review) may have changed very little. For example, a few changed words in a paragraph-length message, or even just some punctuation. Therefore, for each message marked for review, Alice also wants to see the difference since the last review to current version. Here are two messages with typical review elements added by <literal>poascribe di</literal>:
 <programlisting language="po">
 #. ~ascto: charlie:m
 #: gui/mainwindow.cc:372
 #, ediff
 msgid "GAME OVER. {-You won-}{+Tie+}!"
 msgstr "KRAJ IGRE. {-Pobeda-}{+Nerešeno+}!"
 
 #. ~ascto: bob:m charlie:m
 #: game-state.cpp:117
 #, ediff-total
 msgid "Click the pause button again to resume the game."
 msgstr "Kliknite ponovo na dugme pauze da nastavite igru."
 </programlisting>
 </para>
 
 <para>In the first message, the first thing to note is the <literal>#. ~ascto:</literal> comment. This comment succinctly lists who did what with the message since the last review; here <literal>charlie:m</literal> means that Charlie is the one who modified it. Then there is the <literal>ediff</literal> flag, which Alice can search for in the editor to jump through messages marked for review. Finally, the original and translation have been diffed; here they show that, since the last review, the message was fuzzied by changing "You won" to "Tie", and what Charlie did in translation to unfuzzy it. Even on a message as short as this, the difference tells something useful to Alice: the phrase "Game over" likely has a formulaic translation, and the fact that it is not part of the difference means that the earlier reviewer had made sure it is consistent, so Alice does not have to check that.</para>
 
 <para>The <literal>#. ~ascto:</literal> comment of the second message reveals that both Charlie and Bob had been modifying it. The <literal>ediff-total</literal> flag instead of plain <literal>ediff</literal> means that this message had no reviews until now, so there are no embedded differences in text fields.</para>
 
 <para>Alice can now go through marked messages in listed PO files, review translations, and possibly make modifications. When making changes in a message with embedded differences, she can freely edit the text outside of difference segments and within <literal>{+...+}</literal> segments (as these are the ones which belong to current version of the text). While reviewing, Alice does <emphasis>not</emphasis> remove any of the added message elements (except for an occasional difference segment, if she modifies a translation), as these elements are needed for a subsequent invocation of <command>poascribe</command>. If a message is particularly hard to translate and Alice wants to defer reviewing it for some later time, she can add to it the <literal>unreviewed</literal> flag (or <literal>nrev</literal> for short).</para>
 
 <para>Once the review is complete, Alice simply commits the reviewed files:
 <programlisting language="bash">
 $ poascribe co po/ui/
 po/ui/alpha.po  (0/2)
 po/ui/foxtrot.po  (0/7)
 po/ui/november.po  (3/12)
 ===== Ascription summary:
 -           modified  reviewed
 translated         3        21
 >>>>> VCS is committing catalogs:
 Sending      po/ui/november.po
 Sending      po-ascript/ui/alpha.po
 Sending      po-ascript/ui/foxtrot.po
 Sending      po-ascript/ui/november.po
 Transmitting file data ....
 Committed revision 1284220.
 $ 
 </programlisting>
 Three things have happened here. First, all review states (flags, embedded differences, etc.) have been removed, restoring diffed PO files to original state. Then, any modifications that Alice has made during review are ascribed to her (here 3 out of 21 messages). Finally, all marked messages are ascribed as reviewed by Alice (any with <literal>unreviewed</literal> or <literal>nrev</literal> flags would have been omitted here). When committing, the only original PO file that got committed is the one with modifications made during review, and all the ascription PO files were committed because of the reviews recorded in them.</para>
 
 <para>When many PO files with few changes per file should be reviewed, it becomes burdensome to manually open each and every diffed file for review, and then to make sure that all are committed with <command>poascribe co</command>. To make this easier, <literal>-w toreview.out</literal> option can be added to the <literal>poascribe di</literal> command line, which requests that paths of all diffed PO files be written into <filename>toreview.out</filename> file. This file can then be used to batch-open diffed PO files in an editor, as well as to commit them later by adding <literal>-f toreview.out</literal> to <literal>poascribe co</literal>. There is also <option>-o</option> option, which tells <command>poascribe</command> to directly open PO files in one of the supported PO editors (see <xref linkend="sec-cmsupped"/>). Putting it together, to efficiently review a whole bunch of small changes throughout many PO files, with Lokalize as the PO editor, you can execute:
 <programlisting language="bash">
 $ poascribe di <replaceable>paths...</replaceable> -w toreview.out -o lokalize
 $ # ...only marked messages opened in Lokalize, review them...
 $ poascribe co -f toreview.out
 </programlisting>
 </para>
 
 <para>If for whatever reason you want to simply remove the review elements from messages without committing the PO files (effectively discarding the review), you can use the <literal>purge</literal> mode (short <literal>pu</literal>) of <command>poascribe</command>:
 <programlisting language="bash">
 $ poascribe pu <replaceable>paths...</replaceable>
 </programlisting>
 If <option>-k</option>/<option>--keep-flags</option> option is added to this command line, the flags which mark the messages as reviewed get preserved; more precisely, every <literal>ediff*</literal> flag is replaced with <literal>reviewed</literal> flag, and every <literal>unreviewed</literal> flag is left in, so that subsequent invocation of <literal>poascribe co</literal> can record reviews. You will want this limited purging if you have some automatic validation tools to run before committing, and these tools would be thrown off by review elements (most likely by embedded differences).</para>
 
 </sect2>
 
 <sect2 id="sec-ascselrev">
 <title>Selecting Messages for Review</title>
 
 <para>Invocations of <command>poascribe di</command> without any options, as in the previous section, are equivalent to this:
 <programlisting language="bash">
 $ poascribe di -s modar <replaceable>paths...</replaceable>
 </programlisting>
 The <option>-s</option> option serves to issue a message <emphasis>selector</emphasis>. <literal>modar</literal> is the default selector for the <literal>diff</literal> operation mode, and stands for "MODified-After-Review": it selects the earliest historical modification of the message after the last (or no) review of that message, if there is any such. By selecting a historical modification of the message, the difference from it to current version can be computed and embedded into the PO file, as seen in earlier examples.</para>
 
 <para id="p-seltypes">There are various specialized selectors, and they fall into two groups: <emphasis>shallow selectors</emphasis> and <emphasis>history selectors</emphasis>. Shallow selectors look only into the current version of the message, and cannot select historical versions, which means that they cannot provide embedded differences. History selectors (<literal>modar</literal> is of this type) can select messages from history and provide differences. Several selectors can be issued on the command line, and the message is selected only if all selectors select it (boolean AND-linking). Shallow selectors are thus normally used as a pre-filters for history selectors. For example, to select messages modified after the last review, but only those <link linkend="ch-summit">found in the stable branch</link>, <literal>branch</literal> and <literal>modar</literal> selectors are chained like this:
 <programlisting language="bash">
 $ poascribe di -s branch:stable -s modar <replaceable>paths...</replaceable>
 </programlisting>
 It is important that the history selector is given last, because the last selector determines which historical message is selected for diffing. If the ordering had been reversed in this example, same messages would get selected, but they would not have embedded differences, because <literal>branch</literal> is a shallow selector.</para>
 
 <para>Selectors can take parameters themselves, like <literal>branch:stable</literal> in the previous example. Parameters are separated from the selector name by any non-alphanumeric character; this is colon by convention, but if a parameter contains a colon, something else, like slash, tilde, etc. can be used. Number of parameters can vary, and <literal>modar</literal> in particular can take from none to three. If Alice wants to review only those messages modified <emphasis>by Charlie</emphasis> since the last review, she states this by first argument to <literal>modar</literal>:
 <programlisting language="bash">
 $ poascribe di -s modar:charlie <replaceable>paths...</replaceable>
 </programlisting>
 If Alice does not give much credit to other reviewers, she can request selection of messages modified after <emphasis>her own</emphasis> last review with second parameter to <literal>modar</literal>:
 <programlisting language="bash">
 $ poascribe di -s modar::alice <replaceable>paths...</replaceable>
 </programlisting>
 Here the first parameter ("modified by..."), which is not needed, must be explicitly skipped, before proceeding to the second parameter ("reviewed by..."). (The third optional parameter to <literal>modar</literal> will be demonstrated later on.)</para>
 
 <para>When a selector parameter is a user name, normally it can also be a comma-separated list of user names (<literal>modar:bob,charlie</literal>) or prefixed with tilde to negate, i.e. to select all users other than those listed (<literal>modar:~alice</literal>).</para>
 
 <para>Any selector can be negated by prepending <literal>n</literal> to its name. For example, the history selector <literal>modafter:<replaceable>date</replaceable></literal> selects first modification after the given date; to select messages modified after the last review, but only if modified during June 2010:
 <programlisting language="bash">
 $ poascribe di -s modafter:2010-06 -s nmodafter:2010-07 -s modar <replaceable>paths...</replaceable>
 </programlisting>
 Negating a history selector produces a shallow selector: while <literal>modafter</literal> is a history selector, <literal>nmodafter</literal> is shallow. But the mutual ordering of the two in this example is not important, since the last selector in the chain is the usual <literal>modar</literal>.</para>
 
 <para>Selectors can be issued in other modes too. If the PO file is big, and Alice has reviewed messages up to and including the message with entry number 246 when she has to pause until another day, she can commit reviews only up to this entry by issuing the <literal>espan</literal> selector:
 <programlisting language="bash">
 $ poascribe co -s espan::246 <replaceable>paths...</replaceable>
 </programlisting>
 The first parameter to <literal>espan</literal>, here omitted, would be the entry number of the first message to select, in case messages should not be selected starting from the first in the file. There is also the counterpart <literal>lspan</literal> selector, which works with referent line numbers (those of <varname>msgid</varname> keywords) instead of entry numbers.</para>
 
 <para>If you do not want to immediately diff for review, but to see first how many messages would be selected by the selector chain that you assembled, you can use the <literal>status</literal> operation mode (<literal>st</literal> for short) instead of <literal>diff</literal>. It takes selectors in the same way as <literal>diff</literal>, and shows counts of selected messages by category. You can also add the <option>-b</option> option to have counts reported by PO file (where non-zero).</para>
 
 <para>You may also want to observe the complete recorded ascription history of a message, all its modifications and reviews, with differences between each two modifications. For this you can use the <literal>history</literal> operation mode (<literal>hi</literal> for short), typically with one of <literal>l</literal> or <literal>e</literal> selectors to single out a particular message. The history will be written out to terminal, starting from the newest to the oldest version of the message, with highlighted embedded differences.</para>
 
 </sect2>
 
 <sect2 id="sec-ascfgrev">
 <title>Fine-Grained Reviews</title>
 
 <para>In the introduction of this chapter, several distinct things that can go wrong in translation were described. Not all reviewers may be able to check translation against all those problems. Here is a typical scenario of this kind:</para>
 
 <para>Alice is computer-savvy and knows the translation project inside and out, which means that she can review well for context, terminology, and technical style. But, her language style leaves something to be desired, which shows in longer sentences and passages. Dan, on the other hand, is a very literary person, but not that much into the technical aspects. Dan's style reviews would thus be a perfect complement to Alice's general reviews.</para>
 
 <para><command>poascribe</command> can support this scenario in the following way. A <emphasis>review type</emphasis> tag <literal>lstyle</literal> for language style is defined in the ascription configuration, using the <literal>review-tags</literal> field:
 <programlisting language="ini">
 [global]
 # ...
 review-tags = lstyle
 </programlisting>
 With this addition to configuration, Alice can continue to review as she did before, without any changes in her workflow.</para>
 
 <para>Dan selects messages for review similarly to Alice, but additionally giving the <literal>lstyle</literal> tag as the <emphasis>third</emphasis> parameter of <literal>modar</literal>, and indicating that reviews should be tagged as <literal>lstyle</literal> using the <option>-t</option> option:
 <programlisting language="bash">
 $ poascribe di -s modar:::lstyle -t lstyle <replaceable>paths...</replaceable>
 </programlisting>
 After finishing the review, Dan commits as usual:
 <programlisting language="bash">
 $ poascribe co PATHS...
 </programlisting>
 </para>
 
 <para>If Dan is always going to review the language style, in order not to have to issue the selector and the tag in command line all the time, he can make them default for the <literal>diff</literal> mode in Pology user configuration:
 <programlisting language="ini">
 [poascribe]
 user = dan
 selectors/diff = modar:::lstyle
 tags/diff = lstyle
 </programlisting>
 With this, Dan can use plain <literal>poascribe di</literal> just like Alice does.</para>
 
 <para>The important point of review tags is that they make reviews by types independent. For example, Dan may come around to review the language style of the given message after several modifications and general reviews have been ascribed to it -- <literal>modar:::lstyle</literal> will simply ignore all reviews other than <literal>lstyle</literal> reviews. This is going to be reflected in the <literal>~ascto:</literal> comment of diffed messages:
 <programlisting language="po">
 #...
 #. ~ascto: charlie:m alice:r bob:m
 #...
 msgid "..."
 msgstr "..."
 </programlisting>
 Here Alice has made one review between Charlie's and Bob's modifications, and that review, being general instead of <literal>lstyle</literal>, did not cause <literal>modar</literal> to stop at it. After Dan reviews this message for language style, Alice runs selection for review and gets this:
 <programlisting language="po">
 #...
 #. ascto: bob:m dan:r(lstyle)
 #...
 msgid "..."
 msgstr "..."
 </programlisting>
 Again, since <literal>lstyle</literal> reviews do not mix with general reviews<footnote>
 <para>General review too has a tag assigned, the empty string, in case the reviewer needs to explicitly issue it in some context.</para>
 </footnote>, Dan's review did not hide Bob's modification that Alice did not check so far.</para>
 
 </sect2>
 
 </sect1>
 
 <!-- ======================================== -->
 <sect1 id="sec-ascmaint">
 <title>General Maintenance Procedures</title>
 
 <para>After the ascription system is set up, there should be very little to do to maintain it. The details depend on the established translation workflow, and this section describes some of the procedures which may apply.</para>
 
 <sect2 id="sec-ascmerge">
 <title>Ascribing Merges</title>
 
 <para>If PO files are periodically merged with templates in a centralized manner, by one designated person or repository automation, these modifications must also be ascribed. This is done as any other ascription, by substituting the VCS commit command with <literal>poascribe co</literal>. For example:
 <programlisting language="bash">
 $ svn commit $LANGDIR -m "Everything merged."
 </programlisting>
 may be substituted with:
 <programlisting language="bash">
 $ poascribe commit $LANGDIR -m "Everything merged."
 </programlisting>
 Since the user is not explicitly given by the <option>-u</option> option, this will ascribe modifications due to merging to the person set in Pology user configuration on the system where the command is executed. This is just fine. It is also possible to define a dummy user to which modifications due to merging are ascribed, though there is no known advantage to that at present.</para>
 
 <para>Note that you can issue the <option>-C</option> option to prevent <command>poascribe</command> from automatically committing merged files, in case are some automatic post-merge operations that you would like to perform on merged PO files beforehand. Afterward, standalone VCS commit command can be issued, but do not forget to include the ascription file tree in it as well.</para>
 
 </sect2>
 
 <sect2 id="sec-ascshuffle">
 <title>Shuffling Ascription PO Files</title>
 
 <para>Sometimes PO files are "shuffled" in the repository: renamed, moved to another subdirectory, etc. Such shuffling should be exactly mirrored in the ascription tree:
 <itemizedlist>
 
 <listitem>
 <para>If a PO file is moved or renamed, its counterpart ascription PO file should also be moved or renamed in the same way within the ascription tree.</para>
 </listitem>
 
 <listitem>
 <para>If a PO file is split into two, then it depends on how you handle the splitting. A good way would be to copy the old PO file to two new names, and then merge them with new templates. In this way as much of existing translation as possible will be preserved. If this is done, then the ascription PO files should be copied to new names, but then there is nothing to merge them with. This is just right, since message ascription histories generally interleave across the split (but also see <xref linkend="sec-asctrim"/>).</para>
 </listitem>
 
 <listitem>
 <para>If two PO files are merged into one, you should probably handle that by using <command>msgcat</command> to properly concatenate them into the new PO file, and then merge the new PO file with its template. Then, the old ascription PO files should be concatenated with <command>msgcat</command> as well, and nothing more. But, <emphasis>make sure</emphasis> that you issue the <option>--use-first</option> to <command>msgcat</command>, for both concatenations. This is because when in the two concatenated PO files there are two messages with same <varname>msgctxt</varname>+<varname>msgid</varname> but different <varname>msgstr</varname>, <command>msgcat</command> will by default make a free-form composition of <varname>msgstr</varname> texts, for translator to manually disentangle later. This would ruin the ascription entry of such a message in the concatenated ascription PO file.</para>
 </listitem>
 
 </itemizedlist>
 After the shuffling is performed in both file trees, <literal>poascribe co</literal> is executed to smooth out and commit modifications.</para>
 
 </sect2>
 
 <sect2 id="sec-ascfltrel">
 <title>Filtering for Release</title>
 
 <para>At the moment of this writing, <link linkend="p-asrel">filtering for release</link> has not been implemented yet in <command>poascribe</command>, but it is planned.</para>
 
 <para>However, if you <link linkend="ch-summit">translate in summit</link>, it is possible to configure the summit to skip insufficiently reviewed messages when scattering to branches. See <xref linkend="sec-sucfgascf"/> for details.</para>
 
 </sect2>
 
 <sect2 id="sec-asctrim">
 <title>Trimming Ascription History</title>
 
 <para>At the moment of this writing, trimming the ascription history has not been implemented yet in <command>poascribe</command>, but it is planned.</para>
 
 </sect2>
 
 </sect1>
 
 <!-- ======================================== -->
 <sect1 id="sec-ascoptions">
 <title>Command Line Options</title>
 
 <para>Overview of operation modes:
 <variablelist>
 
 <varlistentry>
 <term><literal>commit</literal>, <literal>co</literal></term>
 <listitem>
 <para>Commits modifications and reviews to PO files. Default selector: <literal>any</literal>.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term><literal>diff</literal>, <literal>di</literal></term>
 <listitem>
 <para>Adds embedded differences and other review elements to selected messages in PO files. Default selector: <literal>modar</literal>.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term><literal>history</literal>, <literal>hi</literal></term>
 <listitem>
 <para>Outputs to terminal the complete history of modifications and reviews for selected messages. Default selector: <literal>any</literal>.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term><literal>purge</literal>, <literal>pu</literal></term>
 <listitem>
 <para>Removes all review elements from PO files (unless <option>-k</option>/<option>--keep-flags</option> option is added, when only review flags are kept). Default selector: <literal>any</literal>.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term><literal>release</literal>, <literal>re</literal></term>
 <listitem>
 <para><emphasis>Not implemented yet.</emphasis></para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term><literal>status</literal>, <literal>st</literal></term>
 <listitem>
 <para>Shows ascription counts per message category (total for all selected messages, and also per PO file if <option>-b</option>/<option>--show-by-file</option> option is added). Default selector: <literal>any</literal>.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term><literal>trim</literal>, <literal>tr</literal></term>
 <listitem>
 <para><emphasis>Not implemented yet.</emphasis></para>
 </listitem>
 </varlistentry>
 
 </variablelist>
 </para>
 
 <para>Options specific to <command>poascribe</command>:
 <variablelist>
 
 <varlistentry>
 <term><option>-a <replaceable>SELECTOR[:ARGS]</replaceable></option>, <option>--select-ascription=<replaceable>SELECTOR[:ARGS]</replaceable></option></term>
 <listitem>
 <para>By default, a historical message is selected for diffing with current message based on the last history selector given by <option>-s</option>/<option>--selector</option> option (if any). Instead, with this option you can explicitly set the selector for historical messages. It will be applied after the message has been selected by the primary selector chain. The option can be repeated, in which case a historical message is selected if all selectors match it.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term><option>-A <replaceable>RATIO</replaceable></option>, <option>--min-adjsim-diff=<replaceable>RATIO</replaceable></option></term>
 <listitem>
 <para>The minimum adjusted similarity between the current and the historical message at which embedded differences will be shown.<footnote>
 <para>Unlike for example in fuzzy messages, the similarity between the current and the earlier message from the ascription history may be exactly zero, it the PO file has undergone several merges in between. For example, in a two-word message, the first merge could have replaced the first word, and the second merge the second word.</para>
 </footnote> This is a number in range from 0.0 (always show) to 1.0 (never show). If the difference is not shown due to this limit, the message will get the flag <literal>ediff-ignored</literal> instead of the usual <literal>ediff</literal>. A reasonable value may be 0.6 to 0.8.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term><option>-b</option>, <option>--show-by-file</option></term>
 <listitem>
 <para>Some operation modes show summary at the end of the run, which is based on all processed PO files taken together. With this option you can request some of the summary elements to be shown per processed file.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term><option>-C</option>, <option>--no-vcs-commit</option></term>
 <listitem>
 <para>Issue this option if you want <command>poascribe</command> not to commit modifications to version control itself. This may be useful if you want to examine raw modifications it made, to perform some checks, etc, and commit manually later. But <emphasis>do not</emphasis> modify any messages in between, as that would defeat the purpose of ascription.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term><option>-d <replaceable>LEVEL</replaceable></option>, <option>--depth=<replaceable>LEVEL</replaceable></option></term>
 <listitem>
 <para>Operation modes normally consider ascription history of a message starting from the newest and going down to the earliest ascription. With this option you can set the depth to which history is examined, where 0 is the newest ascription only, 1 the current and first previous ascription, etc.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term><option>-D <replaceable>SPEC</replaceable></option>, <option>--diff-reduce-history=<replaceable>SPEC</replaceable></option></term>
 <listitem>
 <para>Some special (possibly custom) selectors may need to examine only differences or commonalities between each two adjacent messages. In order not to have to build this functionality into each such selector, you can issue this option to preprocess ascription history such that each historical message is reduced based on the difference with the next earlier message. The message can be reduced to the parts equal, added or removed as compared to the earlier message. This is controlled by the <literal><replaceable>SPEC</replaceable></literal> value, which must start with one of the letters <literal>e</literal> (equal), <literal>a</literal> (added), or <literal>r</literal> (removed). This letter may be followed with an arbitrary sequence of characters, which will be used to separate the remaining parts of the text in the message; if there are no additional characters, space is used as the separator.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term><option>-F <replaceable>HOOKSPEC</replaceable></option>, <option>--filter=<replaceable>HOOKSPEC</replaceable></option></term>
 <listitem>
 <para>Sometimes it may be necessary to apply selectors not to the ascription history as it is, but to a suitably filtered version of the history. This option can be used to set a Pology F1A hook as filter, see <xref linkend="sec-cmhooks"/> for details. It can be repeated to set several filters.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term><option>-G</option>, <option>--show-filtered</option></term>
 <listitem>
 <para>When setting a filter on ascription history by the <option>-F</option>/<option>--filter</option> option in the <literal>diff</literal> mode, it may be good to see also the difference in filtered messages, those on which the selectors were actually applied. By issuing this option, every message field with an embedded difference will get added a visually conspicuous separator, followed by the filtered version of the text with difference as well. When you commit or purge the PO file diffed in this way, the separators and the filtered text are removed together with all other review elements.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term><option>-k</option>, <option>--keep-flags</option></term>
 <listitem>
 <para>When the diffed PO file is purged of review elements, by default all review elements are removed, so that on subsequent commit only modifications would be ascribed, if there were any. Issuing this option on purge causes that all review elements except for flags are removed. More precisely, <literal>ediff*</literal> flags are replaced with <literal>reviewed</literal>, and <literal>unreviewed</literal> flags are simply kept. This makes the subsequent commit also ascribe reviews. You need this if you want to apply some automatic checks to the PO file after the review and before the commit, where more intrusive review elements (like embedded differences) would interfere.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term><option>-m <replaceable>TEXT</replaceable></option>, <option>--message=<replaceable>TEXT</replaceable></option></term>
 <listitem>
 <para>The text of the commit message. If default commit message is set in the ascription configuration, this text overrides it. If default commit message is not set and this option is not issued, and editor window is opened to enter the commit message.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term><option>-o <replaceable>EDITOR</replaceable></option>, <option>--open-in-editor=<replaceable>EDITOR</replaceable></option></term>
 <listitem>
 <para>When diffing for review, instead of manually opening diffed PO files and searching for messages by flags, this option can be issued to have <command>poascribe</command> automatically open PO files in a PO editor (and possibly have the editor filter the message list to only selected messages). This work only with PO editors explicitly supported by Pology; the <replaceable>EDITOR</replaceable> value is an editor keyword rather than an arbitrary editor command. See <xref linkend="sec-cmsupped"/> for the list of supported editors.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term><option>-L <replaceable>RATIO</replaceable></option>, <option>--max-fraction-select=<replaceable>RATIO</replaceable></option></term>
 <listitem>
 <para>In <literal>diff</literal> mode, this option sets the ratio of selected messages to total messages in a given PO file, above which no message in that file will be selected although the selector chain matched them. The value is the number between 0.0 and 1.0; for example, 0.2 means to accept selection if the number of selected messages is at most 20% of the total number of messages. This can be used to discern between reviewing updated PO files and newly translated PO files, as the latter take much more time to review and hence may be of lesser priority.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term><option>-s <replaceable>SELECTOR[:ARGS]</replaceable></option>, <option>--selector <replaceable>SELECTOR[:ARGS]</replaceable></option></term>
 <listitem>
 <para>The option to set a selector, in various modes. Can be repeated to create selector chains, in which case a message must match all selectors to be selected. In <literal>diff</literal> mode, if the last selector in the chain is not a <link linkend="p-seltypes">history selector</link>, selected messages will have no embedded differences (unless an ascription selector is explicitly given by the <option>-A</option>/<option>--select-ascription</option> option).</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term><option>-t <replaceable>TAG</replaceable></option>, <option>--tag=<replaceable>TAG</replaceable></option></term>
 <listitem>
 <para>The review tag, denoting the type of the review. If <literal>review-tags</literal> field in ascription configuration set, this must be one of the tags defined there (general review has an empty string as tag, which is the default). The tag is normally issued in <literal>diff</literal> mode: it will be appended to review flags on diffed messages (e.g. <literal>ediff/<replaceable>tag</replaceable></literal>), which will cause on commit that the review of this type is ascribed. In <literal>commit</literal> mode, this option has effect only if <option>--all-reviewed</option> is issued as well, in which case this tag will override any from the PO file. Several tags may be given as comma-separated list.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term><option>-u <replaceable>NAME</replaceable></option>, <option>--user=<replaceable>NAME</replaceable></option></term>
 <listitem>
 <para>The user, one of those defined in ascription configuration, to whom modifications and reviews are ascribed on commit.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term><option>-U</option>, <option>--update-headers</option></term>
 <listitem>
 <para>If you work on PO files with a general text editor, you can issue this option on commit to have the header data in modified PO files automatically updated. The necessary information is fetched from the ascription configuration.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term><option>-v</option>, <option>--verbose</option></term>
 <listitem>
 <para>More detailed information on progress of the operation.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term><option>-w <replaceable>FILE</replaceable></option>, <option>--write-modified=<replaceable>FILE</replaceable></option></term>
 <listitem>
 <para>This option specifies the file into which to write the path of every PO file modified during the operation, one per line. This file can later be fed back to <command>poascribe</command> (and other Pology commands) with the <option>-f</option>/<option>--files-from</option> option.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term><option>-x <replaceable>FILE</replaceable></option>, <option>--externals=<replaceable>FILE</replaceable></option></term>
 <listitem>
 <para>If you have <link linkend="sec-prascsel">written some custom selectors</link>, with this option you specify the path to the file containing them. It can be repeated to load several files with custom selectors.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term><option>--all-reviewed</option></term>
 <listitem>
 <para>On commit, normally only messages having <literal>ediff*</literal> or <literal>reviewed</literal> flags will be ascribed as reviewed. If this option is used, instead all messages will be ascribed as reviewed (except for those having <literal>unreviewed</literal> flag).</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"/>
 
 </variablelist>
 </para>
 
 </sect1>
 
 <!-- ======================================== -->
 <sect1 id="sec-ascconfig">
 <title>User Configuration</title>
 
 <para>The following <link linkend="sec-cmconfig">configuration</link> fields can be used to modify general behavior of <command>poascribe</command>:
 <variablelist>
 
 <varlistentry>
 <term><literal>[poascribe]/aselectors</literal></term>
 <listitem>
 <para>The list of explicit selectors of historical messages, as if they were issued with multiple <option>-a</option>/<option>--aselector</option> options. The first character in the value must be non-alphanumeric (e.g. <literal>/</literal>), and that character is then used to separate selector specifications; the value must also end with this character.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term><literal>[poascribe]/diff-reduce-history</literal></term>
 <listitem>
 <para>Counterpart to <option>-D</option>/<option>diff-reduce-history</option> command line option.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term><literal>[poascribe]/filters</literal></term>
 <listitem>
 <para>Comma-separated list of history filters, as if they were issued with multiple <option>-F</option>/<option>--filter</option> options.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term><literal>[poascribe]/max-fraction-select</literal></term>
 <listitem>
 <para>Counterpart to <option>-L</option>/<option>max-fraction-select</option> command line option.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term><literal>[poascribe]/min-adjsim-diff</literal></term>
 <listitem>
 <para>Counterpart to <option>-A</option>/<option>--min-adjsim-diff</option> command line option.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term><literal>[poascribe]/po-editor</literal></term>
 <listitem>
 <para>Counterpart to <option>-o</option>/<option>--open-in-editor</option> command line option.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term><literal>[poascribe]/selectors</literal></term>
 <listitem>
 <para>List of message selectors, as if they were issued with multiple <option>-s</option>/<option>--selector</option> options. The first character in the value must be non-alphanumeric (e.g. <literal>/</literal>), and that character is then used to separate selector specifications; the value must also end with this character.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term><literal>[poascribe]/tags</literal></term>
 <listitem>
 <para>Counterpart to <option>-t</option>/<option>--tag</option> command line option.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term><literal>[poascribe]/update-headers=[yes|*no]</literal></term>
 <listitem>
 <para>Setting to <literal>yes</literal> is counterpart to <option>-U</option>/<option>--update-headers</option> command line option.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term><literal>[poascribe]/user</literal></term>
 <listitem>
 <para>Counterpart to <option>-u</option>/<option>--user</option> command line option.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term><literal>[poascribe]vcs-commit/=[*yes|no]</literal></term>
 <listitem>
 <para>Setting to <literal>no</literal> is counterpart to <option>-C</option>/<option>--no-vcs-commit</option> command line option.</para>
 </listitem>
 </varlistentry>
 
 </variablelist>
 </para>
 
 </sect1>
 
 <!-- ======================================== -->
 <sect1 id="sec-ascsels">
 <title>Review Selectors</title>
 
 <para><command>poascribe</command> provides a variety of internal selectors, and new selectors are added as general need for them is observed in practice. Selectors come in two types: history and shallow; the former also select a historical message from which to show the differences to the current message, while the latter do not. Arguments to selectors are added consistently separated with any non-alphanumeric character, customarily colon (<literal>:</literal>) when possible. If less arguments are given than the selector can take, all remaining arguments are set to empty (the selector may or may not accept this).</para>
 
 <para>Available internal selectors are as follows:
 <variablelist>
 
 <varlistentry>
 <term><literal>any</literal> (shallow)</term>
 <listitem>
 <para>Selects any message.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term><literal>active</literal> (shallow)</term>
 <listitem>
 <para>Selects active messages, i.e. those translated and not obsolete.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term><literal>asc:<replaceable>USER</replaceable></literal> (history)</term>
 <listitem>
 <para>Selects latest historical message ascribed (modified or reviewed) by the given user, or to any user if the argument is empty. Multiple users can be given as a comma-separated list, and selection inverted by prepending <literal>~</literal>.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term><literal>branch:<replaceable>NAME</replaceable></literal> (shallow)</term>
 <listitem>
 <para>Selects messages belonging to the given branch (see <xref linkend="ch-summit"/>). Several branch names may be given, as comma-separated list.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term><literal>current</literal> (shallow)</term>
 <listitem>
 <para>Selects current messages, i.e. those not obsolete.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term><literal>e:<replaceable>ENTRYNUM</replaceable></literal> (shallow)</term>
 <listitem>
 <para>Selects a message with given entry number in the PO file (first message has entry number 1, second 2, etc).</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term><literal>espan:<replaceable>START</replaceable>:<replaceable>END</replaceable></literal> (shallow)</term>
 <listitem>
 <para>Select messages with entry numbers between given start and end, including both. If start is empty, 1 is assumed; if end is empty, number of messages is assumed.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term><literal>fexpr:<replaceable>EXPRESSION</replaceable></literal> (shallow)</term>
 <listitem>
 <para>Selects messages matching a boolean search expression on message parts. It has same syntax as the <link linkend="p-fexprdesc"><literal>fexpr</literal> parameter</link> of the <command>find-messages</command> sieve.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term><literal>hexpr:<replaceable>EXPRESSION</replaceable>:<replaceable>USER</replaceable>:<replaceable>DIFFSPEC</replaceable></literal> (history)</term>
 <listitem>
 <para>Like <literal>fexpr</literal>, but matches through historical messages starting from the latest ascription. If user argument is not empty, matches only messages ascribed to that user. Multiple users can be given as a comma-separated list, and selection inverted by prepending <literal>~</literal>. The last argument, if not empty, requests to reduce historical messages by incremental differences before matching them; see the <option>--diff-reduce-history</option> option for the syntax and other details.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term><literal>l:<replaceable>LINENUM</replaceable></literal> (shallow)</term>
 <listitem>
 <para>Selects a message with given referent line number in the PO file. This is the line number of <varname>msgid</varname> message field. ±1 offset is accepted.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term><literal>lspan:<replaceable>START</replaceable>:<replaceable>END</replaceable></literal> (shallow)</term>
 <listitem>
 <para>Select messages with referent line numbers between given start and end, including both. If start is empty, 1 is assumed; if end is empty, total number of lines is assumed.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term><literal>mod:<replaceable>USER</replaceable></literal> (history)</term>
 <listitem>
 <para>Selects latest historical message modified by the given user, or by any user if the argument is empty. Multiple users can be given as a comma-separated list, and selection inverted by prepending <literal>~</literal>.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term><literal>modafter:<replaceable>TIMESTAMP</replaceable>:<replaceable>USER</replaceable></literal> (history)</term>
 <listitem>
 <para>Selects the earliest historical message modified at or after the given date and time. The full timestamp format is <literal><replaceable>YEAR</replaceable>-<replaceable>MONTH</replaceable> <replaceable>DAY</replaceable> <replaceable>HOUR</replaceable>:<replaceable>MINUTE</replaceable>:<replaceable>SECOND</replaceable></literal>, but trailing elements can be omitted as logical; for example, <literal>2010-10</literal> would be interpreted as <literal>2010-10-01 00:00:00</literal>. If the user argument is not empty, only modifications by that user are considered; multiple users can be given as a comma-separated list, and selection inverted by prepending <literal>~</literal>.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term><literal>modam:<replaceable>USER1</replaceable>:<replaceable>USER2</replaceable></literal> (history)</term>
 <listitem>
 <para>Selects the earliest historical message which introduced modifications after the last modification, or the very first historical message. This makes sense only if one or both of the user arguments are not empty. If the first user argument is not empty, only modifications by that user are considered for selection. If the second user argument is not empty, only the modifications by that user are considered as base. For both user arguments, multiple users can be given as a comma-separated list, and selection inverted by prepending <literal>~</literal>.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term><literal>modar:<replaceable>MODUSER</replaceable>:<replaceable>REVUSER</replaceable>:<replaceable>TAG</replaceable></literal> (history)</term>
 <listitem>
 <para>Selects the earliest historical message which introduced modifications after the last review, or the very first historical message if there was no review yet. If the first user argument is not empty, only modifications by that user are considered and reviews by that user are ignored. If the second user argument is not empty, only reviews by that user are considered and modifications by that user are ignored. For both user arguments, multiple users can be given as a comma-separated list, and selection inverted by prepending <literal>~</literal>. The last argument determines which review types (by review tag) to consider, where empty value means "general review"; multiple tags can be given as comma-separated list.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term><literal>modarm:<replaceable>MODUSER</replaceable>:<replaceable>REVUSER</replaceable>:<replaceable>TAG</replaceable></literal> (history)</term>
 <listitem>
 <para>Like <literal>modar</literal>, but uses as base for selection the last review <emphasis>or</emphasis> the last modification. This generally makes sense only if some combination of user arguments is given too.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term><literal>rev:<replaceable>USER</replaceable></literal> (history)</term>
 <listitem>
 <para>Selects latest historical message reviewed by the given user, or by any user if the argument is empty. Multiple users can be given as a comma-separated list, and selection inverted by prepending <literal>~</literal>.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term><literal>revbm:<replaceable>REVUSER</replaceable>:<replaceable>MODUSER</replaceable>:<replaceable>TAG</replaceable></literal> (history)</term>
 <listitem>
 <para>Selects the earliest historical message which has been reviewed just before a modification occurred. If the first user argument is not empty, only reviews by that user are considered and modifications by that user are ignored. If the second user argument is not empty, only modifications by that user are considered and reviews by that user are ignored. For both user arguments, multiple users can be given as a comma-separated list, and selection inverted by prepending <literal>~</literal>. The last argument determines which review types (by review tag) to consider, where empty value means "general review"; multiple tags can be given as comma-separated list.</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term><literal>tmodar:<replaceable>MODUSER</replaceable>:<replaceable>REVUSER</replaceable>:<replaceable>TAG</replaceable></literal> (history)</term>
 <listitem>
 <para>Like <literal>modar</literal>, but considers as modified only those historical messages with modifications in translation (<varname>msgstr</varname>).</para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term><literal>unasc</literal> (shallow)</term>
 <listitem>
 <para>Select messages that are not yet ascribed, i.e. those which are modified but not yet committed.</para>
 </listitem>
 </varlistentry>
 
 </variablelist>
 </para>
 
 <para>Every selector automatically gets a negative counterpart, with the name prefixed by <literal>n*</literal>. The negative selector is always shallow, regardless of the type of the original selector.</para>
 
 <sect2 id="sec-asccustsels">
 <title>Custom Review Selectors</title>
 
 <para>Custom selectors can be written in a standalone Python source file, which is then fed to <command>poascribe</command> using the <option>-x</option>/<option>--externals</option> option. A file with several custom selectors should have this layout:
 <programlisting language="python">
 def selector_foo (args):
     ...
 
 def selector_bar (args):
     ...
 
 asc_selector_factories = {
     # key: (factory, is_history_selector)
     "foo": (selector_foo, False),
     "bar": (selector_bar, True),
 }
 </programlisting>
 <function>selector_foo</function> and <function>selector_bar</function> are factory functions for selectors <literal>foo</literal> and <literal>bar</literal>. After loading the file, <command>poascribe</command> will look for the <varname>asc_selector_factories</varname> dictionary to see which selectors are defined and of what type they are. See <xref linkend="sec-prascsel"/> for the instructions on writing selector factory functions.</para>
 
 </sect2>
 
 </sect1>
 
 </chapter>