= DEBVisDic Manual =

[[PageOutline]]

= Installation of Debvisdic =

== How to obtain DEBVisDic login+password ==

 * go to http://nlp.fi.muni.cz/declaration/
 * fill in the form, print it, sign it and send it to the NLP Centre
 * you will obtain the login and password (for free) by e-mail

== How to install DEBVisDic ==

 * you may see http://nlp.fi.muni.cz/projects/deb2/install.html
 * [http://www.mozilla.com/firefox Mozilla Firefox] has to be installed first in the usual way (you download it using Google first)
 * When Firefox is installed go to the following address: http://nlp.fi.muni.cz/projects/deb2/clients/
 * Click on ''DEBVisDic''
 * ''Note:'' Before the first installation, you need to add our site nlp.fi.muni.cz to the list of sites allowed for installing. The dialog for adding the site to the list appears the first time you click on any installation package (at our site). Then you must Allow the site and next time you click on the package, you can begin the real installation.
[[Image(manual-allow1.png, 350, top)]]
[[Image(manual-allow2.png, 350, top)]]
 * a window will open with several packages - click on ''Install'' 
[[Image(manual-install1.png)]]
 * close all windows in Firefox (with {{{File -> Quit}}})
 * start Firefox again and DEBVisDic should appear as a new menu entry in Firefox {{{Tools}}} 

== First start ==

 * Click on {{{Tools -> DEBVisDic}}}
 * Log-in with your username and password
 * DEBVisDic will automatically install packages for all the !WordNets you have access to
 * Close DEBVisDic and all Firefox windows (with {{{File -> Quit}}})
 * Run DEBVisDic again (for example, click on {{{Tools -> DEBVisDic}}} in Firefox)
 * Log-in with your username and password
 * You will see long and narrow main DEBVisDic window
[[Image(manual-mainwin.png)]]

== Choose !WordNets == 

 * In DEBVisDic click on {{{Settings -> Preferences}}}
 * Upper part of the window contains list of !WordNets available to you. Select the packages in the left list (Ctrl+click, Shift+click to select multiple packages) and click the ''Add'' button. You can ''Add'' one !WordNet several times, you'll get more windows for the same dictionary.
 * Click OK and the selected !WordNets will open
 * Now you can start working
[[Image(manual-prefs.png)]]


== How to uninstall/remove DEBVisDic ==

 * run Firefox (without the {{{-chrome}}} option)
 * in {{{Tools -> Extensions}}} (or {{{Add-ons}}}) select all DEBVisDic
   packages ({{{debvisdic}}}, {{{jslib}}}, and {{{wn...}}} for each
   wordnet) and Uninstall them

= Short overview =

== Interface description (main components) ==

Each !WordNet client is opened in a window of its own, you can arrange those windows as you like on your desktop,
or you can select one of the options in the ''Windows'' menu of DEBVisDic main window to arrange windows automatically.

[[Image(manual-wn1.png)]]

Each window has the following components:
'''1: Search query'''

Enter the search query into this box (previously used queries are automatically offered).
The ''Search'' button will run the query only in the actual !WordNet window,
while the ''Search in all'' will run the same query in all open windows.
Query possibilities are listed in section [#Searchqueries Search, queries]

'''2: Result list'''

List of synsets found as a result of the query. Each line represents one synsets - PoS and list of literals.
Click on a synset to display detailed information in the bottom part of the window.


'''3: Synset information'''

This part of window contains several ''tabs'', by clicking on them you will get detailed information about the selected synset.

== Synset information, tabs ==
 * ''Preview'' - text preview of a given synset. When you click on a synset link (for example hypernym), linked synset is selected and its information is displayed.
 * ''Tree'' - hypernym/hyponym tree related to the given synset. By default, the selected synset is displayed plus all the hypernyms up to the topmost one. By clicking on the  [+] button in front of a synset name in the tree, the synset hyponyms are displayed. You can also click on [-] button to hide tree levels below. When you click on [+] again, all the hyponyms of synset are displayed.
 * ''Rev(ersed) Tree'' - basically, the same tree as above, just reversed upside-down. This time, hyponyms are up and hypernyms down. This reversed tree is needed since the hypero/hyponymy relations form a general graph structure, not just a simple tree.
 * ''Edit'' - a form for synset editing and adding new synsets, see section [#Editingfunctions Editing functions]
 * ''XML'' - the synset data displayed in XML format

== Search, queries ==
You can use several types of queries, from the basic ones to the advanced.

 * ''word'' - search for entries containing whole word in literals, for example ''dog'' will give you all the synsets with dog in literals (even multiword literals, like Eskimo dog)
 * ''word:'' - search for exact literal, for example ''dog:'' will find all synsets with literal dog (exactly this one word)
 * ''word:number'' - search for entries containg the exact literal (all PoS), for example ''dog:3''
 * ''xml_element=value'' - search for value of xml_element, for example ''SYNSET.POS=n'' will find all nouns
 * ''xml_element=dictionary_code2:entry_id2:xml_element2'' - search for xml_element with value from xml_element2 of entry_id2 in dictionary_code2, for example  ''SYNSET.SUMO=sumo:BodyPart:CONCEPT.ID'' will lookup the entry with ''!BodyPart'' in ''sumo'' dictionary and take the value of element ''CONCEPT.ID'' and then search for all synsets with given value in element ''SYNSET.SUMO''. This is used mostly in automatic DEBVisDic AutoLookup queries.

== Inter-!WordNet functions ==

Usually, !WordNets are connected using !InterLanguage Identifiers. If you right-click in the lower part of !WordNet window, you'll see the dictionary
context menu (see picture).

[[Image(manual-context1.png)]]

Now, let's have a look at the first five menu entries. ''Show in'' allows you to display entry with the same ID in another !WordNet, 
for example see the entry linked to english synset in Czech !WordNet. When you select this entry, you'll see the list of dictionaries connected to the actual one. When you click on a dictionary name, linked entry is displayed in selected dictionary.

''Show in (by)'' is similar, but uses different elements to link between entries. For example, you can display SUMO entry for the SUMO information stored in synset.

''!AutoLookUp in'' works similar to ''Show in''. When you click on dictionary name, the tick appears (or disappears) in front of the name. When you select another synset in actual dictionary, all the ticked dictionaries are automatically updated to show the entry with the same ID.
For example: in English !WordNet you tick !AutoLookUp in Czech and Polish !Wordnets. Whenever you select synset in English WN (by clicking in result list, on a link in preview or on a synset in tree), czech and polish synset is automatically displayed.

''!AutoLookUp in (by)'' is a combination of ''Show in (by)'' and ''!AutoLookUp in''.

''!AutoLookUp by search'' - whenever you search in actual dictionary, the same query is automatically run in all the ticked dictionaries.


== Editing functions ==

=== Writing a new synset ===

To create a new synset, choose the ''Edit'' tab and click the ''New'' button. You'll see red border around the form - this means that you are editing new entry, not existing one.
In the form, you see several boxes with label and + button, for example ''Synonyms'' or ''Relations''. When you click on the + button, the box will open and you'll see the form fields. The + button changed to - button, which you can use to hide the box if you feel the form is too complex.

For a new synset, you have to select at least ''Part of Speech'' and on ''synonym'' - click on ''Add'' button to add more synonyms. Don't forget to fill the literal and sense number for each synonym.
You can also fill in other information, like ''Definition'', ''Usage'' or ''Relations''.

When you are done, click on ''Save'' button.

[[Image(manual-editnew.png)]]

=== Changing the existing synset ===

[[Image(manual-edit.png)]]

=== Relations editing ===

[[Image(manual-editrel.png)]]

Click the ''Add'' button in ''Relations'' box to add new relation form fields. Write the query (see [#Searchqueries queries]) to the first box, press ''Enter'' and select the synset from the list (this is important).  Select relation type in second box. When adding hyponym/hypernym relations, add only the hypernym of the synset, hyponyms are generated automatically.

If you press the ''Go to'' button, linked synset is displayed. Note: when pressing this button, you'll lose all unsaved changes.

=== Inter-!WordNet functions - linking to other !WordNets ===

Let's have look at the rest of the [#Inter-WordNetfunctions-linkingtootherWordNets Inter-WordNet functions].

''Copy entry to'' copies the selected synset completely to selected dictionary. If the entry with same ILI already exists in target dictionary, you are asked if you want to overwrite the entry.

''Take ID from'' changes the ILI of selected synset to the value of synset ILI in selected dictionary. You can use this function to link several dictionaries to the basic one. For example, create a new Czech synset,  find the appropriate English equivalent and in Czech WN select ''Take ID from English Wordnet''. Synsets are connected with the same ILI and you can display them using  [#Inter-WordNetfunctions-linkingtootherWordNets Show and Autolookup functions].

===  Locking synsets ===

When you start editing synset, it's locked for you so nobody can make changes. Locks are indicated in synset result list - ''[x]'' in front of synset means that someone else has this synset locked, ''[*]'' means that you have this synset locked. Also, when you change to the ''Edit'' tab, you'll see the lock icon for synsets locked by some other user.

= Typical errors =
 * Do not try to write a new synset on the first top line (box). To enter a new synset you have to open the ''Edit'' tab.
 * When entering a relation between two synsets or linking two synsets via ILI, always check whether they both exist.
 * Do not forget to click on the ''New'' button when entering a new synset and the ''Save'' button when you want to store it. If you do not click the ''Save'' button, nothing will be stored.
 * Avoid entering one synset twice or more times.


= Linguistic recommendations =
 * Use a synonymical dictionary if it exists for a given language.
 * A good explanatory dictionary of a given language should be used for establishing hyperonym relations on the first level, e.g ''chair'' is a ''piece of furniture''.
 * To find reliable translation equivalents use parallel corpora.


= How to write a synset? =
 * You decide what literals a synset will consist of and what part of speech it belongs to: noun (n), verb (v), adjective (a) or adverb (b)
 * When you open the ''Edit'' tab, click on ''New'', then type down a respective literal (one or more), assign it a symbol of PoS and click ''Save''.
 * If you do not click ''Save'', all what you wrote will be lost.


= Numbering senses =
 * A new synset (in fact, any synset) has to be always numbered, i.e. you have to provide a sense number for it. 
 * Sense number distinguishes the different senses of synset, e.g.  ''bank:1'' - financial institution, ''bank:2'' as in "river bank". 
 * It is usual as you can observe in Princeton !WordNet (v. 2.0 and higher) to assign lower numbers (1, 2, 3) to the basic senses.
 * It can be seen that senses in PWN 2.0 are quite often too fine grained - see e.g. verb ''to get'' with 36 senses. We recommend to translate only the senses that can be confirmed in a corpus.

= Eq_Relations, IL relations, ILI =

= Glossary of basic terms =
 * synset 
 * literal 
 * sense
 * IL relations: synonymy, antonymy, hyperonymy/hyponymy, holo/meronymy, deriv
 * EQ_relations
 * Interlingual Index
 * Set of Base Concepts
 * Top Ontology
 * ...