Wednesday 16 July 2008

Improvements to Regulus documentation

I have been doing some work on and off over the last few weeks to try and improve the Regulus documentation. It's one of those "important non-urgent" tasks that is very hard to schedule, because you always feel you have something that should take higher priority, but I do finally seem to have made some concrete progress.

There are three parts to the work, which are meant to be closely interlinked. First, I have created a directory under Regulus/doc called CommandDoc, which is supposed to contain one short file for each command and type of config file entry. I've so far populated it with the information in RegulusDoc.html, which certainly confirmed that RegulusDoc is badly out of date... I'm afraid half the files are currently empty.

Second, I have added a new top-level Regulus command called DOC. If you type DOC followed by the name of a command, you get the CommandDoc file printed out in a reasonably readable way. For example:

>> DOC LOAD_DIALOGUE
(Print documentation for command)

LOAD_DIALOGUE
[Brief doc: Load dialogue-related files]
Compile the files defined by the dialogue_files config file entry.

>> DOC EBL_NUANCE
(Print documentation for command)

EBL_NUANCE
[Brief doc: Compile current specialised Regulus grammar into Nuance GSL form]
Compile current specialised Regulus grammar into Nuance GSL form. Same
as the NUANCE command, but for the specialised grammar. The input is
the file created by the EBL_POSTPROCESS command; the output Nuance GSL
grammar is placed in the file defined by the ebl_nuance_grammar config
file entry.

>> DOC TRANSLATE_CORPUS
(Print documentation for command)

TRANSLATE_CORPUS
[Brief doc: Process text translation corpus]

Process the default text mode translation corpus, defined by the
translation_corpus config file entry. The output file, defined by
the translation_corpus_results config file entry, contains
question marks for translations that have not yet been judged. If
these are replaced by valid judgements, currently 'good', 'ok' or
'bad', the new judgements can be incorporated into the translation
judgements file (defined by the translation_corpus_judgements
config file entry) using the command
UPDATE_TRANSLATION_JUDGEMENTS.

TRANSLATE_CORPUS <Arg>
[Brief doc: Process text translation corpus with specified ID]

Parameterised version of TRANSLATE_CORPUS. Process the text mode
translation corpus with ID <Arg>, defined by the
parameterised config file entry
translation_corpus(<Arg>). The output file, defined
by the parameterised config file entry
translation_corpus_results(<Arg>), contains
question marks for translations that have not yet been judged. If
these are replaced by valid judgements, currently 'good', 'ok' or
'bad', the new judgements can be incorporated into the translation
judgements file (defined by the translation_corpus_judgements
config file entry) using the parameterised command
UPDATE_TRANSLATION_JUDGEMENTS <Arg>.


Third, and last, I have also arrange things so that the doc files are automatically included in the new Cookbook. This is still just a skeleton, but my plan is to start by completing the command and config-file section, so that the book will immediately be useful for something, and then work outwards from there. The PDF version is checked in as Regulus/doc/Cookbook/draft_cookbook.pdf.

No comments: