Updating_the_Customization_System

Updating the Customization System

The Matrix customization system is a web application that presents a user-linguist with a linguistic-typological questionnaire, and in response to the answers, creates a LKB-compatible grammar for the language described. When a developer wishes to make changes to the customization system, several different parts of the system must all be updated at the same time in order to keep everything working.

The system is a CGI application written in Python that is stored in the Matrix svn repository (in matrix/customize). It's most important files are:

• The [http://wiki.delph-in.net/moin/matrixdef_File_Syntax matrixdef] file, which defines both the questionnaire and the list of choices -- that is, the name space of attributes and their ranges of values that are used to store the user's answers to the questionnaire.

• matrix.cgi, a CGI script written in Python. The entry point for the customization system.

• deffile.py, which defines the MatrixDefFile class. This class is responsible for creating web pages based on the contents of matrixdef.

• choices.py, which defines the ChoicesFile class. This class is responsible for loading, saving, and providing access to the choices file, which contains the user's answers to the questionnaire.

• validate.py, which contains code to confirm that the user's current choices are describe a coherent language. (For example, if the user says the language contains no determiners, they must not have defined one.)

• customize.py, which contains the code that creates an LKB-compatible grammar based on the current choices.

• tdl.py, which defines the TDLFile class.

Generally speaking, the procedure that must be followed when adding to the customization is as follows, assuming the developer is adding to the typological range of the system:

1. The linguistic phenomenon to be covered must be identified, along with its range of possible patterns in the world's languages, and based on this range a set of new choices (names and values) must be defined.

2. Form fields for the new choices must be added to the matrixdef file.

   1. If necessary, support for new form field types or behavior (e.g. a drop-down box) must be added to deffile.py.

3. If any old choices have become obsolete, the version number in choices.py must be incremented. Furthermore, a new up-revving method that converts choices files of version n-1 to the current version n must be added. See the comments in choices.py for details.

4. New code must be added to validate.py to enforce any constraints on the new choices that must be satisfied before a grammar is created.

5. Finally, new code must be added to customize.py to create the grammar rules and lexical entries associated with the new phenomenon, based on the new choices.

Check-in procedure

1. svn update

2. resolve conflicts

3. run the unit tests: [MatrixCustomizationUnitTesting]

4. fix any regressions (repeat as necessary)

5. svn diff each file to find diffs and note in text file for svn comment

6. svn update

7. svn commit