home *** CD-ROM | disk | FTP | other *** search
/ POINT Software Programming / PPROG1.ISO / misc / lingua12 / lingua.doc < prev    next >
Text File  |  1993-05-21  |  10KB  |  256 lines
  1. ---- LINGUA -- MULTILANGUAGE SUPPORT FOR YOUR PROGRAMS -- SHAREWARE ----
  2. -- VERSION 1.2 -- (C) 1993 -- SICHEMSOFT -- WAGENINGEN -- NETHERLANDS --
  3.  
  4. The LINGUA package is designed to help C-programmers to develop applications
  5. that must be released in multiple languages. The end user gets a program
  6. plus one or more datafiles containing all text in the program. One
  7. datafile for each different language. A language can be chosen at
  8. run time. This thus avoids different .exe files for different languages.
  9. The programmer needs only to compile one executable and to make a text data
  10. file for every supported language. It's also easy to afterwards create
  11. support for yet another language and send the data file to interested
  12. customers.
  13.  
  14.  
  15. HOW IT WORKS
  16.  
  17. The package consists of a program, LINGUA, and a module, UI_TEXT (UI
  18. stands for User Interface). The module should be compiled and linked with
  19. your application program. This module is the same for any language and
  20. is very small (about 3.5KB when compiled with Borland C++ 3.1 under MSDOS).
  21. For every supported language a text file is prepared by the programmer
  22. according to a specified format. This text file is then encrypted by LINGUA,
  23. so users cannot alter and perhaps corrupt it just by editing it. These
  24. encrypted text files are shipped with the application and one of them is
  25. loaded by the module UI_TEXT at run time so the application speaks the
  26. desired language.
  27.  
  28.  
  29. FILES IN THE PACKAGE
  30.  
  31. LINGUA.DOC        You're reading it
  32. LINGUA.EXE        Utility to encrypt .TXT file to .ETF file
  33. LINGUA.C          Source of the above
  34. UI_TEXT.OBJ       Module to be linked with your application (large model)
  35. UI_TEXT.C         Source of the above
  36. LINGDEMO.EXE      Small demo program, usage e.g.: lingdemo francais
  37. LINGDEMO.C        Source of the above
  38. LINGUA.H          Include file for compilation of lingua.c and ui_text.c
  39. FILES.INC         Include file for ui_text.c, replace if desired (see below)
  40. MAKEFILE          Makefile for the above programs (DOS/BC++)
  41. UNIX.MAK          Makefile for the above programs (UNIX)
  42. NOCR.C            Source for carriage-return/end-of-file remover for UNIX
  43. ENGLISH.TXT       Text files for demo program
  44. FRANCAIS.TXT
  45. DEUTSCH.TXT
  46. NL.TXT
  47. ENGLISH.ETF       Encrypted files for demo program
  48. DEUTSCH.ETF
  49. FRANCAIS.ETF
  50. NL.ETF
  51. UI_TEXT.H         Header file created by LINGUA from .txt files above
  52.  
  53. The file FILES.INC defines all file functions for ui_text.c. FILES.INC uses
  54. the standard C library file functions, like fopen, fseek etc. If you wish
  55. to use other file functions, or C++ streams functions, or whatever, you can
  56. write your own FILES.INC with these functions.
  57.  
  58.  
  59. USAGE
  60.  
  61. First of all, do not use ANY literal strings in your C-source, but
  62. always use identifiers, e.g. not "Press any key" but ANYKEY.
  63. Write your program in any way you like while observing this main rule.
  64.  
  65. At the same time create and maintain a text file with all literal
  66. text for the program in your native language. This file may have any
  67. name but its extension should be .TXT for use by LINGUA. The lines in
  68. this text file should all begin (at the first position!) with an identifier,
  69. corresponding to the identifiers used in the program. Behind the identifier
  70. follows the literal string that should be used in run time. Comment lines
  71. are allowed, they must begin with #. In the literal strings _ signifies
  72. a leading or trailing space, and - denotes an empty string. String arrays,
  73. in which not every item has its own name, are represented by [ after an
  74. identifier's name followed by one or more lines starting with only [.
  75. Multiline strings are represented by / after an identifier's name followed
  76. bye one or more lines starting with only /.
  77.  
  78. By default the text is loaded all at once into memory at the start of the
  79. application (or rather by calling ui_loadtext) and deleted at the end of
  80. the application (ui_unloadtext). If desired, part or all of the text can
  81. be read from the file only when necessary. For this, use the directive
  82. #FILE in the text file (see example below). All text after this directive
  83. will only be loaded when necessary. All text before #FILE remains resident
  84. in memory. You could place all frequently used strings before #FILE and
  85. seldom used or very long strings after #FILE. If #FILE is used the text
  86. file will remain open between ui_loadtext and ui_unloadtext.
  87.  
  88. Example file english.txt:
  89.  
  90. #english.txt
  91. #empty string
  92. ZEROTH     -
  93. #normal strings
  94. FIRST     one
  95. SECOND    two times
  96. #array
  97. THIRD[    three
  98. [         four
  99. [         five
  100. [         -
  101. [         seven
  102. #leading and trailing spaces
  103. EIGHTH    __eight__
  104. #FILE
  105. #normal string again
  106. NINTH     nine
  107. #multi line string
  108. TENTH/    this is
  109. /         a multiline
  110. /         tenth string
  111. #that's it!
  112. ELEVEN    eleven
  113.  
  114. Whenever any identifier in this text file has been added/edited/deleted,
  115. run the utility LINGUA, like:
  116.  
  117. lingua english
  118.  
  119. and recompile (like you would also have to do if you had edited
  120. literal strings in your source code).
  121.  
  122. LINGUA creates two files: english.etf and ui_text.h (ETF stands for
  123. Encrypted Text File). The header file UI_TEXT.H must be included in the
  124. source file that takes care of the loading and unloading of the text
  125. at run time. Since this header is not language dependent, no
  126. recompilation for another language is necessary. It contains only
  127. defines for all identifiers as show below.
  128.  
  129. Example file ui_text.h:
  130.  
  131. /* ui_text.h */
  132.  
  133. int ui_loadtext(char *fname,char *vers);
  134. void ui_unloadtext(void);
  135. char *ui_filetext(unsigned pos);
  136. char **ui_filearray(unsigned pos);
  137. extern char **ui_text;
  138.  
  139. #define ZEROTH                         ui_text[0]
  140. #define FIRST                          ui_text[1]
  141. #define SECOND                         ui_text[2]
  142. #define THIRD                          (ui_text+3)
  143. #define EIGHTH                         ui_text[8]
  144. #define NINTH                          ui_filetext(0)
  145. #define TENTH                          ui_filetext(1)
  146. #define ELEVEN                         ui_filetext(2)
  147.  
  148. When your application is finished, make a copy of the original .TXT
  149. file and change the literal strings in the copy to another language.
  150. Be careful not to change the identifiers at the start of every line though!
  151. When you run LINGUA on this text file a new .ETF file is created
  152. (and also a ui_text.h, but this one is identical to the one in the
  153. original language).
  154.  
  155. In the application program, start with a call to ui_loadtext (in
  156. the UI_TEXT module). End the application program with a call to
  157. ui_unloadtext. Another language may be loaded at that point too.
  158. Lingua also writes a checksum at the start of the .ETF file. ui_loadtext
  159. returns 1 if the file was read and decoded successfully and the
  160. computed checksum is equal to the one in the file and 0 if not.
  161. You can then handle an error condition in your application (but
  162. in what language?).
  163.  
  164. Example file lingdemo.c (link with ui_text.c):
  165.  
  166. #include <stdio.h>
  167. #include <string.h>
  168. #include "ui_text.h"
  169.  
  170. int main(int argc,char *argv[])
  171. {
  172.    char filename[81],version[81];
  173.  
  174.    if (argc>3) return 1;
  175.    if (argc==3) strcpy(version,argv[2]); else version[0]='\0';
  176.    if (argc>=2) strcpy(filename,argv[1]); else strcpy(filename,"english");
  177.  
  178.    if (ui_loadtext(filename,version)) {
  179.       printf("%s",FIRST);
  180.       printf("%s",SECOND);
  181.       printf("%s",THIRD[0]);
  182.       printf("%s",THIRD[1]);
  183.       printf("%s",THIRD[2]);
  184.       printf("%s",THIRD[3]);
  185.       printf("%s",THIRD[4]);
  186.       printf("%s",EIGHTH);
  187.       printf("%s",NINTH);
  188.       printf("%s",TENTH);
  189.       printf("%s",ELEVEN);
  190.       ui_unloadtext();
  191.    } else puts("Fatal error");
  192.    return 0;
  193. }
  194.  
  195. Execute this example program by:
  196.  
  197. lingdemo <name of etf-file without extension>
  198.  
  199. e.g.:
  200.  
  201. lingdemo english
  202.  
  203. If so desired an optional version number (or other string) may be
  204. given as second argument for the LINGUA utility. This same version
  205. number should then be used as the second parameter in the call
  206. to ui_loadtext. This can be useful to let ui_loadtext reject a file
  207. from a previous version of your application program.
  208.  
  209. NOTE: You should be aware of one snag when using the #FILE directive.
  210. Every identifier that is defined after #FILE results in a pointer to the
  211. same filebuffer. This means that when using two consecutive strings the
  212. latter will overwrite the former. This leads to problems with something like:
  213.   printf("%s%s\n",TENTH,ELEVEN);
  214. This will result in printing "eleven" twice. Instead, to be safe, use:
  215.   printf("%s",TENTH); printf("%s",ELEVEN);
  216. NOTE 2: UNIX users should strip all carriage returns and the end-of-file
  217. character from the sources. You may compile and use NOCR.C for this.
  218.  
  219.  
  220. SHAREWARE NOTICE
  221.  
  222. You may copy and distribute this program freely, as long as all parts
  223. of the package are included without modification.  This is a shareware
  224. (NOT public domain) package; if you like it and use it on a regular
  225. basis please register it. Registration can be done at no charge by
  226. sending me a picture postcard from were you live or work. Suggestions
  227. for improvement are welcomed any time. Please do NOT modify the source
  228. code and pass that on. Send modified source code to me and I will
  229. include your modification, if I consider it useful, in a future release.
  230.  
  231. COMMERCIAL USERS -MUST- REGISTER AND -MUST- MENTION THE USE OF LINGUA
  232. IN THEIR DOCUMENTATION: LINGUA 1.2 (C) SICHEMSOFT, WAGENINGEN, NETHERLANDS.
  233. WE ALSO REQUEST A FREE COPY OF EVERY PRODUCT THAT MAKES USE OF LINGUA!!
  234.  
  235. I hope many people, programmers and users alike, will benefit from LINGUA!
  236.  
  237. Anneke Sicherer-Roetman
  238. SichemSoft
  239. Roghorst 160
  240. 6708 KS Wageningen
  241. Netherlands
  242. email: anneke@chem.ruu.nl
  243.        anneke@hutruu54.bitnet
  244.  
  245.  
  246. VERSION HISTORY
  247.  
  248. 1.0 - 920613 - initial release
  249. 1.1 - 930314 - added multi line string support
  250.                added checksum computation and check
  251.                changed ui_loadtext return type from void to int
  252.                fixed minor bug
  253. 1.2 - 930521 - added support for reading text from file at run time (#FILE)
  254.                added support for DOS vs. UNIX (makefiles, \r\n vs.\n)
  255.                added programmers' choice of file functions (FILES.INC)
  256.