Generating 'Help' files for Intkey5 8 December 2000 M. J. Dallwitz and T. A. Paine CSIRO Division of Entomology, GPO Box 1700, Canberra ACT 2601, Australia Phone +61 2 6246 4075 Fax +61 2 6246 4000 Email delta@ento.csiro.au WWW http://biodiversity.uno.edu/delta/ The Intkey5 help file, intken.hin, is generated from text files, which we will refer to as 'source' files, by means of the program inthlp.exe. Inthlp.exe and other program and documentation files are supplied in a compressed, self-expanding file inthelp@.exe. The source files for different languages are supplied in compressed, self-expanding files inth??@.exe, where '??' is the ISO-639 language code, e.g. inthen@.exe for English, inthde@.exe for German. The file iso639.txt lists the codes. The program files should be stored in a separate subdirectory. We will assume in this documentation that the directory is \inthlp, but it could be any directory, for example, \delta\inthlp. The source files are stored in subdirectories of inthlp, named by the language code, for example, \inthlp\en for English, \inthlp\de for German. The language code zu (Zulu) will be used in the examples below. Download the compressed files into the directory \inthlp. You will need inthelp@.exe, inthen@.exe (English source files), and possibly one other set of source files as an example. Unpack them from the MS-DOS command line, as follows: open an MS-DOS window, enter 'cd \inthlp', and enter the name of the compressed file, for example, 'inthelp@' (the '.exe' can be omitted). To start a new translation into Zulu, first create a new subdirectory, \inthlp\zu. Copy the English files into this subdirectory, and carry out the translation by editing these files, rather than by creating new ones. The file names and the internal structure of the files must be preserved. We recommend that most of the commands and options that can be used on the command line should be left in English, because (1) most of the commands are not seen by the user in Normal operating mode; and (2) if they are translated, it will be necessary to also translate the initialization file, intkey.ini, of any data set that you wish to use. The exceptions are the NewDataSet and Quit commands, which appear in the Files menu in Normal mode, but are seldom used in input files. The commands and options referred to in the previous paragraph are in the files commands.txt and vocab.txt. The ones that should not be translated are marked with the comment ''. For the same reasons, it is best not to translate the pre-defined keywords in the file keywords.txt. However, it is OK to append a translation, e.g. 'all (tous)'. The files should be edited with an editor that wraps long lines on the screen, but does not automatically insert hard line breaks when saving the files. TextPad and MS-Word are suitable. Many of the files contain RTF (Rich Text Format) formatting marks. The meanings of the marks used in the source files are described in the file rtf.txt. (A full description of RTF is available at http://support.microsoft.com/support/kb/articles/q86/9/99.asp.) The RTF marks should generally not be changed. Note that although the files contain RTF marks, they are _not_ true RTF files, which require a special header. The files must be edited as text files, and the RTF marks will be visible as such. The eventual effects of the marks, for example, starting a new paragraph or placing text in italics, will not be visible. Eventually, we hope to change inthlp.exe so that the source files can be true RTF files, which will make editing them considerably easier. The RTF marks that affect layout are interpreted in Intkey, but the marks affecting fonts (e.g. 'bold') are currently ignored. The files genhlp.txt and cmdhlp.txt may be combined into a MS-Word document, intkey.doc. You may find it easier to check the translation of these files in intkey.doc, rather than in the Intkey help system. Intkey.doc is generated by an MS-Word macro 'doc', which is in the MS-Word template file inthlp.dot. This requires Word 97 or later. To create intkey.doc, first open inthlp.dot in Word. Then select 'Tools > Macro > Macros...'. This displays the Macros dialog. Select 'doc', and press the Edit button. This opens the macro in the Microsoft Visual Basic editor. Near the top of the file is a line ChangeFileOpenDirectory "d:\dl\inthlp\en" Change the path within the quotes to the appropriate directory on your own computer: "c:\inthlp\zu". Save the file and close the Visual Basic editor. This returns you to the Word window. Again select 'Tools > Macro > Macros...', and select the macro 'doc'. Now press the 'Run' button, and intkey.doc will be created. Intkey.doc contains a few preliminary pages that are inserted from the file hdrint.rtf. You might want to translate this file too. If so, use one of the non-English versions as a model (they contain information about the translation). You can edit this file in Word; close it before running the macro. There is also a Word template file buthlp.dot, which converts the button help (the contents of buthlp.txt) to a Word file buttons.doc, in a way similar to that described above for inthlp.dot. This is intended only to help with proofreading the button help, not for publication (the same information is included in the general help, genhlp.txt). The help file, intkzu.hin, is generated from the source files by running the file hlpgen.bat in an MS-DOS window. If you have been editing the source files in Word, close them. Open an MS-DOS window, and move to the directory containing the source files: 'cd \inthlp\zu'. Before using hlpgen.bat for the first time, edit it as described in the comments at the top of the file. (The essential change is to substitute 'zu' for 'en'.) Then run hlpgen.bat by entering 'hlpgen'. This creates a file inthzu.hin in the DELTA directory. We suggest that you run hlpgen after translating only a few sentences, in order to check that the results, when viewed in Intkey, are as you expect. Create a shortcut to a test version of Intkey5 with -h=intkzu.hin on the 'shortcut target line', as described in the English online help in Advanced Mode (Help > Introduction > Data-Sets Index and Startup Parameters). The source files will change from time to time as the program is altered. Changes in the English version will be marked '++date', for example '++11-MAR-97'. The DELTA development group will keep the foreign-language versions workable until the translations are updated, by adding any essential changes, such as new commands or messages, in English. However, non-essential changes, such as changes in genhlp.txt, will not be marked in these versions. You do not need to put (or retain) revision markers in the translated versions. To help tranlators find the changes, Inthlp produces a log file, help.log, containing sections that have been marked with ++. If a date is supplied as a parameter on the Inthlp command line, for example, inthlp 08-JAN-97 the log file will contain only those changes made after (not including) the specified date. The hlpgen.bat files contain this parameter. You should change the date in the English version of hlpgen.bat to the date of the English version from which you last worked, and run it to find subsequent changes. The 'Compare Documents' feature of MS-Word may be helpful in comparing different versions of a file in a given language. For comparing an English file with the corresponding file in another language, a program such as Araxis Merge (http://www.araxis.com/) is better. You should put your name and contact information at #143 in mess.txt.