User Tools

Site Tools


docs:userman

Loki Manual - User manual

Editing

Defining Semantic data

There are three main methods of semantic annotations used in Semantic MediaWiki that are supported in Loki:

  • categories - a simple form of annotation that allows users to classify pages. To state that article (Wiki page) belongs to the category country it is necesary to write

[[category:country]]

  • relations - there is a possibility to describe relationships between two Wiki pages. For example there is a relation capital_of between cities:warsaw and coutries:poland. To express this it is necesary to edit the page countries:warsaw and add

[[capital of::countries:poland]]

  • attributes - allows to specify relationships of Wiki pages to things that are not Wiki pages. For example, one can state that Wiki page namespace:page was created at April 22 2009 by writing

[[created:=April 22 2009]]

It is possible to assign one value to multiple relations or attributes in one annotation, thus:

Warsaw is the capital city of [[capital of::located in::countries:poland]]
inhabited by [[inhabited by:=population:=1 800 000]] people. 
The other functionality allows users to decide, how an annotation should be displayed on the page. It is done by defining an lternative text for the annotation using the pipe symbol (|). If no alternative text is specified, the annotation value (default text) is isplayed. If the alternative text is a single space, no value is displayed. For example, code:
Warsaw is located in [[located in::countries:poland|Poland]]. It's inhabited 
by about [[population:=1 800 000|1.8 mln]] people. [[page created:=2011-02-14| ]]
will be displayed as:

Warsaw is located in Poland. It's inhabited by about 1.8 mln people.

All attributes are displayed as plain text, relations as links to the related page and categories as links to the selected category's special page.

Special pages

Special pages are pages containing metadata informations, namely pages describing categories, relations and attributes used in the wiki with information about their usages in the wiki. Loki supports these pages, but it doesn't automatically create them - they have to be created manually. Special pages supported in Loki are:

  • categories - page listing all categories used in the wiki.
  • relations - page listing all relations used in the wiki.
  • attributes - page listing all attributes used in the wiki.

Namespaces for these pages are: for categories - special:category, for relations - special:relation and for attributes - special:attribute.

Each property (including categories) can be a subproperty of another property of the same type (eg. a relation cannot be a subproperty of an attribute). This is set on the subproperty's special page:

  • for categories:

Category is a subcategory of [[category:another_category]].

  • for relations:

Relation is a subrelation of [[subrelation of::another_relation]].

  • for attributes:

Attribute is a subattribute of [[subattribute of:=another_attribute]].

  • for compatibility with SMW syntax, relations and attributes can use the construction subproperty of:: to set their superior properties. This construction is translated into a subrelation or a subattribute depending on the current page namespace. Example use:

Property is a [[subproperty of::another_property]]

Prolog in DokuWiki

The simplest way to use Prolog in DokuWiki is to place code between <pl> … </pl> tags. Code will be interpreted and it will appear as a result of given goal. It can be explained by the following example:

<pl goal="woman(X),write(X),nl,fail.">
woman(kate).
woman(alice).
woman(anna).
man(john).
man(tom).
</pl>
Result of given example: kate
alice
anna

It is important to remember that adding write(X) string to the goal shows a result. When more than one result is expected, it is necesary to add nl,fail.

There are three ways to deliver Prolog code:

  • As a code placed between tags <pl> … </pl>
  • As a DokuWiki file with code <pl file=“manespace:file.pl”></pl>
  • As url to external file with Prolog code <pl url=“http://example.page.com/file.pl”></pl>

Searching interfaces

Ask queries

Loki supporst almost full functionality for ask queries known from SMW. Ask queries allow to define pages search conditions and display results. Each query contain list of arguments seperated with vertical line (|). First condition should be the criteria for wanted pages. Form of the search criteria:

[[condition1]] [[condition2]] [[condition3]]
This is conjunction of conditions. To use alternative, it is necessary to insert OR between conditions.
[[condition1]] OR [[condition2]]
Each condition determines the value of property which searched page must contain. Using empty strings for values is allowed.

