Logic in wiki

User Tools

Site Tools

Trace:
docs:sbvr-tutorial

Differences

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

Link to this comparison view

docs:sbvr-tutorial [2017/09/19 14:31]
 docs:sbvr-tutorial [2022/03/23 16:59] (current)
Line 1: Line 1:
 +======== SBVRwiki Tutorial ========
 +
 +SBVRwiki uses the Dokuwiki back-end for storage, unlimited version control
 +and user authentication. The tool supports identification and creation of vocabularies,
 +terms and rules in a transparent, user friendly fashion. It also provides
 +visualization and evaluation mechanisms for created rules.
 +
 +The tool provides visualization and evaluation mechanisms for created rules, and besides basic
 +syntax highlighting and checking, it allows for logical analysis. As it is
 +integrated with the Loki knowledge engineering platform, it allows for
 +on-the-fly conversion of the SBVR rule base and vocabularies to Prolog.
 +
 +SBVRwiki plugin can be downloaded from [[downloads:start#sbvrwiki|downloads page]].
 +
 +===== Creating new SBVRwiki project =====
 +
 +SBVRwiki project consists of three business dictrionaries (every in single namespace/URL):
 +  - :terms
 +  - :facts
 +  - :rules
 + 
 +To start defining a model first you need to create new project and project namespaces in wiki.
 +
 +There two ways of doing it:
 +
 +**1)** By entering new name and submmiting in insertbox:
 +
 +{{.:create.png|}}
 +
 +This will create whole project structure.
 +
 +**2)** By entering new URL and creating new pages:
 +
 +    * <nowiki>http://<server-addres>/doku.php?id=<project-name>:terms</nowiki>
 +
 +    * <nowiki>http://<server-addres>/doku.php?id=<project-name>:facts</nowiki>
 +
 +    * <nowiki>http://<server-addres>/doku.php?id=<project-name>:rules</nowiki>
 +
 +===== Creating dictionaries =====
 +
 +To create new dictionary on a specific page you have to enter editing mode and insert SBVR markers,\\ which plugin will recognise as begining and end of a dictionary:
 +<code><sbvr></sbvr></code>
 +
 +You can insert template entry by clicking button named **//Example SBVR terms dictionary entry//**. The tamplates and examples are shown in subsections :terms, :facts and :rules.
 +
 +**NOTE:** every whitespace is interpreted by the SBVRwiki plugin hence specific code structure is necessary
 +
 +**NOTE:** to view changes it is necessary to save the page
 +
 +==== :terms ====
 +
 +  * template:
 +
 +<code>
 +− [category] Example terms cat egory
 +− Example term
 +* Description : Example term’s description
 +* Other attribue : Example term’s other property
 +</code>
 +
 +  * example:
 +
 +<code>
 +<sbvr>
 +
 +- [category] Monsters
 +- Cookie monster
 +  * Description: Blue monster with big eyes 
 +  * Size: Large
 +- Big Bird
 +  * Description: Big Bird is a yellow bird about eight foot, two inches tall who is 6 years old
 +
 +- [category] Places
 +- Sesame Street
 +  * Description: Special inner city street, the inhabitants, both human and puppet, teach preschool subjects with comedy, cartoons, games and songs.
 +
 +</sbvr>
 +</code>
 +
 +{{.:terms_example.png?800|}}
 +
 +==== :facts ====
 +
 +  * template:
 +
 +<code>
 +− [category] Example facts category
 +− Example term is needed
 +</code>
 +
 +  * example:
 +
 +<code>
 +<sbvr>
 +
 +- [category] Monster facts
 +- Cookie monster lives on Sesame Street 
 +- Cookie monster likes Big Bird
 +
 +</sbvr>
 +</code>
 +
 +{{.:facts_example.png?800|}}
 +
 +Facts can be created only based on previously defined terms. To list avaible terms click **//Terms list//** button.
 +Select a term and it will insert itself after a cursor.
 +
 +UML - class diagrams will be automaticaly generated and added to the bottom of a page.
 +
 +==== :rules ====
 +
 +  * template:
 +
 +<code>
 +− [category] Example rules category
 +− It is necessary that at least one example term is needed.
 +</code>
 +
 +  * example:
 +
 +<code>
 +<sbvr>
 +
 +- [category] Monster Rules
 +- It is obligatory that each Cookie monster likes a Big Bird
 +
 +</sbvr>
 +</code>
 +
 +{{.:rules_example.png?800|}}
 +
 +You can add terms and facts from lists avaible by clicking buttons in the menu.
 +
 +**NOTE:** It is important to select proper terms with the facts which were defined together.
 +
 +===== XML & XMI export =====
 +
 +On ''rules'' page you can find ''Export to XML'' and ''Export to XMI'' buttons.
 +They both export current model (the whole model, not only rules page) to ''*.xml'' file compatible with {{http://www.omg.org/spec/SBVR/1.0/PDF|SBVR specification}} and {{http://www.omg.org/spec/SBVR/20130601/SBVR-XML-Schema.xsd|SBVR XML Schema}}.
 +
 +===== Additional information =====
 +
 +//**SBVRwiki Syntax Plugin**// requiers specified project structure divided into terms, facts and rules because this module implements formatting of the syntax which need data from other dictionaries. The module will not be working properly if names of the data pages are other than specified. The order of page creation also is strict.
 +
 +Concepts defined in dictionaries must be unique.
 +
 +Special editor's keywords and its meaning:
 +^Element^Definition^
 +|[category]|Beginning of a new concepts category|
 +|[comment]|Comments visible in endpage, ignored by syntax plugin |
 +|[silent_comment]|Comments visible during page eddting only|
 +
 +===== Administrator Guide =====
 +
 +Dokuwiki offers several classes of plugins allowing for fine-grained processing
 +of the wiki text. SBVRwiki implements two main plugin components:
 +
 +  * //**SBVRwiki Action Plugin**// : responsible for the file export in the XMI (XML) format. It also handles the user interface events and extends the built-in Dokuwiki editor with shortcuts for common SBVR constructs.
 +  * //**SBVRwiki Syntax Plugin**// : used to enter SBVR expressions as wiki text using a special <sbvr> wiki markup. Using it a user can enter legal SBVR expressions and the plugin offers rich syntax highlighting. Moreover, vocabularies can be visualized with the dynamic translation to UML class diagrams that are rendered by the wiki using the PlantUML tool2.
 +
 +All the modules are implemented in PHP.
 +
 +==== Project structure ====
 +
 +  * //**parser.php**// 
 +    * adds markers to the line with editor's special keywords //[category]//, //[comment]//, //[silent_comment]//
 +    * handles //*// markers
 +    * preprocessing
 +    * process of tokens
 +
 +  * //**lexer.php**//
 +    * processes every line from the dictionary
 +    * splits lines into tokens
 +    * searches for terms and its connections
 +
 +  * //**syntax.php**//
 +    * rendering
 +      * preparation of the list of terms
 +      * terms dictionary processing
 +      * preparation of the list of facts
 +      * export button
 +      * visualisation generation
 +
 +  * //**script.js**//
 +    * reacts on events during working with plugin
 +
 +  * //**pl_generator**// and //**xml_generator**//
 +    * export of a data
 +
 +
 +
 +Visualisation part is done using //**PlantUML**// tool http://plantuml.sourceforge.net/.
 +
  

Page Tools

Except where otherwise noted, content on this wiki is licensed under the following license: CC Attribution-Share Alike 4.0 International
CC Attribution-Share Alike 4.0 International Donate Powered by PHP Valid HTML5 Valid CSS Driven by DokuWiki