Voir la source de 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 [[Help/Categories|category]] system. Categories are a means to ''classify'' pages. For example, by adding <code><nowiki>[[Category:Auteur(e)s]]</nowiki></code> 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 [[Help/Links|links]]: <code><nowiki>[[</nowiki>''Property name''::''property value''<nowiki>]]</nowiki></code>. 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:

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

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":

<blockquote>One of Maurice Carême's works is <code><nowiki>[[Author of::Médua]]</nowiki></code>.</blockquote>

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:

<blockquote>''Médua'' is one of <code><nowiki>[[Work of::Maurice Carême]]</nowiki></code>'s works.</blockquote>

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:<br>
* <code>::</code> (two subsequent colons) − a single colon should not cause any trouble
* <code>-</code> (hyphen) in initial position − for reasons to do with inverse properties
* <code>.</code> (dot) − operator used to link properties in concatenation
* <code>|</code> (pipe)
* <code>#</code> (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 <code><nowiki>[[Maurice Carême]]</nowiki></code> 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: <code><nowiki>[[Work of::Maurice Carême]]</nowiki></code>.

In the page, this text is still displayed as a simple hyperlink to "Maurice Carême". The additional text <code>Work of</code> 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 [[#Properties to be used in the Rich Annotator System|property names to be used 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:
{| class="wikitable" style="text-align:left;"
! What it does !! What you type !! What is to note
|-
| Classify a [[Help/Links|link]] with the property "example property." || <pre>Classify a [[Example property::link]] with the property "example property."</pre> || 
|-
| Make [[Help/Links|alternate text]] appear in place of the link. || <pre>Make [[Example property::link|alternate text]] appear in place of the link.</pre> || 
|-
| To hide the property from appearing at all, use a space as the alternate text. || <pre>To hide the property [[Example property::link| ]] from appearing at all use a space as the alternate text.</pre> || The space after “<code><nowiki>|</nowiki></code>” is necessary. If left away, the pipe trick applies, but rarely with desirable effects. → Consider using [[#Silent annotations|annotations with <code>#set</code>]] instead.
|}


===Silent annotations===
The <code>#set</code> function allows to annotate data, i.e. assign values to a property, silently. If you want to, you can avoid the <code><nowiki>[[Property::value]]</nowiki></code> syntax (in-text annotation) using a <code>#set</code> 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: <code><nowiki>{{#set: Work of=Maurice Carême}}</nowiki></code>.

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: <code><nowiki>[[Work of::Maurice Carême| ]]</nowiki></code>. It is no longer needed doing it like this, you can just use a <code>#set</code> call as shown in the example above.


===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 <code><nowiki>[[Work of::Maurice Carême]]</nowiki></code>, it is assumed that ''Work of'' if 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 <code>#set</code>, instead of using in-text annotation syntax notation.


===Properties to be used in the Rich Annotator System===
Properties already used are listed below. When you create a new [[Help/Links|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.
{| class="wikitable sortable" style="text-align:left;"
! Property !! French synonym !! class="unsortable"|Example !! class="unsortable"|Datatype and use
|-
| Has the volume || A le tome || À la recherche du temps perdu <code><nowiki>[[Has the volume::Du côté de chez Swann]]</nowiki></code> || Page. Used when a work has several volumes.
|-
| Author of || Auteur de<br>Auteure de || Victor Hugo <code><nowiki>[[Author of::Les Travailleurs de la mer]]</nowiki></code> || Page
|-
| Cited by || Cité par || Du côté de chez Swann/Partie 2 <code><nowiki>[[Cited by::Lire et voir (Anikó Ádám)</nowiki></code> || Page. Used when a literary text is cited in a ''[[Help/Readings|reading]]''.
|-
| Coauthor of || Coauteur de || Nicolas Bouvier <code><nowiki>{{#set: Coauteur de=[[L'Usage du monde]] (illustré par [[Thierry Vernet]])}}</nowiki></code> || Text. See [[Help/Authors#Coauthored works|Authors]].
|-
| Linked to || En lien avec || Séphora <code><nowiki>[[Linked to::À la recherche du temps perdu]]</nowiki></code> || Page
|}






[[User help|{{#fas:caret-left}} Back to contents]]
[[Category:Help]]
{{interlanguagelink:en|Help-Semantic-links}}