User Tools

Site Tools


docs:plwiki2

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

docs:plwiki2 [2017/09/19 16:31] (current)
Line 1: Line 1:
 +====== PlWiki 2.0 functionality ======
 +
 +Functionalities added in the extended version of PlWiki can be divided into four parts: ​
 +  - Support for Semantic MediaWiki syntax and functionality
 +  - Debugging functions
 +  - Exporting pages to RDF
 +  - Support for SPARQL queries
 +
 +Each of these functionalities are described in details below.
 +
 +
 +===== Support for SMW functionality =====
 +
 +==== Special pages ====
 +
 +Special pages are pages containing metadata informations,​ namely pages describing categories, relations and attributes used in the wiki. PlWiki supports these pages, but it doesn'​t automatically create them - they have to be created manually. Special pages supported in PlWiki are: 
 +  * [[special:​categories]] - page listing all categories used in the wiki.
 +  * [[special:​relations]] - page listing all relations used in the wiki.
 +  * [[special:​attributes]] - page listing all attributes used in the wiki.
 +
 +Apart from those, PlWiki also supports special pages describing properties, eg. ''​special:​category:​cats''​. These pages contain informations about specific properties and their usages 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:
 +<code smw>
 +Category is a subcategory of [[category:​another_category]].
 +</​code>​
 +  * for relations:
 +<code smw>
 +Relation is a subrelation of [[subrelation of::​another_relation]].
 +</​code>​
 +  * for attributes:
 +<code smw>
 +Attribute is a subattribute of [[subattribute of:​=another_attribute]].
 +</​code>​
 +  * 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:
 +<code smw>
 +Property is a [[subproperty of::​another_property]]
 +</​code>​
 +
 +
 +==== Defining semantic data ====
 +
 +The second version of PlWiki contains improved processing of semantic annotations on wiki pages.
 +Firstly, it is now possible to assign one value to multiple relations or attributes in one annotation, thus:
 +<code smw>
 +Warsaw is the capital city of [[capital of::located in::​countries:​poland]]
 + ​inhabited by [[inhabited by:​=population:​=1 800 000]] people. ​
 +</​code>​
 +
 +The other new functionality allows users to decide, how an annotation should be displayed on the page. It is done by defining an alternative text for the annotation using the pipe symbol (''​|''​). ​
 +If no alternative text is specified, the annotation value (default text) is displayed. If the alternative text is a single space, no value is displayed. For example, code:
 +<code smw>
 +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| ]]
 +</​code>​
 +will be displayed as:
 +<​code>​
 +Warsaw is located in Poland. It's inhabited by about 1.8 mln people.
 +</​code>​
 +
 +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.
 +
 +==== Ask queries ====
 +
 +In the earlier versions of PlWiki a very limited support for Ask queries was available. Now the PlWiki supports almost full functionality of SMW Ask queries.
 +
 +Each query consists of two main parts: conditions for selecting pages and display options. ​
 +
 +The '​selecting pages' functionality has been drastically improved in the new version of PlWiki. Most of SMW functionalities are supported. Among them are:
 +
 +  * Wildcards
 +A wildcard constitutes any value of a property. For example, query:
 +<code smw>
 +{{#ask: [[located in::+]] }}
 +</​code>​
 +will return all pages which have any value of the relation ''​located in''​ specified.
 +  * comparators
 +Comparators are supported in relations and attributes. ​
 +There are three comparators defined in PlWiki: "''>''",​ meaning "more or equal","''<''",​ meaning "less or equal" and "''​!''",​ meaning "not equal"​.
 +Comparators are used directly before the annotation value:
 +<code smw>
 +{{#ask: [[population:​=>​2000000]] [[located in::​!countries:​china]]}}
 +</​code>​
 +NOTE: all comparisons in PlWiki are done alphabetically,​ eg. "​25"<"​9"​. One way of reducing this effect is to assume a consistant value format in the wiki ("​0025">"​0009"​). ​
 +  * disjunction of search conditions
 +Disjunction in a query can be used on two levels: as a disjuntion of conditions (keyword ''​OR''​) or as alternative values of a condition(''​||''​). Example use:
 +<code smw>
 +{{#ask:: [[category:​city||village]] OR [[population:​=<​1 000 000]] }}
 +</​code>​
 +  * subqueries
 +Subqueries are used to find the values of a search conditions. It is most useful if the value is not known or if a set of values is needed. Subqueries'​ conditions are defined between ''<​q>''​ tags. Subqueries have basically the same construction as queries, except only searching pages is supported (without additional display options - for example, one cannot define a subquery which returns top five most populated cities). There are no limitations as to the maximum number of levels of subqueries or the maximum number of subqueries on a given level. Example of a subquery use:
 +<code smw>
 +{{#ask: [[located in::<​q>​[[category:​country]] [[located in::​Asia]]</​q>​]] }}
 +</​code>​
 +  * property chains
 +Property chains are a kind of simple subqueries. They are defined using "''​.''"​ and they allow the user to get the value of a value (of a value and so on) of a property. As with subqueries, the length of a property chain has no upper bounds. This only works with relations:
 +<code smw>
 +{{#ask: [[capital of.located in.located in::​southern hemisphere]] }}
 +</​code>​
 +  * support for property hierarchy
 +Setting a property value in a condition will also cause all the pages which has it's subproperty set to the same value to be displayed. For example, a query searching for all four-limbed animals will return all four-legged cats as well as all four-armed apes - assuming, that the attributes ''​number of legs''​ and ''​number of arms''​ are both a subattribute of ''​number of limbs'',​ and also that ''​cats''​ and ''​apes''​ are subcategories of ''​animals''​. The search can go through any number of levels of the property hierarchy, for example if cats are mammals and mammals are animals, then a query searching for animals will also include cats as well as mammals.
 +
 +
 +The second part of a query are the display options. Options are defined in the second, third and following arguments of the query (first argument being the conditions for selecting pages). Query arguments are separated by the pipe sign (''​|''​). ​
 +Optional arguments can consist of two types of data: columns to be displayed and additional options. ​
 +
 +Users can specify which columns (which properties'​ values) should be displayed as a result of a query. It is done by writing a question mark before the property name, eg.:
 +<code smw>
 +{{#ask: [[category:​city]] ​
 +      | ?located in }}
 +</​code>​
 +Column names can also be specified:
 +<code smw>
 +{{#ask: [[category:​city]]
 +      | ?located in=Localisation }}
 +</​code>​
 +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 use:
 +<code smw>
 +{{#ask: [[located in:​countries:​poland]]
 +      | ?​category:​city=City
 +      | ?​category:​village=Village }}
 +</​code>​
 +
 +The other kind of optional arguments of Ask queries are additional options. PlWiki supports most of the options used in Semantic MediaWiki. Those options are:
 +  * ''​intro''​ - text to be written before the results. In ''​intro'',​ ''​outro''​ and ''​default'',​ underscore signs will be replaced with spaces.
 +  * ''​outro''​ - text to be written after the results. ​
 +  * ''​default''​ - if the query returns no results, this text will be written instead.
 +  * ''​mainlabel''​ - text to be used as the main result column header. Null by default.
 +  * ''​sort''​ - names of columns by which the results should be sorted, separated by commas. Only the displayed columns names can be used.
 +  * ''​order''​ - order by which the results should be sorted. If more than one, the values should be separated by commas. Correct values are: "''​asc''"​ (default), "''​ascending''",​ "''​desc''",​ "''​descending''",​ "''​reverse''"​ and "''​random''"​.
 +  * ''​link''​ - specifies which values should be displayed as links. Available oprions are: 
 +    * ''​all''​ - default option. Every value displayed ​ as a link, apart from attribute values which are always displayed as plain text.
 +    * ''​subject''​ - only the subject (values displayed in the first column, main result of the query) will be displayed as links, with all additional properties displayed as plain text.
 +    * ''​none''​ - every value displayed as plain text.
 +  * ''​headers''​ - specifies whether the column headers should be shown. Available options are "''​show''"​ (default) and "''​hide''"​.
 +  * ''​format''​ - defines the output format of the query results. Correct values are:
 +    * ''​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.  ​
 +
 +All these options and functionalities can be mixed. Here is an example of an ASK query in PlWiki:
 +<code smw>
 +{{#ask: [[category:​city||town]] ​
 +        [[located in.member of::​organisations:​european union]] ​
 +        [[localisation of::<​q>​ [[category:​university]] [[enrollment:​=>​0 001 000]] </​q>​]]
 +      | ?​population=Population ​
 +      | intro=Top five most populated university towns in the EU:
 +      | sort=population
 +      | order=descending
 +      | limit=5
 +      | format=ol ​
 +}}
 +</​code>​
 +
 +
 +===== Debug functions =====
 +
 +==== STDERR redirection ====
 +
 +Redirection of the standard error stream in PlWiki allows to display or save error messages generated by the SWI-Prolog engine. This is set in the "''​msgerr''"​ attribute of the PlWiki Prolog tags. This attribute can have one of three values:
 +  * ''​ignore''​ - default option, all error messages are redirected to /dev/null.
 +  * ''​display''​ - error messages displayed on the wiki page.
 +  * ''​tofile''​ - error messages are written to file. The file is saved in the ''​$DOKU_HOME/​lib/​plugins/​tmp''​ directory.
 +Example use:
 +<code plwiki>
 +<pl goal="​invalid_goal"​ scope="​*"​ msgerr="​display"></​pl>​
 +</​code>​
 +
 +
 +==== 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:
 +<code plwiki>
 +<pl scope="​*"​ goal="​mother(X,​Y),​ write(X), write('​ - '), write(Y), nl, fail"
 +    trace="​mother,​woman,​parent"></​pl>​
 +</​code>​
 +
 +
 +===== RDF export =====
 +
 +Every PlWiki page can be exported to an RDF/XML file. This is 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 pagesto 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.
 +
 +
 +===== SPARQL queries =====
 +
 +PlWiki 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. Only normal wiki pages can be queried, special pages and ontology data (including ontology hierarchy) aren't included in the query.
 +
 +SPARQL queries are written between PlWiki prolog tags, with the tag's "''​format''"​ attribute is set to "''​sparql''"​.
 +
 +==== SELECT queries ====
 +
 +SELECT queries consost of the following elements:
 +  * PREFIX declarations - a prefix can be ser to an empty URI.
 +  * selection of columns to be displayed in the result table
 +  * optional WHERE statement. it can include the OPTIONAL block and the FILTER element.
 +  * additional options: ORDER BY, LIMIT, OFFSET.
 +The result of a SELECT query is displayed as an HTML table. ​
 +
 +The following functions and operators can be used in the FILTER element:
 +  * ''​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. ​
 +
 +Example query:
 +<​code>​
 +<pl format="​sparql">​
 +PREFIX wiki: <>
 +SELECT ?city ?population ?area ?location
 +WHERE {
 +  ?city a "​city";​
 +        wiki:​population ?population ;
 +        wiki:area ?area ;
 +        wiki:​twinned_with <​cities:​warsaw>​ .
 +  OPTIONAL { 
 +       ?city wiki:​located_in ?location.
 +       ?​location a "​country"​
 +  } .
 +  FILTER ( ?area <= "001 000 km^2" && isLiteral(?​population))
 +}
 +ORDER BY DESC(?​population)
 +LIMIT 10
 +</pl>
 +</​code>​
 +
 +This query will return the names, population, area and location countries of 10 most populated cities twinned with Warsaw, which area is at most 1 000 km^2. 
 +
 +
 +==== 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:
 +
 +<code plwiki>
 +<pl format="​sparql">​
 +PREFIX wiki: <>
 +ASK {
 +  ?city a "​city";​
 +        wiki:​population ?population ;
 +        wiki:​twinned_with <​cities:​warsaw>​ .
 +  FILTER ( ?population > "001 000 000 km^2" )
 +}
 +</pl>
 +</​code>​
 +
 +This query will return the answer to the question: "Are there any cities twinned with Warsaw and populated by over one million citizens?"​. ​
 +
 +==== DESCRIBE queries ====
 +
 +DESCRIBE queries return all semantic informations about pages complying with the query criteria, written in TURTLE format. ORDER BY, LIMIT and OFFSET do not apply. Example query:
 +
 +<​code>​
 +<pl format="​sparql">​
 +PREFIX wiki: <>
 +DESCRIBE ?city 
 +WHERE {
 +  ?city a "​city";​
 +        wiki:​twinned_with <​cities:​warsaw>​ .
 +}
 +</pl>
 +</​code>​
  
docs/plwiki2.txt ยท Last modified: 2017/09/19 16:31 (external edit)