VisDic Update

VisDic dictionaries can be updated using vupdate program which converts data written in Journal format to the inner format of VisDic. Every type of change can be interactively consulted with the user who will decide whether the change is applied or not.

1. Journal Format

Journal file consists of following entries (each entry is stored at one line):

DATE TIME USER TYPE CHANGE

where

DATE is a date of change in YY/MM/DD format
TIME is a time of change in HH/MM/SS format
USER is a name of user who made the change
TYPE is a type of change, it can be one of these:
- ADD_NEW - new entry is added to the dictionary
- ADD_EXP - new entry is added to the dictionary, the addition is the result of multi-adding operation like copying the whole trees
- UPD_ENT - update existing entry
- UPD_KEY - update the key value of existing entry, if the entry with the key does not exist, the change is automatically ignored
- DEL_ENT - delete entry
- BEGIN - begin of the user session
- END - end of the user session
CHANGE
- is empty for BEGIN and END type
- in the case of ADD_NEW, ADD_EXP, UPD_ENT and DEL_ENT it contains the XML entry to be processed
- for UPD_KEY it contains the sequence OLD_KEY -> NEW_KEY, where OLD_KEY is a key of the entry which has to be changed (this entry must exist in the dictionary), and NEW_KEY is a key which has to replace the old one.

2. `vupdate` Program

vupdate opens the dictionary which has to be updated and a journal file. Then it reads sequently the changes written in the journal file and makes actions based on different types of events. The behaviour of the program can be specified in the configuration file described below.

There are several types of actions the program provides:

Applying the change - the change is applied
Ignoring the change - the change is ignored
Skipping the change - the change is ignored and written to the standard error output
Questioning the user - the program ask a user for his decision

In the last case, an information of the change is displayed.

The first line contains current position in the journal file, slash, total number of changes in the file, date, time, user and change type of the journal entry.
The Orig: line contains an entry actually stored in the dictionary. If it does not exist, the ??? is displayd instead.
The Jour: line conatins an entry stored in the journal. If it does not exist, the ??? is displayd instead.
Next lines can contain possible unresolved links and/or hints. Both will be described below.

Then the user can enter one of the following commands:

y - apply the change
n - ignore the change
s - skip the change
Y - apply all the changes of current type of event
N - ignore all the changes of current type of event
S - skip all the changes of current type of event
p - print Orig: and Jour: entries again
x - print Orig: and Jour: entries in XML format
t - print Orig: and Jour: entries in a text format
additional commands stored in the configuration file for showing Orig: and Jour: entries in a special view
> - save the question to the special note file if it's name is defined
# - show the first line of information again
? - display the help
. - quit the program

2.1 Hints

There is an option for displaying hints which can help the user for his decision. Hint can say either

yes - apply the change
no - ignore the change
probably yes - I'm not sure, but maybe you should apply the change
probably no - I'm not sure, but maybe you should ignore the change
? - I really don't know

Note: Hints slows the process slightly.

2.2 Configuration file

The configuration file of vupdate consists of two main sections:

Events which can occur and the action connected with them. This field has the following format:
JOUR_EVENT + DICT_EVENT = ACTION

where
- JOUR_EVENT describes the following type of change
  - ADD_NEW - new entry is added to the dictionary
  - ADD_EXP - new entry is added to the dictionary, the addition is the result of multi-adding operation like copying the whole trees
  - UPD_ENT - update existing entry
  - UPD_KEY - update the key value of existing entry, if the entry with the key does not exist, the change is automatically ignored
  - DEL_ENT - delete entry
  - BEGIN - begin of the user session
  - END - end of the user session
- DICT_EVENT describes an actual situation in the dictionary, it can take one of the following values:
  - EXIST - entry already exists
  - NEXST - entry does not exist
  - EQUAL - entry exists and its equal to the entry stored in a journal file
  - EULNK - entry exists but the journal entry contains unresolved links (links pointed to the non-existing entries)
  - NULNK - entry does not exist and the journal entry contains unresolved links
- ACTION describes the behaviour of the program when the JOUR_EVENT and DICT_EVENT occurs at the same time, it can be one of
  - APPL - apply the change
  - SKIP - skip the change and send it to the standard error output
  - IGNR - ingore the change
  - QUES - ask the user what to do
Keys for activating the special view of Orig: and Jour: lines. It contains lines with the following structure:
KEY = VISUAL_DEFINITION
where
- KEY is a keyboard key used during the questioning the user
- VISUAL_DEFINITION is a visual definition for displaying entries. The definition is described in the dictionary configuration file (.cfg). The first definition stored in a configuration file become active in a text view of entries. If no definitions are defined here, the VISDIC_SHORT is used as the default one.

Note: Empty lines, lines beginnig with # character and additional spaces are ignored during the configuration file processing.

Here is an example of vupdate configuration file: vupdate.cfg

2.3 Command Line Options

vupdate has the following command line structure:

vupdate DICT JOURNAL [OPTIONS]