Warning, /sdk/pology/doc/user/programming.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"
 [
     <!ENTITY apibase "../../api/en_US">
     <!ENTITY ap "&apibase;/pology.">
     <!ENTITY amm "-module.html">
     <!ENTITY am "&amm;#">
     <!ENTITY acc "-class.html">
     <!ENTITY ac "&acc;#">
 ]>
 
 <chapter id="ch-prog">
 <title>Programming with Pology</title>
 
 <para>You may find it odd that the user manual contains the section on programming, as that is normally the matter for a separate, programmer-oriented document. On the other hand, while reading the "pure user" sections of this manual, you may have noticed that in Pology the distinction between a user and a programmer is more blurry than one would expect of a translation-related tool. Indeed, before getting into writing standalone Python programs which use the Pology library, there are many places in Pology itself where you can plug in some Python code to adapt the behavior to your language and translation environment. This section exists to support and stimulate such interaction with Pology.</para>
 
 <para>The Pology library is quite simple conceptually and organizationally. It consists of a small core abstraction of the PO format, and a lot of mutually unrelated functionality that may come in handy in particular translation processing scenarios. Everything is covered by <ulink url="&apibase;">the Pology API documentation</ulink>, but since API documentation tends to be non-linear and full of details obstructing the bigger picture, the following subsections are there to provide synthesis and rationale of salient points.</para>
 
 <!-- ======================================== -->
 <sect1 id="sec-prfile">
 <title>PO Format Abstraction</title>
 
 <para>The PO format abstraction in Pology is a quite direct and fine-grained reflexion of PO format elements and conventions. This was a design goal from the start; no attempt was made at a more general abstraction, which would tentatively support various translation file formats.</para>
 
 <para>There is, however, one glaring but intentional omission: multi-domain PO files (those which contain <literal>domain "..."</literal> directives) are not supported. We had never observed a multi-domain PO file in the wild, nor thought of a significant advantage it could have today over multiple single-domain PO files. Supporting multi-domain PO files would mean not only always needing two nested loops to iterate through messages in a PO file, but it would also interfere with higher levels in Pology which assume equivalence between PO files and domains. Pology will simply report an error when trying to read a multi-domain PO file.</para>
 
 <sect2 id="sec-prflmon">
 <title>Monitored Objects</title>
 
 <para>Because the PO abstraction is intended to be robust against programming errors when quickly writting custom scripts, and frugal on file modifications, by default some of the abstracted objects are "monitored". This means that they are checked for expected data types and have modification counters. Main monitored objects are PO files, PO headers, and PO messages, but also their attributes which are not plain data types (strings or numbers). For the moment, these secondary monitored types include <ulink url="&ap;monitored.Monlist&acc;"><classname>Monlist</classname></ulink> (the monitored counterpart to built-in <type>list</type>), <ulink url="&ap;monitored.Monset&acc;"><classname>Monset</classname></ulink> (counterpart to <type>set</type>), and <ulink url="&ap;monitored.Monpair&acc;"><classname>Monpair</classname></ulink> (like two-element <type>tuple</type>). Monitored types do not in general provide the full scope of functionality of their built-in counterparts, so sometimes it may be easier (and faster) to work with built-in types and convert them to monitored at the moment of adding to PO objects.</para>
 
 <para>To take a <classname>Monlist</classname> instance as an example, here is how it behaves on its own:
 <programlisting language="python">
 >>> from pology.monitored import Monlist
 >>> l = Monlist(["a", "b", "c"])
 >>> l.modcount
 0
 >>> l.append(10)
 >>> l
 Monlist(["a", "b", "c", 10])
 >>> l.modcount
 1
 >>>
 </programlisting>
 Appending an element has caused the modification counter to increase, but, as expected, it was possible to add an integer in spite of previous elements being strings. However, if the monitored list comes from a PO message:
 <programlisting language="python">
 >>> from pology.message import Message
 >>> msg = Message()
 >>> msg.msgstr
 Monlist([])
 >>> msg.msgstr.append(10)
 Traceback (most recent call last):
 ...
 pology.PologyError: Expected &lt;type 'unicode'&gt; for sequence element, got &lt;type 'int'&gt;.
 >>> msg.msgstr.append("bar")
 >>> msg.msgstr.modcount
 1
 >>> msg.modcount
 1
 </programlisting>
 The <classname>Message</classname> class has type constraints added to its attributes, and therefore addition of an integer to the <varname>.msgstr</varname> list was rejected: only <type>str</type> values are allowed, to prevent carelessness with encodings. Once a proper string was added to <varname>.msgstr</varname> list, its modification counter increased, but also the modification counter of the parent object.</para>
 
 <para>A few more notes on modification counters. Consider this example:
 <programlisting language="python">
 >>> msg = Message()
 >>> msg.msgstr = Monlist("foo")
 >>> msg.msgstr.modcount
 0
 >>> msg.msgstr_modcount
 1
 >>> msg.modcount
 1
 >>> msg.msgstr[0] = "foo"
 >>> msg.msgstr.modcount
 0
 >>> msg.msgstr = Monlist("foo")
 >>> msg.msgstr_modcount
 1
 >>> msg.modcount
 1
 </programlisting>
 <literal>Monlist("foo")</literal> itself is a fresh list with modification counter at 0, so after it was assigned to <varname>msg.msgstr</varname>, its modification counter is still 0. However, every attribute of a parent monitored object also has the associated <emphasis>attribute</emphasis> modification counter, denoted with trailing <literal>_modcount</literal>; therefore <varname>msg.msgstr_modcount</varname> did increase on assignment, and so did the parent <varname>msg.modcount</varname>. Modification tracking actually checks for equality of values, so when same-valued objects are repeadetly assigned (starting from <literal>msg.msgstr[0] = "foo"</literal> above), modification counters do not increase.</para>
 
 <para>Compound monitored objects may also have the attributes themselves constrained, to prevent typos and other brain glitches from causing mysterious wrong behavior when processing PO files. For example:
 <programlisting language="python">
 >>> msg = Message()
 >>> msg.msgtsr = Monlist("foo")
 Traceback (most recent call last):
 ...
 pology.PologyError: Attribute 'msgtsr' is not among specified.
 >>>
 </programlisting>
 </para>
 
 <para>You may conclude that modification tracking and type and attribute constraining would slow down processing, and you would be right. Since PO messages are by far the most processed objects, a non-monitored counterpart to <classname>Message</classname> is provided as well, for occasions where the code is only reading PO files, or has been sufficiently tested, and speed is of importance. See <xref linkend="sec-prflmsg"/> for details.</para>
 
 </sect2>
 
 <sect2 id="sec-prflmsg">
 <title>Message</title>
 
 <para>PO messages are by default represented with the <ulink url="&ap;message.Message&acc;"><classname>Message</classname></ulink> class. It is monitored for modifications, and constrained on attributes and attribute types. It provides direct attribute access to parts of a PO message:
 <programlisting language="python">
 >>> from pology.monitored import Monpair
 >>> from pology.message import Message
 >>> msg = Message()
 >>> msg.msgid = "Foo %s"
 >>> msg.msgstr.append("Bar %s")
 >>> msg.flag.add("c-format")
 >>> msg.fuzzy = True
 >>> print msg.to_string(),
 #, fuzzy, c-format
 msgid "Foo %s"
 msgstr "Bar %s"
 
 >>>
 </programlisting>
 Attribute access provides the least hassle, while being guarded by monitoring, and makes clear the semantics of particular message parts. For example, the <varname>.flag</varname> attribute is a set, to indicate that the order of flags should be of no importance to either a human translator or a PO processor, and the <varname>.msgstr</varname> attribute is always a list in order to prevent the programmer from not taking into account plural messages. While the fuzzy state is formally indicated by a flag, it is considered special enough to have a separate attribute.</para>
 
 <para>Some message parts may or may not be present in a message, and when they are not present, the corresponding attributes are either empty if sequences (e.g. <varname>.manual_comment</varname> list for translator comments), or set to <literal>None</literal> if strings<footnote>
 <para>The canonical way to check if message is a plural message is <literal>msg.msgid_plural is not None</literal>.</para>
 </footnote> (e.g. <varname>.msgctxt</varname>).</para>
 
 <para>There are also several derived, read-only attributes for special purposes. For example, if in some context the messages are to be tracked in a dictionary by their keys, there is the <varname>.key</varname> attribute available, which is an undefined but unique combination of <varname>.msgctxt</varname> and <varname>.msgid</varname> attributes. Or, there is the <varname>.active</varname> attribute which is <literal>True</literal> if the message is neither fuzzy nor obsolete, i.e. its translation (if there is one) would be used by the consumer of the PO file that the message is part of.</para>
 
 <para><classname>Message</classname> has a number of methods for frequent operations that need to read or modify more than one attribute. For example, to thoroughly unfuzzy a message, it is not sufficient to just remove its fuzzy flag (by setting <varname>.fuzzy</varname> to <literal>False</literal> or removing <literal>"fuzzy"</literal> from <varname>.flag</varname> set), but previous field comments (<literal>#| ...</literal>) should be removed as well, and this is what <function>.unfuzzy()</function> method does:
 <programlisting language="python">
 >>> print msg.to_string(),
 #| msgid "Foubar"
 #, fuzzy
 msgid "Foobar"
 msgstr "Fubar"
 
 >>> msg.unfuzzy()
 >>> print msg.to_string(),
 msgid "Foobar"
 msgstr "Fubar"
 
 </programlisting>
 Other methods include those to copy over a subset of parts from another message, to revert the message to pristine untranslated state, and so on.</para>
 
 <para>There exists a non-monitored counterpart to <classname>Message</classname>, the <ulink url="&ap;message.MessageUnsafe&acc;"><classname>MessageUnsafe</classname></ulink>class. Its attributes are of built-in types, e.g. <varname>.msgstr</varname> is plain <classname>list</classname>, and there is no type nor attribute checking. By using <classname>MessageUnsafe</classname>, a speedup of 50% to 100% has been observed in practical applications, so it makes for a good trade-off when you know what you are doing (e.g. you are certain that no modifications will be made). A PO file is opened with non-monitored messages by issuing the <literal>monitored=False</literal> argument to <classname>Catalog</classname> constructor.</para>
 
 <para>Read-only code could should work with <classname>Message</classname> and <classname>MessageUnsafe</classname> objects without any type-based specialization. Code that writes may need some care to achieve the same, for example:
 <programlisting language="python">
 def translate_moo_as_mu (msg):
 
     if msg.msgid == "Moo!":  # works for both
         msg.msgstr = ["Mu!"]  # raises exception if Message
         msg.msgstr[:] = ["Mu!"]  # works for both
         msg.msgstr[0] = "Mu!"  # works for both (when not empty)
 </programlisting>
 If you need to create an empty message of the same type as another message, or make a same-type copy of the message, you can use <function>type</function> built-in:
 <programlisting language="python">
 newmsg1 = type(msg)()  # create empty
 newmsg2 = type(msg)(msg)  # copy
 </programlisting>
 <classname>Message</classname> and <classname>MessageUnsafe</classname> share the virtual base class <classname>Message_base</classname>, so you can use <literal>isinstance(obj, Message_base)</literal> to check if an object is a PO message of either type.</para>
 
 </sect2>
 
 <sect2 id="sec-prflhead">
 <title>Header</title>
 
 <para>The PO header could be treated as just another message, but that would both be inconvenient for operating on it, and disruptive in iteration over a catalog. Instead the <ulink url="&ap;header.Header&acc;"><classname>Header</classname></ulink> class is introduced. Similar to <classname>Message</classname>, it provides both direct attribute access to parts of the header (like the <varname>.field</varname> list of name-value pairs), and methods for usual manipulations which would need a sequence of basic data manipulations (like <function>.set_field()</function> to either modify an existing or add a new header field with the given value).</para>
 
 <para>In particular, header comments are represented by a number of attributes (<varname>.title</varname>, <varname>.author</varname>, etc.), some of which are strings and some lists, depending on semantics. Unfortunatelly, the PO format does not define this separation formally, so when the PO file is parsed, comments are split heuristically (<varname>.title</varname> will be the first comment line, <varname>.author</varname> will get every line which looks like it has an email address and a year in it, etc.)</para>
 
 <para><classname>Header</classname> is a monitored class just like <classname>Message</classname>, but unlike <classname>Message</classname> it has no non-monitored counterpart. This is because in practice the header operations make a small part of total processing, so there is no real advantage at having non-monitored headers.</para>
 
 </sect2>
 
 <sect2 id="sec-prflcat">
 <title>Catalog</title>
 
 <para>PO files are read and written through <ulink url="&ap;catalog.Catalog&acc;"><classname>Catalog</classname></ulink> objects. A small script to open a PO file on disk (given as the first argument), find all messages that contain a certain substring in the original text (given as the second argument), and write those messages to standard output, would look like this:
 <programlisting language="python">
 import sys
 from pology.catalog import Catalog
 from pology.msgreport import report_msg_content
 
 popath = sys.argv[1]
 substr = sys.argv[2]
 
 cat = Catalog(popath)
 for msg in cat:
     if substr in msg.msgid:
         report_msg_content(msg, cat)
 </programlisting>
 Note the minimalistic code, both by raw length and access interface. Instead of using something like <literal>print msg.to_string()</literal> to output the message, already in this example we introduce the <ulink url="&ap;msgreport&amm;"><literal>msgreport</literal></ulink> module, which contains various functions for reporting on PO messages;<footnote>
 <para>There is also the <ulink url="&ap;report&amm;"><literal>report</literal></ulink> module for reporting general strings. In fact, all code in Pology distribution is expected to use function from these modules for writing to output streams, and there should not be a <function>print</function> in sight.</para>
 </footnote> <function>report_msg_content()</function> will first output the PO file name and location of the message (line and entry number) within the file, and then the message content itself, with some highlighting (for field keywords, fuzzy state, etc.) if the output destination permits it. Since no modifications are done to messages, this example would be just as safe but run significantly faster if the PO file were opened in non-monitored mode. This is done by adding the <literal>monitored=False</literal> argument to <classname>Catalog</classname> constructor:
 <programlisting language="python">
 cat = Catalog(popath, monitored=False)
 </programlisting>
 and no other modification is required.</para>
 
 <para>When some messages are modified in a catalog created by opening a PO file on disk, the modifications will not be written back to disk until the <function>.sync()</function> method is called -- not even if the program exists. If the catalog is monitored and there were no modifications to it up to the moment <function>.sync()</function> is called, the file on disk will not be touched, and <function>.sync()</function> will return <literal>False</literal> (it returns <literal>True</literal> if the file is written).<footnote>
 <para>This holds only for catalogs created with monitoring, i.e. no <literal>monitored=True</literal> constructor argument. For non-monitored <function>.sync()</function> will always touch the file and report <literal>True</literal>.</para>
 </footnote> In a scenario where a bunch of PO files are processed, this allows you to report only those which were actually modified. Take as an example a simplistic<footnote>
 <para>As opposed to <link linkend="sv-find-messages">the <command>find-messages</command> sieve</link>.</para>
 </footnote> script to search and replace in translation:
 <programlisting language="python">
 import sys
 from pology.catalog import Catalog
 from pology.fsops import collect_catalogs
 from pology.report import report
 
 serchstr = sys.argv[1]
 replacestr = sys.argv[2]
 popaths = sys.argv[3:]
 
 popaths = collect_catalogs(popaths)
 for popath in popaths:
     cat = Catalog(popath)
     for msg in cat:
         for i, text in enumerate(msg.msgstr):
             msg.msgstr[i] = text.replace(searchstr, replacestr)
     if cat.sync():
         report("%s (%d)" % (cat.filename, cat.modcount))
 </programlisting>
 This script takes the search and replace strings as the first two arguments, followed by any number of PO paths. The paths do not have to be only file paths, but can also be directory paths, in which case the <function>collect_catalogs()</function> function from <ulink url="&ap;fsops&amm;"><literal>fsops</literal></ulink> module will recursively collect any PO files in them. After the search and replace iteration through a catalog is done (<varname>msgstr</varname> being properly handled on plain and plural messages alike), its <function>.sync()</function> method is called, and if it reports that the file was modified, the file's path and number of modified texts is output. The latter is obtained simply as the modification counter state of the catalog, since it was bumped up by one on each text that actually got modified. Note the use of <varname>.filename</varname> attribute for illustration, although in this particular case we had the path available in <varname>popath</varname> variable.</para>
 
 <para>Syncing to disk is an atomic operation. This means that if you or something else aborts the program in the middle of execution, none of the processed PO files will become corrupted; they will either be in their original state, or in the expected modified state.</para>
 
 <para>As can be seen, at its base the <classname>Catalog</classname> class is an iterable container of messages. However, the precise nature of this container is less obvious. To the consumer (a program or converter) the PO file is a dictionary of messages by keys (<varname>msgctxt</varname> and <varname>msgid</varname> fields); there can be no two messages with the same key, and the order of messages is of no importance. For the human translator, however, the order of messages in the PO file is of great importance, because it is one of <link linkend="sec-pocontext">context indicators</link>. Message keys are parts of the messages themselves, which means that a message is both its own dictionary key and the value. Taking these constraints together, in Pology the PO file is treated as an <emphasis>ordered set</emphasis>, and the <classname>Catalog</classname> class interface is made to reflect this.</para>
 
 <para>The ordered set nature of catalogs comes into play when the composition of messages, rather than just the messages themselves, is modified. For example, to remove all obsolete messages from the catalog, the <function>.remove()</function> method <emphasis>could</emphasis> be used:
 <programlisting language="python">
 for msg in list(cat):
     if msg.obsolete:
         cat.remove(msg)
 cat.sync()
 </programlisting>
 Note that the message sequence was first copied into a list, since the removal would otherwise clobber the iteration. Unfortunatelly, this code will be very slow (linear time wrt. catalog size), since when a message is removed, internal indexing has to be updated to maintain both the order and quick lookups. Instead, the better way to remove messges is the <function>.remove_on_sync()</function> method, which marks the message for removal on syncing. This runs fast (constant time wrt. catalog size) and requires no copying into a list prior to iteration:
 <programlisting language="python">
 for msg in cat:
     if msg.obsolete:
         cat.remove_on_sync(msg)
 cat.sync()
 </programlisting>
 </para>
 
 <para>A message is added to the catalog using the <function>.add()</function> method. If <function>.add()</function> is given only the message itself, it will overwrite the message with the same key if there is one such, or else insert it according to source references, or append it to the end. If <function>.add()</function> is also given the insertion position, it will insert the message at that position only if the message with the same key does not exist in the catalog; if it does, it will ignore the given position and overwrite the existing message. When the message is inserted, <function>.add()</function> suffers the same performance problem as <function>.remove()</function>: it runs in linear time. However, the common case when an empty catalog is created and messages added one by one to the end can run in constant time, and this is what <function>.add_last()</function> method does.<footnote>
 <para>In fact, <function>.add_last()</function> does a bit more: if both non-obsolete and obsolete messages are added in mixed order, in the catalog they will be separated such that all non-obsolete come before all obsolete, but otherwise maintaining the order of addition.</para>
 </footnote></para>
 
 <para>The basic way to check if a message with the same key exists in the catalog is to use the <literal>in</literal> operator. Since the catalog is ordered, if the position of the message is wanted, <function>.find()</function> method can be used instead. Both these methods are fast, running in constant time. There is a series of <function>.select_*()</function> methods for looking up messages by other than the key, which run in linear time, and return lists of messages since the result may not be unique any more.</para>
 
 <para>Since it is ordered, the catalog can be indexed, and that either by a position or by a message (whose key is used for lookup). To replace a message in the catalog with a message which has the same key but is otherwise different, you can either first fetch its position and then use it as the index, or use the message itself as the index:
 <programlisting language="python">
 # Idexing by position.
 pos = cat.find(msg)
 cat[pos] = msg
 
 # Indexing by message key.
 cat[msg] = msg
 </programlisting>
 This leads to the following question: what happens if you modify the key of a message (its <varname>.msgctxt</varname> or <varname>.msgid</varname> attributes) in the catalog? In that case the internal index goes out of sync, rather than being automatically updated. This is a necessary performance measure. If you need to change message keys, while doing that you should treat the catalog as a pure list, using only <literal>in</literal> iteration and positional indexing. Afterwards you should either call <function>.sync()</function> if you are done with the catalog, or <function>.sync_map()</function> to only update indexing (and remove messages marked with <function>.remove_on_sync()</function>) without writing out the PO file.</para>
 
 <para>The <classname>Catalog</classname> class provides a number of convenience methods which report things about the catalog based on the header information, rather than having to manually examine the header. These include the number of plural forms, the <varname>msgstr</varname> index for the given plural number, as well as information important in some Pology contexts, like language code, accelerator markers, markup types, etc. Each of these methods has a counterpart which sets the appropriate value, but this value is not written to disk when the catalog is synced. This is because frequently there are more ways in which the value can be determined from the header, so it is ambiguous how to write it out. Instead, these methods are used to set or override values provided by the catalog (e.g. based on command line options) for the duration of processing only.</para>
 
 <para>To create an empty catalog if it does not exist on disk, the <literal>create=True</literal> argument can be added to the constructor. If the catalog does exist, it will be opened as usual; if it did not exist, the new PO file will be written to disk on sync. To unconditionally create an empty catalog, whether the PO file exists or not at the given path, the <literal>truncate=True</literal> parameter should be added as well. In this case, if the PO file did exist, it will be overwritten with the new content only when the catalog is synced. The catalog can also be created with an empty string for path, in which case it is guaranteed to be empty even without setting <literal>truncate=True</literal>. If a catalog with empty path should later be synced (as opposed to being transient during processing), its <varname>.filename</varname> attribute can simply be assigned a valid path before calling <function>.sync()</function>.</para>
 
 <para>In summary, it can be said that the <classname>Catalog</classname> class is biased, in terms of performance and ease of use, towards processing existing PO files rather than creating PO files from scratch, and towards processing existing messages in the PO file rather than shuffling them around.</para>
 
 </sect2>
 
 </sect1>
 
 <!-- ======================================== -->
 <sect1 id="sec-prcodconv">
 <title>Coding Conventions</title>
 
 <para>This section describes the style and conventions that the code which is intended to be included in Pology distribution should adhere to. The general coding style is expected to follow the Python style guide described in <ulink url="http://www.python.org/dev/peps/pep-0008/">PEP 8</ulink>.</para>
 
 <para>Lines should be up to 80 characters long. Class names should be written in camel case, and all other names in lower case with underscores:
 <programlisting language="python">
 class SomeThingy (object):
     ...
 
     def some_method (self, ...):
 
         ...
         longer_variable = ...
 
 
 def some_function (...):
     ...
 </programlisting>
 Long expressions with operators should be wrapped in parentheses and before the binary operator, with the first line indented to the level of the other operand:
 <programlisting language="python">
 some_quantity = (  a_number_of_thingies * quantity_of_that_per_unit
                   + the_base_offset)
 </programlisting>
 In particular, long conditions in <literal>if</literal> and <literal>while</literal> statements should be written like this:
 <programlisting language="python">
 if (    something and something_else and yet_something
     and somewhere_in_between and who_knows_what_else
 ):
     do_something_appropriate()
 </programlisting>
 </para>
 
 <para>All messages, warnings, and errors should be issued through <ulink url="&ap;report&amm;"><literal>msgreport</literal></ulink> and <ulink url="&ap;msgreport&amm;"><literal>msgreport</literal></ulink> modules. There should be no <function>print</function> statements or raw writes to <literal>sys.stdout</literal>/<literal>sys.stderr</literal>.</para>
 
 <para>For the code in Pology library, it is always preferable to raise an exception instead of aborting execution. On the other hand, it is fine to add optional parameters by which the client can select if the function should abort rather than raise an exception. All topical problems should raise <classname>pology.PologyError</classname> or a subclass of it, and built-in exceptions only for simple general problems (e.g. <classname>IndexError</classname> for indexing past the end of something).</para>
 
 <sect2 id="sec-prcsi18n">
 <title>User-Visible Text and Internationalization</title>
 
 <para>All user-visible text, be it reports, warnings, errors (including exception messages) should be wrapped for internationalization through Gettext. The top <ulink url="&ap;pology&amm;"><literal>pology</literal></ulink> module provides several wrappers for Gettext functions, which have the following special traits: context is mandatory on every wrapped text, all format directives must be named, and arguments are specified as keyword-value pairs just after the text argument (unless deferred translation is used). Some examples:
 <programlisting language="python">
 # Simple message with context marker.
 _("@info",
   "Trying to sync unnamed catalog.")
 
 # Simple message with extended context.
 _("@info command description",
   "Keep track of who, when, and how, has translated, modified, "
   "or reviewed messages in a collection of PO files.")
 
 # Another context marker and extended context.
 _("@title:column words per message in original",
   "w/msg-or")
 
 # Parameter substitution.
 _("@info",
   "Review tag '%(tag)s' not defined in '%(file)s'.",
   tag=rev_tag, file=config_path)
 
 # Plural message
 n_("@item:inlist",
    "written %(num)d word", "written %(num)d words",
    num=nwords)
 
 # Deferred translation, when arguments are known later.
 tmsg = t_("@info:progress",
           "Examining state: %(file)s")
 ...
 msg = tmsg.with_args(file=some_path).to_string()
 </programlisting>
 Every context starts with the "context marker" in form of <literal>@<replaceable>keyword</replaceable></literal>, drawn from a predefined set (see the <ulink url="http://techbase.kde.org/Development/Tutorials/Localization/i18n_Semantics#Context_Markers">article on i18n semantics</ulink> at KDE Techbase); it is most often <literal>@info</literal> in Pology code. The context marker may be, and should be, followed by a free-form extend context whenever it can help the translator to understand how and where the message is used. It is usual to have the context, text and arguments in different lines, though not necessary if they are short enough to fit one line.</para>
 
 <para>Pology defines lightweight XML markup for coloring text in the <ulink url="&ap;colors&amm;"><literal>colors</literal></ulink> module. In fact, Gettext wrappers do not return ordinary strings, but <ulink url="&ap;colors.ColorString&acc;"><classname>ColorString</classname></ulink> objects, and functions from <literal>report</literal> and <literal>msgreport</literal> modules know how to convert it to raw strings for given output destination (file, terminal, web page...). Therefore you can use colors in any wrapped string:
 <programlisting language="python">
 _("@info:progress",
   "&lt;green&gt;History follows:&lt;/green&gt;")
 
 _("@info",
   "&lt;bold&gt;Context:&lt;/bold&gt; %(snippet)s",
   snippet=some_text)
 </programlisting>
 Coloring should be used sparingly, only when it will help to cue user's eyes to significant elements of the output.</para>
 
 <para>There are two consequences of having text markup available throughout. The first is that every message must be well-formed XML, which means that it must contain no unballanced tags, and that literal <literal>&lt;</literal> characters must be escaped (and then also <literal>&gt;</literal> for good style):
 <programlisting language="python">
 _("@item automatic name for anonymous input stream",
   "&amp;lt;stream-%(num)s&amp;gt;",
   num=strno)
 </programlisting>
 The other consequence is that <classname>ColorString</classname> instances must be joined and interpolated with dedicated functions; see <function>cjoin()</function> and <function>cinterp()</function> functions in <literal>colors</literal> module.</para>
 
 <para>Unless the text of the message is specifically intended to be a title or an insert (i.e. <literal>@title</literal> or <literal>@item</literal> context markers), it should be a proper sentence, starting with a capital letter and ending with a dot.</para>
 
 </sect2>
 
 </sect1>
 
 <!-- ======================================== -->
 <sect1 id="sec-prsieves">
 <title>Writing Sieves</title>
 
 <para><link linkend="ch-sieve">Pology sieves</link> are filtering-like processing elements applied by the <command>posieve</command> script to collections of PO files. A sieve can examine as well as modify the PO entries passed through it. Each sieve is written in a separate file. If the sieve file is put into <filename>sieve/</filename> directory of Pology distribution (or intallation), the sieve can be referenced on <command>posieve</command> command line by the shorthand notation; otherwise the path to the sieve file is given. The former is called an internal sieve, and the latter an external sieve, but the sieve file layout and the sieve definition are same for both cases.</para>
 
 <para>In the following, <command>posieve</command> will be referred to as "the client". This is because tools other than <command>posieve</command> may start to use sieves in the future, and it will also be described what these clients should adhere to when using sieves.</para>
 
 <sect2 id="sec-prsvlayout">
 <title>Sieve Layout</title>
 
 <para>The sieve file must define the <classname>Sieve</classname> class, with some mandatory and some optional interface methods and instance variables. There are no restrictions at what you can put into the sieve file beside this class, only keep in mind that <command>posieve</command> will load the sieve file as a Python module, exactly once during a single run.</para>
 
 <para>Here is a simple sieve (also the complete sieve file) which just counts the number of translated messages:
 <programlisting language="python">
 class Sieve (object):
 
     def __init__ (self, params):
 
         self.ntranslated = 0
 
     def process (self, msg, cat):
 
         if msg.translated:
             self.ntranslated += 1
 
     def finalize (self):
 
         report("Total translated: %d" % self.ntranslated)
 </programlisting>
 The constructor takes as argument an object specifying any sieve parameters (more on that soon). The <methodname>process</methodname> method gets called for each message in each PO file processed by the client, and must take as parameters the message (instance of <ulink url="&ap;message.Message_base&acc;"><classname>Message_base</classname></ulink>) and the catalog which contains it (<ulink url="&ap;catalog.Catalog&acc;"><classname>Catalog</classname></ulink>). The client calls the <methodname>finalize</methodname> method after no more messages will be fed to the sieve, but this method does need to be defined (client should check if it exists before placing the call).</para>
 
 <para>Another optional method is <methodname>process_header</methodname>, which the client calls on the PO header:
 <programlisting language="python">
 def process_header (self, hdr, cat):
     # ...
 </programlisting>
 <literal>hdr</literal> is an instance of <ulink url="&ap;header.Header&acc;"><classname>Header</classname></ulink>, and <literal>cat</literal> is the containing catalog. The client will check for the presence of this method, and if it is defined, it will call it prior to any <methodname>process</methodname> call on the messages from the given catalog. In other words, the client is not allowed to switch catalogs between two calls to <methodname>process</methodname> without calling <methodname>process_header</methodname> in between.</para>
 
 <para>There is also the optional <methodname>process_header_last</methodname> method, for which everything holds just like for <methodname>process_header</methodname>, except that, when present, the client must call it <emphasis>after</emphasis> all consecutive <methodname>process</methodname> calls on messages from the same catalog:
 <programlisting language="python">
 def process_header_last (self, hdr, cat):
     # ...
 </programlisting>
 </para>
 
 <para>Sieve methods should not abort program execution in case of errors, instead they should throw an exception. In particular, if the <methodname>process</methodname> method throws <ulink url="&ap;sieve.SieveMessageError&acc;"><classname>SieveMessageError</classname></ulink>, it means that the sieve can still process other messages in the same catalog; if it throws <ulink url="&ap;sieve.SieveCatalogError&acc;"><classname>SieveCatalogError</classname></ulink>, then any following messages from the same catalog must be skipped, but other catalogs may be processed. Similarly, if <methodname>process_header</methodname> throws <classname>SieveCatalogError</classname>, other catalogs may still be processed. Any other type of exception tells the client that the sieve should no longer be used.</para>
 
 <para>The <methodname>process</methodname> and <methodname>process_header</methodname> methods should either return <literal>None</literal> or an integer exit code. A return value which is neither <literal>None</literal> nor <literal>0</literal> indicates that while the evaluation was successfull (no exception was thrown), the processed entry (message or header) should not be passed further along the <link linkend="sec-svchains">sieve chain</link>.</para>
 
 </sect2>
 
 <sect2 id="sec-prsvparams">
 <title>Sieve Parameter Handling</title>
 
 <para>The <literal>params</literal> parameter of the sieve constructor is an object with data attributes as <link linkend="p-svparam">parameters which may influence</link> the sieve operation. The sieve file can define the <function>setup_sieve</function> function, which the client will call with
 a <ulink url="&ap;subcmd.SubcmdView&acc;"><classname>SubcmdView</classname></ulink> object as the single argument, to fill in the sieve description and define all mandatory and optional parameters. For example, if the sieve takes an optional parameter named <literal>checklevel</literal>, which controles the level (an integer) at which to perform some checks, here is how <function>setup_sieve</function> could look like:
 <programlisting language="python">
 def setup_sieve (p):
 
     p.set_desc("An example sieve.")
     p.add_param("checklevel", int, defval=0,
                 desc="Validity checking level.")
 
 
 class Sieve (object):
 
     def __init__ (self, params):
 
         if params.checklevel >= 1:
             # ...setup some level 1 validity checks...
         if params.checklevel >= 2:
             # ...setup some level 2 validity checks...
         #...
 
     ...
 </programlisting>
 See the <ulink url="&ap;subcmd.SubcmdView&ac;add_param"><methodname>add_param</methodname></ulink> method for details on defining sieve parameters.</para>
 
 <para>The client is not obliged to call <function>setup_sieve</function>, but it must make sure that the object it sends to the sieve as <literal>params</literal> has all the instance variable according to the defined parameters.</para>
 
 </sect2>
 
 <sect2 id="sec-prsvregime">
 <title>Catalog Regime Indicators</title>
 
 <para>There are two boolean instance variables that the sieve may define, and
 which the client may check for to decide on the regime in which the
 catalogs are opened and closed:
 <programlisting language="python">
 class Sieve (object):
 
     def __init__ (self, params):
 
         # These are the defaults:
         self.caller_sync = True
         self.caller_monitored = True
 
     ...
 </programlisting>
 The variables are:
 <itemizedlist>
 
 <listitem>
 <para><varname>caller_sync</varname> instructs the client whether catalogs processed by the sieve should be synced to disk at the end. If the sieve does not define this variable, the client should assume <literal>True</literal> and sync catalogs. This variable is typically set to <literal>False</literal> in sieves which do not modify anything, because syncing catalogs takes time.</para>
 </listitem>
 
 <listitem>
 <para><varname>caller_monitored</varname> tells the client whether it should open catalogs in monitored mode. If this variable is not set, the client should assume it <literal>True</literal>. This is another way of reducing processing time for sieves which do not modify PO entries.</para>
 </listitem>
 
 </itemizedlist>
 </para>
 
 <para>Usually a modifying sieve will set neither of these variables, i.e. catalogs will be monitored and synced by default, while a checker sieve will set both to <literal>False</literal>. For a modifying sieve that unconditionally modifies all entries sent to it, only <varname>caller_monitored</varname> may be set to <literal>False</literal> and <varname>caller_sync</varname> left undefined (i.e. <literal>True</literal>).</para>
 
 <para>If a sieve requests no monitoring or no syncing, the client is not obliged to satisfy these requests. On the other hand, if a sieve does request monitoring or syncing (either explicitly or by not defining the corresponding variables), the client must provide catalogs in that regime. This is because there may be several sieves operating at the same time (a sieve chain), and monitoring and syncing is usually necessary for proper operation of those sieves that request it.</para>
 
 </sect2>
 
 <sect2 id="sec-prsvnotes">
 <title>Further Notes on Sieves</title>
 
 <para>Since monitored catalogs have modification counters, the sieve may use them within its <methodname>process*</methodname> methods to find out if any modification really took place. The proper way to do this is to record the counter at start, and check for increase at end:
 <programlisting language="python">
 def process (self, msg, cat):
 
     startcount = msg.modcount
 
     # ...
     # ... do some stuff
     # ...
 
     if msg.modcount > startcount:
         self.nmodified += 1
 </programlisting>
 The <emphasis>wrong</emphasis> way to do it would be to merely check if <literal>msg.modcount > 0</literal>, because several modifying sieves may be operating at the same time, each increasing the counters.</para>
 
 <para>If the sieve wants to remove the message from the catalog, if at all possible it should use catalog's <methodname>remove_on_sync</methodname> instead of <methodname>remove</methodname> method, to defer actual removal to sync time. This is because <methodname>remove</methodname> will probably ruin client's iteration over the catalog, so if it must be used, the sieve documentation should state it clearly. <methodname>remove</methodname> also has linear execution time, while <methodname>remove_on_sync</methodname> has constant.</para>
 
 <para>If the sieve is to become part of Pology distribution, it should be properly documented. This means fully equipped <function>setup_sieve</function> function in the sieve file, and a piece of user manual documentation.
 The <classname>Sieve</classname> class itself should not be documented in general. Only when <methodname>process*</methodname> are returning an exit code, this should be stated in their own comments (and in the user manual).</para>
 
 </sect2>
 
 </sect1>
 
 <!-- ======================================== -->
 <sect1 id="sec-prhooks">
 <title>Writing Hooks</title>
 
 <para>Hooks are functions with specified sets of input parameters, return values, processing intent, and behavioral constraints. They can be used as modification and validation plugins in many processing contexts in Pology. There are three broad categories of hooks: filtering, validation and side-effect hooks.</para>
 
 <para>Filtering hooks modify some of their inputs. Modifications are done in-place whenever the input is mutable (like a PO message), otherwise the modified input is provided in a return value (like a PO message text field).</para>
 
 <para>Validation hooks perform certain checks on their inputs, and return a list of <emphasis>annotated spans</emphasis> or <emphasis>annotated parts</emphasis>, which record all the encountered errors:
 <itemizedlist>
 
 <listitem>
 <para id="p-annspans">Annotated spans are reported when the object of validation is a piece of text. Each span is a tuple of start and end index of the problematic segment in the text, and a note which explains the problem. The return value of a text-validation hook will thus be a list:
 <programlisting language="python">
 [(start1, end1, "note1"), (start2, end2, "note1"), ...]
 </programlisting>
 The note can also be <literal>None</literal>, if there is nothing to say about the problem.</para>
 </listitem>
 
 <listitem>
 <para id="p-annparts">Annotated parts are reported for an object which has more than one distinct piece of text, such as a PO message. Each annotated part is a tuple stating the name of the problematic part of the object (e.g. <literal>"msgid"</literal>, <literal>"msgstr"</literal>), the item index for array-like parts (e.g. for <literal>msgstr</literal>), and the list of problems in appropriate form (for a PO message this is a list of annotated spans).
 The return value of a PO message-validation hook will look like this:
 <programlisting language="python">
 [("part1", item1, [(start11, end11, "note11"), ...]),
  ("part2", item2, [(start21, end21, "note21"), ...]),
  ...]
 </programlisting>
 </para>
 </listitem>
 
 </itemizedlist>
 </para>
 
 <para>Side-effect hooks neither modify their inputs nor report validation information, but can be used for whatever purpose which is independent of the processing chain into which the hook is inserted. For example, a validation hook can be implemented like this as well, when it is enough that it reports problems to standard output, or where the hook client does not know how to use structured validation data (annotated spans or parts). The return value of a side-effect hook the number of errors encountered internally by the hook (an integer). Clients may use this number to decide upon further behavior. For example, if a side-effect hook modified a temporary copy of a file, the client may decide to abandon the result and use the original file if there were some errors.</para>
 
 <sect2 id="sec-prhktypes">
 <title>Hook Taxonomy</title>
 
 <para>In this section a number of hook types are described and assigned a formal
 type keyword, so that they can be conveniently referred to elsewhere in Pology documentation.</para>
 
 <para>Each type keyword has the form <emphasis>&lt;letter1&gt;&lt;number&gt;&lt;letter2&gt;</emphasis>, e.g. F1A. The first letter represents the hook category: <emphasis>F</emphasis> for filtering hooks, <emphasis>V</emphasis> for validation hooks, and <emphasis>S</emphasis> for side-effect hooks. The number enumerates the input signature by parameter types, and the final letter denotes the difference in semantics of input parameters for equal input signatures. As a handy mnemonic, each type is also given an informal signature in the form of <literal>(param1, param2, ...) -> result</literal>; in them, <literal>spans</literal> stand for <link linkend="p-annspans">annotated spans</link>, <literal>parts</literal> for <link linkend="p-annparts">annotated parts</link>, and <literal>numerr</literal> for number of errors.</para>
 
 <para>Hooks on pure text:
 <itemizedlist>
 <listitem>
 <para>F1A (<literal>(text) -> text</literal>): filters the text</para>
 </listitem>
 <listitem>
 <para>V1A (<literal>(text) -> spans</literal>): validates the text</para>
 </listitem>
 <listitem>
 <para>S1A (<literal>(text) -> numerr</literal>): side-effects on text</para>
 </listitem>
 </itemizedlist>
 </para>
 
 <para>Hooks on text fields in a PO message in a catalog:
 <itemizedlist>
 <listitem>
 <para>F3A (<literal>(text, msg, cat) -> text</literal>): filters any text field</para>
 </listitem>
 <listitem>
 <para>V3A (<literal>(text, msg, cat) -> spans</literal>): validates any text field</para>
 </listitem>
 <listitem>
 <para>S3A (<literal>(text, msg, cat) -> numerr</literal>): side-effects on any text field</para>
 </listitem>
 <listitem>
 <para>F3B (<literal>(msgid, msg, cat) -> msgid</literal>): filters an original text field; original fields are either <literal>msgid</literal> or <literal>msgid_plural</literal></para>
 </listitem>
 <listitem>
 <para>V3B (<literal>(msgid, msg, cat) -> spans</literal>): validates an original text field</para>
 </listitem>
 <listitem>
 <para>S3B (<literal>(msgid, msg, cat) -> numerr</literal>): side-effects on an original text field</para>
 </listitem>
 <listitem>
 <para>F3C (<literal>(msgstr, msg, cat) -> msgstr</literal>): filters a translation text field; translation fields are the <literal>msgstr</literal> array</para>
 </listitem>
 <listitem>
 <para>V3C (<literal>(msgstr, msg, cat) -> spans</literal>): validates a translation text field</para>
 </listitem>
 <listitem>
 <para>S3C (<literal>(msgstr, msg, cat) -> numerr</literal>): side-effects on a translation text field</para>
 </listitem>
 </itemizedlist>
 </para>
 
 <para>*3B and *3C hook series are introduced next to *3A for cases when it does not make sense for text field to be any other but one of the original, or translation fields. For example, to process the translation sometimes the original (obtained by <literal>msg</literal> parameter) must be consulted. If a *3B or *3C hook is applied on an inappropriate text field, the results are undefined.</para>
 
 <para>Hooks on PO entries in a catalog:
 <itemizedlist>
 <listitem>
 <para>F4A (<literal>(msg, cat) -> numerr</literal>): filters a message, modifying it</para>
 </listitem>
 <listitem>
 <para>V4A (<literal>(msg, cat) -> parts</literal>): validates a message</para>
 </listitem>
 <listitem>
 <para>S4A (<literal>(msg, cat) -> numerr</literal>): side-effects on a message (no modification)</para>
 </listitem>
 <listitem>
 <para>F4B (<literal>(hdr, cat) -> numerr</literal>): filters a header, modifying it</para>
 </listitem>
 <listitem>
 <para>V4B (<literal>(hdr, cat) -> parts</literal>): validates a header</para>
 </listitem>
 <listitem>
 <para>S4B (<literal>(hdr, cat) -> numerr</literal>): side-effects on a header (no modification)</para>
 </listitem>
 </itemizedlist>
 </para>
 
 <para>Hooks on PO catalogs:
 <itemizedlist>
 <listitem>
 <para>F5A (<literal>(cat) -> numerr</literal>): filters a catalog, modifying it in any way</para>
 </listitem>
 <listitem>
 <para>S5A (<literal>(cat) -> numerr</literal>): side-effects on a catalog (no modification)</para>
 </listitem>
 </itemizedlist>
 </para>
 
 <para>Hooks on file paths:
 <itemizedlist>
 <listitem>
 <para>F6A (<literal>(filepath) -> numerr</literal>): filters a file, modifying it in any way</para>
 </listitem>
 <listitem>
 <para>S6A (<literal>(filepath) -> numerr</literal>): side-effects on a file, no modification</para>
 </listitem>
 </itemizedlist>
 </para>
 
 <para>The *2* hook series (with signatures <literal>(text, msg) -> ...</literal>) has been skipped because no need for them was observed so far next to *3* hooks.</para>
 
 </sect2>
 
 <sect2 id="sec-prhkfact">
 <title>Hook Factories</title>
 
 <para>Since hooks have fixed input signatures by type, the way to customize
 a given hook behavior is to produce its function by another function.
 The hook-producing function is called a I{hook factory}. It works by
 preparing anything needed for the hook, and then defining the hook proper
 and returning it, thereby creating a lexical closure around it:
 <programlisting language="python">
 def hook_factory (param1, param2, ...):
 
     # Use param1, param2, ... to prepare for hook definition.
 
     def hook (...):
 
         # Perhaps use param1, param2, ... in the hook definition too.
 
     return hook
 </programlisting>
 </para>
 
 <para>In fact, most internal Pology hooks are defined by factories.</para>
 
 </sect2>
 
 <sect2 id="sec-prhknotes">
 <title>Further Notes on Hooks</title>
 
 <para>General hooks should be defined in top level modules, language-dependent hooks in <literal>lang.<replaceable>code</replaceable>.<replaceable>module</replaceable></literal>,
 project-dependent hooks in <literal>proj.<replaceable>name</replaceable>.<replaceable>module</replaceable></literal>,
 and hooks that are both language- and project-dependent in <literal>lang.<replaceable>code</replaceable>.proj.<replaceable>name</replaceable>.<replaceable>module</replaceable></literal>. Hooks placed like this can be fetched by <ulink url="&ap;getfunc&am;get_hook_ireq"><function>getfunc.get_hook_ireq</function></ulink> in various non-code contexts, in particular from Pology utilities which allow users to insert hooks into processing through command line options or configurations. If the complete module is dedicated to a single hook, the hook function (or factory) should be named same as the module, so that users can select it by giving only the hook module name.</para>
 
 <para><link linkend="p-annparts">Annotated parts</link> for PO messages returned by hooks are a reduced but valid instance of highlight specifications used by reporting functions, e.g. <ulink url="&ap;msgreport&am;report_msg_content"><function>msgreport.report_msg_content</function></ulink>. Annotated parts do not have the optional fourth element of a tuple in highlight specification, which is used to provide the filtered text against which spans were constructed, instead of the original text. If a validation hook constructs the list of problematic spans against the filtered text, just before returning it can apply <ulink url="&ap;diff&am;adapt_spans"><function>diff.adapt_spans</function></ulink>
 to reconstruct the spans against the original text.</para>
 
 <para>The documentation to a hook function should state the hook type within the short description, in square brackets at the end as <literal>[type ... hook]</literal>. Input parameters should be named like in the informal signatures in the taxonomy above, and should not be omitted in <literal>@param:</literal> Epydoc entries; but the return should be given under <literal>@return:</literal>, also using one of the listed return names, in order to complete the hook signature.</para>
 
 <para>The documentation to a hook factory should have <literal>[hook factory]</literal> at the end of the short description. It should normally list all the input parameters, while the return value should be given as <literal>@return: type ... hook</literal>, and
 the hook signature as the <literal>@rtype:</literal> Epydoc field.</para>
 
 </sect2>
 
 </sect1>
 
 <!-- ======================================== -->
 <sect1 id="sec-prascsel">
 <title>Writing Ascription Selectors</title>
 
 <para>Ascription selectors are functions used by <command>poascribe</command> in the translation review workflow as described in <xref linkend="ch-ascript"/>. This section describes how you can write your own ascription selector, which you can then put to use by following the instructions in <xref linkend="sec-asccustsels"/>.</para>
 
 <para>In terms of code, an ascription selector is a function factory, which construct the actual selector function based on supplied selector arguments. It has the following form:
 <programlisting language="python">
 # Selector factory.
 def selector_foo (args):
 
     # Validate input arguments.
     if (...):
         raise PologyError(...)
 
     # Prepare selector definition.
     ...
 
     # The selector function itself.
     def selector (msg, cat, ahist, aconf):
 
         # Prepare selection process.
         ...
 
         # Iterate through ascription history looking for something.
         for i, asc in enumerate(ahist):
             ...
 
         # Return False or True if a shallow selector,
         # and 0 or 1-based history index if history selector.
         return ...
 
     return selector
 </programlisting>
 It is customary to name the selector function <function>selector_<replaceable>something</replaceable></function>, where <replaceable>something</replaceable> will also be used as the selector name (in command line, etc). The input <varname>args</varname> parameter is always a list of strings. It should first be validated, insofar as possible without having in hand the particular message, catalog, ascription history or ascription configuration. Whatever does not depend on any of these can also be precomputed for later use in the selector function.</para>
 
 <para>The selector function takes as arguments the message (an instance of <ulink url="&ap;message.Message_base&acc;"><classname>Message_base</classname></ulink>), the catalog (<ulink url="&ap;catalog.Catalog&acc;"><classname>Catalog</classname></ulink>) it comes from, the ascription history (list of <ulink url="&ap;ascript.AscPoint&acc;"><classname>AscPoint</classname></ulink> objects), and the ascription configuration (<ulink url="&ap;ascript.AscConfig&acc;"><classname>AscConfig</classname></ulink>). For the most part, <classname>AscPoint</classname> and <classname>AscConfig</classname> are simple attribute objects; check their API documentation for the list and description of attributes. Some of the attributes of <classname>AscPoint</classname> objects that you will usually inspect are <varname>.msg</varname> (the historical version of the message), <varname>.user</varname> (the user to whom the ascription was made), or <varname>.type</varname> (the type of the ascription, one of <varname>AscPoint.ATYPE_*</varname> constants). The ascription history is sorted from the latest to the earliest ascription. If the <varname>.user</varname> of the first entry in the history is <literal>None</literal>, that means that the current version of the message has not been ascribed yet (e.g. if its translation has been modified compared to the latest ascribed version). If you are writing a shallow selector, it should return <literal>True</literal> to select the message, or <literal>False</literal> otherwise. In a history selector, the return value should be a 1-based index of an entry in the ascription history which caused the message to be selected, or <literal>0</literal> if the message was not selected.<footnote>
 <para>In this way the history selector can automatically behave as shallow selector as well, because simply testing for falsity on the return value will show whether the message has been selected or not.</para>
 </footnote></para>
 
 <para>The entry index returned by history selectors is used to compute embedded difference from a historical to the current version of the message, e.g. on <literal>poascribe diff</literal>. Note that <command>poascribe</command> will actually take as base for differencing the first non-fuzzy historical message <emphasis>after</emphasis> the indexed one, because it is assumed that already the historical message which triggered the selection contains some changes to be inspected. (When this behavior is not sufficient, <command>poascribe</command> offers the user to specify a second history selector, which directly selects the historical message to base the difference on.)</para>
 
 <para>Most of the time the selector will operate on messages covered by a single ascription configuration, which means that the ascription configuration argument sent to it will always be the same. On the other hand, the resolution of some of the arguments to the selector factory will depend only on the ascription configuration (e.g. a list of users). In this scenario, it would be waste of performance if such arguments were resolved anew in each call to the selector. You could instead write a small caching (memoizing) resolver function, which when called for the second and subsequent times with the same configuration object, returns previously resolved argument value from the cache. A few such caching resolvers for some common arguments have been provided in the <ulink url="&ap;ascript&amm;"><literal>ascript</literal></ulink> module, functions named <function>cached_*()</function> (e.g. <ulink url="&ap;ascript&am;cached_users"><function>cached_users()</function></ulink>).</para>
 
 </sect1>
 
 </chapter>