Referring Expressions

This is the documentation for 3.2.1 version, which is not the latest version. Consider upgrading to 4.3.0.

Simple example

In a specific text you often make a reference to the same thing again and again. Often it is the main thing you talk about: a hotel when you describe hotels, a financial fund if you ever want to talk about a financial fund, etc. But you won’t want to mention it again and again using the same words:

*The ring* is made of gold. The ring has one diamond. The ring can be used to rule them all.

You would prefer:

*The ring* is made of gold. This jewel has one diamond. It can be used to rule them all.

So we would wish to configure:

  1. How to mention the object the first time we talk about it (here the ring): this is called the reference.

  2. How to mention it afterwards (here this jewel, it, etc.): this is called a referring expression.

Referring expression generation is a classic and complex topic in NLG, but we will keep it very simple.

This is how to define references and referring expressions. We assume that you have a js object called PRODUCT.

you can only reference a mixin as ref or refexpr after it was defined.

In the signature of the re/ref mixins:

  • obj is the object itself (here PRODUCT)

  • params are additional parameters

Then you just trigger the reference or a referring expression using the value mixin. The system automatically chooses when to trigger the reference and when to trigger a referring expression.

p #[+value(PRODUCT)]  / #[+value(PRODUCT)] / #[+value(PRODUCT)] / #[+value(PRODUCT)]

This will output the ring / it / this jewel / it (referring expressions are randomly choosen here).

Other mixins using Reference and Referring expressions

The value mixin is a direct way to trigger them. But other mixins also use this mechanism:

  • thirdPossession(THE_DIAMONDS, 'color') will output the color of the diamonds or their color

  • subjectVerb and subjectVerbAdj: for instance, +subjectVerb(PRODUCT, 'shine') will output the ring shines or it shines.

Force representant & reset

Sometimes you just want to force which representation to use (reference or referring expression) at a specific place.

  • #[+value(PRODUCT, {REPRESENTANT: 'ref'})] will force the representant representation.

  • #[+value(PRODUCT, {REPRESENTANT: 'refexpr'})] will force the referring expression representation.

Sometimes you also whish to reset the representant back to its reference. This is often done when changing paragraph or section in a same document. Use resetRep:

- resetRep(PRODUCT)

Referring expressions and gender/number

In English you don’t care about the gender of an object. But you do care about its number. For instance, let’s talk about earrings:

  • Representant will be earrings.

  • Referring expressions will be these earrings or this jewel

This issue is that the agreement of the verb depends of the chosen referring expression: These earrings are beautiful / This jewel is beautiful. In some languages like French you have to care for both gender and number.

To deal with this just mention the gender and/or the number each time a reference or a referring expression is triggered. Default gender is masculine and default number is singular.

Setting explicitely the number

You can have fun and trigger it or they as a referring expression depending on the current number of the object.

Setting the gender

Use setRefGender to change the gender:

  • Accepts a direct gender value: M/F for French, M/F/N for German.

  • Or, in French, German, Italian and Spanish, a word: the gender will be lookup in the dictionnary.

  • Or, in French, German, Italian and Spanish, #[+value('bague', {represents: PRODUIT})] will output bague and set the gender of PRODUIT to F via the dictionnary.

You can use some syntactic sugar to simplify the structures. An example in German:

Will output:

  • if case is NOMINATIVE: das Telefon / diese Gurke / diese Gurke / dieses Handy / dieses Handy etc.

  • if case is GENITIVE: des Telefons / dieser Gurke / dieses Telefons / des Telefons / dieser Gurke etc.

addToParams is a shortcut that completes the params parameter (it has to have that exact name) with more properties. Behind the scenes it is just an Object.assign call. Use it often!

Getting information about the next representant

aka predicting the future.

Sometimes you need to know what the next reference will be, especially its characteristics (gender, number, referential or referring expression), but without actually triggering it. This is useful:

  • In some languages like French where you have to agree with something that will only appear later: in "Fabriquées en or, les boucles d’oreilles", "Fabriquées" agrees with "boucles d’oreilles", even if "boucles d’oreilles" is only output after it.

  • Internally for mixins like thirdPossession(THE_DIAMONDS, 'color') which can output the color of the diamonds or their color: when they output the color of, they already know that the next representant is the reference.

The js function getNextRep(obj) will give you an object containing properties of the next representant. On this object functions like getRefGender or getRefNumber will work. Still most of the time you may use it as it in a agreeAdj mixin:

#[+agreeAdj('fabriqué', getNextRep(PRODUIT))]
You must not call getNextRep from within a ref or refexpr functions. It will not trigger an error, but it will return a wrong result.