Help/Semantic links

Special markup elements allow editors to provide information on how to interpret links in the Rich Annotator System. Such pieces of information are called semantic annotations and they are created with a special markup.

Some annotations are necessary in the Rich Annotator System for automatic listings and for realize the main utility of the platform. Other annotations can be provided by editors as they like, but they should concert about it with administrators.

Classification and semantic annotations

Semantic annotations can be viewed as an extension of the category system. Categories are a means to classify pages. For example, by adding [[Category:Auteur(e)s]] to a page, it is tagged as describing in French a literary author.

Properties

Different pages have links and text values in them, but only a human reader knows what the link or text represents. Properties allow you to annotate any link or text on the page to describe the meaning of the hyperlink or text. This turns links and text into explicit properties of a page.

This enables users to go beyond mere categorisation of pages. Usage and possible problems with using these features are similar to the existing category system. Since categories and properties merely emphasize a particular part of a page's content, they are often called (semantic) annotations. Information that was provided in a page anyway, e.g. that À la recherche du temps perdu is a work of Marcel Proust, is now provided in a formal way accessible to software tools.

Besides annotations, administrators embed semantic queries into pages.

Creating properties

Properties are used by a simple markup, similar to the syntax of links: [[Property name::property value]]. This statement defines a value for the property of the given property name. The page where this is used will just show the text for value and not the property assignment.

The naming of properties is more important than one would probably expect at first. Property names should avoid ambiguity and confusion. Thus, it is good practice to create property names as a verb phrase. Here's an example that uses Maurice Carême and Médua to makes this practice more comprehensible:

One of Maurice Carême's works is Médua ↔ Médua is one of Maurice Carême's works.

In both cases one could assign a property named "Work", but this does not convey exactly the intended meaning. The first sentence says that Maurice Carême has a work entitled Médua, in other words he is the author of Médua. Therefore the better name for the property is "Author of":

One of Maurice Carême's works is [[Author of::Médua]].

Note that "Author of" is a property of "Maurice Carême" with value "Médua".

The second sentence states that Médua is one of Maurice Carême's works. Hence the better name for the property is "Work of" in this case. So the annotation avoiding ambiguity is as follows:

Médua is one of [[Work of::Maurice Carême]]'s works.

Note that "Work of" is a property of "Médua" with value "Maurice Carême".

Avoid using certain kinds of punctuation

Certain kinds of punctuation are to be avoided or have been declared invalid in property names, because they are also used as special syntax in semantic queries or they may cause problems for other reasons.

Do not use:

• :: (two subsequent colons) − a single colon should not cause any trouble
• - (hyphen) in initial position − for reasons to do with inverse properties
• . (dot) − operator used to link properties in concatenation
• | (pipe)
• # (number sign)

Best practice

• Use a verb phrase to describe a property.
• Use short names.

In-text annotation

Consider the page Médua. It contains links to other pages, such as "La Renaissance du livre" or "Maurice Carême". However, the link to "Maurice Carême" has a special meaning: it was put there since Médua is a work of Maurice Carême. To make this knowledge available to computer programs, one should "tag" the link [[Maurice Carême]] in the page text, identifying it as a link that describes a "work property". This is done by putting a property name and :: in front of the link inside the brackets, thus: [[Work of::Maurice Carême]].

In the page, this text is still displayed as a simple hyperlink to "Maurice Carême". The additional text Work of is the name of the property that classifies the link to Maurice Carême. As in the case of categories, the name of the property is arbitrary, but users should re-use properties that already appear elsewhere. See below property names to use in the Rich Annotator System.

To simplify this re-use, every property has its own article, just as every category has an article.

In-text annotations are case-sensitive and if changed arbitrarily may cause content to be rendered invalid or unavailable during query execution.

Turning links into properties

There are various ways of adding properties to pages:

What it does	What you type	What is to note
Classify a link with the property "example property."	Classify a [[Example property::link]] with the property "example property."
Make alternate text appear in place of the link.	Make [[Example property::link|alternate text]] appear in place of the link.
To hide the property from appearing at all, use a space as the alternate text.	To hide the property [[Example property::link| ]] from appearing at all use a space as the alternate text.	The space after “|” is necessary. If left away, the pipe trick applies, but rarely with desirable effects. → Consider using annotations with #set instead.

Silent annotations

The #set function allows to annotate data, i.e. assign values to a property, silently. If you want to, you can avoid the [[Property::value]] syntax (in-text annotation) using a #set call. This function takes in pairs of property names and values and stores them semantically; but it does not print anything to the screen. An example call would be: {{#set: Work of=Maurice Carême}}.

This parser function actually does not return anything, but saves the very same properties as data as the following silent or hidden in-text annotation would have: [[Work of::Maurice Carême| ]]. It is no longer needed doing it like this, you can just use a #set call as shown in the example above.

Silent annotations are recommended for the "Coauthor of" property of datatype "Text" (see below and Authors).

Datatypes

If one wants to create a property like e.g. "Work of", a datatype does not necessarily has to be specified since the default datatype for all properties with no explicit datatype declaration is datatype "Page", which displays assigned values as a link.

Page

The datatype Page is used for properties whose value is a page in the Rich Annotator System. These display as a link and may not be longer than 255 characters. This datatype is the default datatype of a property if a different datatype was not explicitly set. In other words, if you write [[Work of::Maurice Carême]], it is assumed that Work of is of type "Page" and that Maurice Carême is a page in the Rich Annotator System (whether or not it exists).

Text

The datatype Text is used to store strings of arbitrary length, i.e. text. If you want to store special character sequences, you need to store them using the function #set, instead of using in-text annotation syntax notation.

Properties to use in the Rich Annotator System

Properties already used are listed below. When you create a new link, consider classifying it if it corresponds to one of these properties. Note that a property can have a synonym: for example, the property "Work of" has the French synonym "Oeuvre de". Synonymic properties are interchangeable.

Property	French synonym	Example	Datatype and use
Author of	Auteur de Auteure de	Victor Hugo [[Author of::Les Travailleurs de la mer]]	Page.
Cited by	Cité par	Du côté de chez Swann/Partie 2 [[Cited by::Lire et voir (Anikó Ádám)	Page. Used when a literary text is cited in a reading.
Coauthor of	Coauteur de	Nicolas Bouvier {{#set: Coauteur de=[[L'Usage du monde]] (illustré par [[Thierry Vernet]])}}	Text. See Authors.
Has the volume	A le tome	À la recherche du temps perdu [[Has the volume::Du côté de chez Swann]]	Page. Used when a work has several volumes.
Linked to	En lien avec	Séphora [[Linked to::À la recherche du temps perdu]]	Page. Used when an image, an audio or a video is connected to an author or a text.
Part of	Partie de	Du côté de chez Swann/Partie 1 [[Partie de::Du côté de chez Swann]]	Page. Used when a literary text is divided into several parts. See also Texts.
Refers to	Fait référence à	Lire et voir (Anikó Ádám) [[Refers to::Roland Barthes]]	Page. Used when a reading refers to a text or an author.
Volume of	Tome de	Du côté de chez Swann [[Tome de::À la recherche du temps perdu]]	Page. Used when a work is one volume of a whole.
Work of	Oeuvre de	Du côté de chez Swann [[Work of::Marcel Proust]]	Page.

Back to contents