.. _section-Annotation using the special explain predicate:

Annotation using the special explain predicate
----------------------------------------------

In cases where the **english** property is still not enough, we support a special predicate, **%explain**, which allows the user to write arbitrary rules for english paraphrasing. This is primarily used for those rare cases where you need to paraphrase unusual term forms (e.g. lists) in a non-standard way, or need to do some other computations in order to produce the paraphrase.

For example, suppose we want to paraphrase the quantity functional term as mentioned in Section :ref:`section-Annotation using the english property`, but without the plural ’s’ when the magnitude is 1. Then we can write an explain-rule as follows:

.. code-block:: flora

   %explain(quantity(?X,?Y),?_vals,?str) :-
     \if ?m == 1 \then fmt_write_string(?str,'%S %S',f2(?X,?Y))@\io
     \else fmt_write_string(?str,'%S %Ss',f2(?X,?Y))@\io.

Note that this simple example glosses over many details of English morphology such as:

| ``  1 meter vs. 2 meters``
| ``  1 inch vs. 2 inches``
| ``  1 foot vs. 2 feet``
|

Suppose we use the functional term quantity as follows:

.. code-block:: flora

   Peter [ height -> quantity(2,meter) ].
   @!{'How tall is Peter?'(?X)} !- Peter [ height -> ?X ].

If we execute the query ’How tall is Peter?’ and click the question mark to see the result explanations in **English** mode, we will see the explanation paraphrased using the **%explain** rule, as shown in :numref:`figure-NL-height-explain.png`.

.. _figure-NL-height-explain.png:

.. figure:: ../figs/NL-height-explain.png
   :alt: The option **English** explains using the **%explain** rule for quantity

   The option **English** explains using the **%explain** rule for quantity

Suppose we add an **english** property to annotate the height property as follows:

.. code-block:: flora

   height [ english -> "%1 is %2 tall"^^\string].

Execute the query ’How tall is Peter?’ again. The result explanation will be paraphrased using a combination of the **%explain** rule and the **english** property for quantity, as shown in :numref:`figure-NL-height-explain-english.png`.

.. _figure-NL-height-explain-english.png:

.. figure:: ../figs/NL-height-explain-english.png
   :alt: Explanation uses a combination of **%explain** rule and **english** property

   Explanation uses a combination of **%explain** rule and **english** property