Conditions can contain alternative values:

{{#ask: [[property::value1||value2]] }}
which is equivalent to:
{{#ask: [[property::value1]] OR [[property::value2]] }}

Value of the condition can be sub-query:

{{#ask: [[property::<q>[[property1::value]] [[category:cat1]]</q>]] }}
Each sub-query can contain unlimited amount of sub-queries.

There is special kind of queries in Loki - property chains. Properity chains can be used to obtain simpler notation. For example :

[[rel1::<q>[[rel2::[[rel3::value]]</q>]]</q>]]
can be replaced by:
{{#ask: [[rel1.rel2.rel3::value]] }}

Other query arguments are connected with displaying results. Optional arguments can consist of two types of data: columns to be displayed and additional options. First group contains names preceded by a question mark. Example:

{{#ask: [[category:city]] 
      | ?located in }}
There is possibility to specify collumn names.
{{#ask: [[category:city]]
      | ?located in=Localisation}}

For categories, a specific category name can be selected to single out pages belonging to the given category. If the page belongs to the selected category, an ”X” sign will be put in the appropriate field. Example:

{{#ask: [[category:city]] 
      | ?category:city=City
      | ?category:village=Village }}
Result of this example:
CityVillage
antananarivoX
bonnX
brusselsX
cracowX
genevaX
gruszkiX
hamburgX
helsinkiX
katowiceX
kielceX
kilmowekX
krosnoX
londonX
madridX
milton_keynesX
moscowX
osakaX
suwalkiX
vukovarX
warsawX
warszawaX

The other kind of optional arguments of Ask queries are additional options. Loki supports most of the options used in Semantic MediaWiki. Those options are displayed in table below:

Name Allowed values Description
format Avaliable options are listed below this table defines the output format of the query results
limit non-negative integer Maximum amount of displayed results
offset positive integer Results which number will be lower then offset will not be displayed
sort names of displayed columns names of columns by which the results should be sorted, separated by commas
orderasc, ascending, desc, descending, reverse, random Sort order, seperated by commas. Default: asc
headers show, hide specifies whether the column headers should be shown. Default: show
mainlabel text text to be used as the main result column header. Default: empty
link all, subject, none specifies which elements of results should be displayed as links. Atributes always are displayed as a text. Default: all
default text text written when no results found
intro text text written before the displayed results
outro text text written after the displayed results
step text concerns only list and csv formats. Defines result separator. Default: , (comma)

Correct values for format parameter:

  • table - default format. An HTML table.
  • broadtable - a page-wide HTML table.
  • ul - unordered list. Additional properties written in parentheses and separated by commas.
  • ol - ordered list. Additional properties written in parentheses and separated by commas.
  • list - a list. Results are separated by a string defined by the ”sep” option (default ”,”). Additional properties written in parentheses and separated by commas.
  • count - a single number depicting the number of results.
  • csv - results exported to a csv (Comma Separated Values) file. Link to the file is displayed on the page. Field separator (”,” by default) can be set in the ”sep” option.
  • debug - instead of query results, debug information is displayed on the page. This includes: the original query, Prolog goal used to find the matching pages, list of properties to be displayed, values of additional options and the number of results returned by the query.

Semantic Web

SPARQL queries

Loki supports a limited version of SPARQL. SELECT, ASK and DESCRIBE queries are supported. Full wiki semantic data is always used as datasource. Datatypes are not supported - every literal is a string. Full documentation of SPARQL language is avaliable for example on W3 website (http://www.w3.org/TR/rdf-sparql-query/). SPARQL queries can be asked inside wiki pages: they are written between Loki prolog tags (<pl>…</pl>), with format=sparql option or can be asked using SPARQL Endpoint under http://youwiki-address/sparql/ address (e.g. SPARQL Endpoint for this wiki: http://loki.ia.agh.edu.pl/wiki/sparql/)

SPARQL queries consist of:

  • PREFIX list (PREFIX ns : <URL>) - Can be empty.
  • Query type - At this moment SELECT, ASK and DESCRIBE is avaliable
  • List of variables (or constants). For SELECT query it will be selection of columns. For DESCRIBE - list of pages that will be described .
  • Search conditions. In this part there is possible to insert OPTIONAL block (not obligatory conditions) or FILTER element (additional conditions)
  • additional options: ORDER BY, LIMIT, OFFSET.

FILTER list supported in Loki:

  • isIRI(), isURI() - checks whether a given variable is a page.
  • isLiteral() - check whether a given variable is a literal. Category names are treated as literals.
  • samePred(x,y) - checks whether two predicates are the same. Uses the “=” opertator in Prolog.
  • =, !=, >=, , >, < - compare two values, all comparisons are done alphabetically.

SELECT queries

The result of a SELECT query is displayed as an HTML table.

Example SELECT query:

<pl format="sparql">
PREFIX wiki:   <>
SELECT ?title ?genre ?author
WHERE 
  { 
     ?book wiki:genre ?genre.
     ?book wiki:title ?title.
     ?book wiki:author ?author.
     FILTER (?genre!=bookstore:genre:handbook) 
  }
ORDER BY INC(?title)
LIMIT 5
</pl>

This query will return table containing title, author and genre of all books which genre is different than handbook. Only 5 results sorted alphabetically :

titlegenreauthor
At the Mountains of Madnesshorrorbookstore:author:h_p_lovecraft
Bag Of Boneshorrorbookstore:author:stephen_king
Desperationhorrorbookstore:author:stephen_king
Insomiahorrorbookstore:author:stephen_king
Ithorrorbookstore:author:stephen_king

ASK queries

ASK queries determine whether a result exists. It returns either “yes” or “no”. ORDER BY, LIMIT and OFFSET do not apply here. Example query:

<pl format="sparql">
PREFIX wiki: <>
ASK {
        ?book wiki:genre ?genre.
        FILTER ( ?genre!=bookstore:genre:horror)
}
</pl>

This query will return the answer to the question: “Are there any books which genre isn't horror?”. Answer : yes

Example query 2:

<pl format="sparql">
PREFIX wiki: <>
ASK {
        ?book wiki:genre ?genre.
        FILTER ( ?genre==bookstore:genre:thriller)
}
</pl>

OR the same query with the use of direct URI

<pl format="sparql">
PREFIX wiki: <>
ASK {
        ?book wiki:genre wiki:bookstore:genre:thriller.
}
</pl>

“Are there any books which genre is thriller?”. Answer : no

DESCRIBE queries

DESCRIBE queries return all semantic informations about pages complying with the query criteria, written in TURTLE (http://www.w3.org/TeamSubmission/turtle/) format. ORDER BY, LIMIT and OFFSET do not apply. Example query:

<pl format="sparql">
PREFIX wiki: <>
DESCRIBE ?aktor 
WHERE {
  ?aktor a "aktor" ;
         wiki:plec "M" .
  ?film a "film" ;
        wiki:rola_glowna ?aktor ;
        wiki:wytwornia <wytwornie:mgm> ;
        wiki:rok_produkcji ?rok .
 FILTER (?rok >= "1950" && ?rok <="1954")
}
</pl>
Query returns actors who plays major role in musicals Metro-Goldwyn-Mayer in years 1959 - 1954.

osoby:donald_o_connor a aktor ;
data_smierci 2003-09-27 ;
data_urodzenia 1925-08-28 ;
imie_nazwisko Donald O'Connor ;
pelne_imie_nazwisko Donald David Dixon Ronald O'Connor ;
plec M .
osoby:gene_kelly a aktor ;
data_smierci 1996-02-02 ;
data_urodzenia 1912-08-23 ;
imie_nazwisko Gene Kelly ;
pelne_imie_nazwisko Eugene Curran Kelly ;
plec M .

Export to RDF

Basic assumption of Loki is ability to storage and process semantic knowledge. For this reason this is very important to allow transfering knowledge from one system to another. For this purpose Semantic Web standards such as RDF, OWL or SPARQL were created. Every Loki page can be exported to a RDF/XML file. It can bo done by opening the page in the exportrdf mode. One can do this by either adding the action do=exportrdf to the page URL or by clicking the Export to RDF button displayed on the bottom of each page.

The generated RDF/XML file consists of three main parts. The first part contains description of the exported page. The second part contains optional related pages data. This data includes descriptions of pages related to the exported page (determined by the wiki_relation predicate). The number of levels of related pages to be exported (default one - only the selected page is exported) is set by the PlWiki rdfexport_maxlevels option in DokuWiki settings. The third part contains descriptions of all ontology elements used in first two parts, along with their superior elements.

Debug functions

Debugging is a very useful function for user. It can help in the analysis of errors and solving problems. Loki supports debugging Prolog code.

STDERR redirection

Loki allows redirection of the standard error stream to display or save messages which are genereted by the SWI-Prolog engine. It is possible by using msgerr parameter in Prolog tags. There are three values avaliable for this parameter:

  • ignore - default option - There are no error messages displayed or saved in the system. All error messages are redirected to /dev/null
  • display - Error messages are displayed on the wiki page

Example use:

<pl goal="invalid_goal" scope="*" msgerr="display"></pl>

Example how it look like on the wiki page :

ERROR: /geist/vhosts/loki_ia_agh_edu_pl/www/lokidev/lib/plugins/tmp/lokidokuwiki.code16d52847503c57b5d2592e2e52a31e8c:415:0: Syntax error: Operator expected 
ERROR: /geist/vhosts/loki_ia_agh_edu_pl/www/lokidev/lib/plugins/tmp/lokidokuwiki.code16d52847503c57b5d2592e2e52a31e8c:418:0: Syntax error: Operator expected 
ERROR: /geist/vhosts/loki_ia_agh_edu_pl/www/lokidev/lib/plugins/tmp/lokidokuwiki.code16d52847503c57b5d2592e2e52a31e8c:420:0: Syntax error: Operator expected 
ERROR: /geist/vhosts/loki_ia_agh_edu_pl/www/lokidev/lib/plugins/tmp/lokidokuwiki.code16d52847503c57b5d2592e2e52a31e8c:426:0: Syntax error: Operator expected 
ERROR: /geist/vhosts/loki_ia_agh_edu_pl/www/lokidev/lib/plugins/tmp/lokidokuwiki.code16d52847503c57b5d2592e2e52a31e8c:428:0: Syntax error: Operator expected 
ERROR: /geist/vhosts/loki_ia_agh_edu_pl/www/lokidev/lib/plugins/tmp/lokidokuwiki.code16d52847503c57b5d2592e2e52a31e8c:431:0: Syntax error: Operator expected 
ERROR: /geist/vhosts/loki_ia_agh_edu_pl/www/lokidev/lib/plugins/tmp/lokidokuwiki.code16d52847503c57b5d2592e2e52a31e8c:500:59: Syntax error: String too long (see style_check/1) 
ERROR: Prolog initialisation failed: ERROR: ignore/1: Undefined procedure: invalid_goal/0 

Tracing predicates

PlWiki uses the non-interactive version of Prolog trace predicate to display debug information on the wiki page. It can be done by using the Prolog tag ”trace” attribute, with a comma separated list of predicate names as its value. Example use:

<pl scope="*" goal="woman(X), write(X), nl, fail" trace="woman,man"></pl>
Result of this example on the wikipage:
T Call: (6) woman(_G624)
T Exit: (6) woman(kate)
kate
T Redo: (6) woman(_G624)
T Exit: (6) woman(alice)
alice
T Redo: (6) woman(_G624)
T Exit: (6) woman(anna)
anna



docs/userman.txt · Last modified: 2017/12/04 17:12 by kkutt