Monster Media 1994 #1

home *** CD-ROM | disk | FTP | other *** search

/ Monster Media 1994 #1 / monster.zip / monster / BBS_UTIL / FDL_V410.ZIP / FLLDOCEN.DOC < prev next >

Wrap

Text File | 1994-04-03 | 28KB | 593 lines

╔══════════════════════════════ ┌─────────────────┐ ║ FDL FileDoor-LITE │ D.I.S.P. │────┐ ║ │ │░░░░│ ╟────────────────────────────── │ │░░░░│ ║ (c) 1994 Robert W.van Hoeven │ Dutch │░░░░│ ╟────────────────────────────── │ Independent │░░░░│ ║ Release : 4.10 │ ShareWare │░░░░│ ║ Rel.Date: April 3th, 1994 │ Programmer│░░░░│ ╠══════════════════════════════ └─────────────────┘░░░░│ ║ | │░░░░░░░░░░░░░░░░░│ ║ L A N G U A G E | └─────────────────┘ ║ R E F E R E N C E | ┌─────┐ | ║ ================= | │░░░░░│ | ║ | └──┬──┘ | ║ Changes to version 4.03 are | ┌────┴────┐ | ║ marked with a '│' in front ------││││││ ═══│------- ║ of the line. └─────────┘ ╠═══════════════════════════════ ║ Address: Robert W. van Hoeven ║ PO. Box 131 ║ 1170 AC Badhoevedorp ║ Nederland / Holland ╚═══════════════════════════════ ┌───────┬─────────────────────────────────────────────────────────────┐ │ 0 │ Table of contents │ └───────┴─────────────────────────────────────────────────────────────┘ 1 ---- General information 1.1 General information on Filedoor language support 1.2 Specific language related problems 2 ---- Setting up FileDoor for language support 2.1 Related options in FDL.CFG 2.2 Related files 2.3 New language files 3 ---- Format of the language file 3.1 Creating your own language file 3.2 General format of the language file 3.3 Meta-command reference 3.4 Macro reference 4 ---- Compilation 4.1 FLL.EXE ┌───────┬─────────────────────────────────────────────────────────────┐ │ 1 │ General information on FileDoor language support │ └───────┴─────────────────────────────────────────────────────────────┘ 1.1 General information on FileDoor language support ──────────────────────────────────────────────────── FileDoor is equipped with its own language-driver which is not at all compatible with the language support that you will find in your BBS program or other doors. The reasons for this are: - FileDoor can be used with a large number of BBS programs which all have their own standard; - The language support of most BBS programs is not as flexible as I wanted it to be; For this reason, a new type of language support was developed which is build around simple ASCII text-files and a language compiler. The ASCII file can be modified with any normal text-editor which supports ASCII text-files (something different than word-processor files). Also a DISP-compatible language-file editor is under development, as this format of language support will be included in all BBS-related DISP programs (RFW, MTS and so on). The language support is quit simple. The basics behind the current mechanism is simple. Most language-independent programs will load the needed language-file into the (conventional) memory, thus taking away precious memory that could otherwise be used for other functions. Depending on the package, this can take from 10K to 64+K of memory. The current language-engine for Filedoor, will use around 4K of memory. By means of string-cache mechanisms, FileDoor will be able to maintain the most needed strings in memory. This caching mechanism is still under development. Currently, FileDoor WILL cache the strings but in a sequential order. In normal situations, this will result in the almost optimal result, because the strings are read into the cache in the same sequence as they are displayed in FileDoor. None of the recursive string-sequences (e.g.line 1, line 2, line 3, question, line 1, line 2, line 3, question, and so on) will pass the current cache bounds, meaning that there is almost NO delay in reading the string from disk. As the mechanism enhances, speed will be better. The main benefits of the DISP-compatible language file that is added to FileDoor, are: - The option to include and exclude almost EVERY line; - The option to format lines in the way you want; - The option to exclude unwanted information; - The option to leave out specific questions when there are more than 2 option are normally allowed; - The option to alternate the colors in the way you like (you can even create a flashing light-show if you want); - Rather fast; - No memory constraint; This flexibility is implemented by using free-form coding, macros that will be substituted (they will be enhanced in the future) and special syntax for questions. 1.2 Specific language related problems ──────────────────────────────────────────────────── The current language support will be fine in most cases. Some of the languages will give problems though: - Cyrilic languages (e.g. Russian) Cyrilic languages ARE supported by the PC, by means of a special 'unofficial' code-page and a device driver. FileDoor WILL support cyrilic languages but I am still changing the code (testing is done by the Russian DISP-site (Anthony Guetmansky, St. Petersburg)). At this moment the cyrilic language is still a problem. The correct uppercase/lowercase routines are implemented but don't function well at this moment, so hold on.... - Hebrew and Arabic languages Currently, Hebrew is under development. In this case the problems are different. Most lines need to be reversed and so will the language substitution in FileDoor. Some of the macros (see later) to trigger special language types are already available, but they won't work (correctly). ┌───────┬─────────────────────────────────────────────────────────────┐ │ 2 │ Setting up FileDoor for language support │ └───────┴─────────────────────────────────────────────────────────────┘ 2.1 Related options in FDL.CFG ──────────────────────────────────────────────────── There is one important option in FDL.CFG that can be used when you use different languages (but only in this case). It is the LANGUAGE option (obvious). If you don't use any different languages (but only one language), you don't need this option. See chapter 2.xx for a barebones setup ! The LANGUAGE option needs the name of the language that is used in the BBS. The BBS must be able to pass the NAME of the language in a special file (FDL.XSL). This file is a normal ASCII text-file with ONE line, containing the name (case is not important) of the language that is currently used. For Remote Access <tm> this can be implemented as follows: - Place the FDL.RAT file (from this release archive) in the Remote Access <tm> system directory. This file contains the enhanced code that will be replaced by the name of the language; - Add the following option to the FileDoor calls (type 7): [start of command-line] -0*SFDL.XSL -0 is needed because of a bug in Remote Access. This package will not correctly clear the remaining command-line, after the *S is detected. FIleDoor will take everything behind -0 as granted, so it will not result in 'invalid option' situations. - The following will happen: - RA will start calling FileDoor; - It will detect *SFDL.XSL and will do the following: - Read FDL.RAT - Substitute the enhanced ANSI-code with the name of the language; - Will write this to FDL.XSL - It will detect other options like *M and so on; - It will actually call FileDoor itself; - FileDoor will read the command-line and will try to open the file FDL.XSL; - If not present, it will use FDL.FLL as the default language file and will use the directory from the FILEDOORDIR option as the one that contains the ANS/ASC text-files to be used; - If present, FileDoor will check if there is a LANGUAGE option with the same name as the name that came from FDL.XSL; - If no LANGUAGE option is valid, the same will happen as if the FDL.XSL file was not present; - If present, FileDoor will use the language-file from the LANGUAGE option ([name].FLL if present. If not present, FDL.FLL is used again) AND will use the directory from the LANGUAGE options as the one that contains the ANS/ASC files; - In short, FileDoor will check for a temporary file FDL.XSL and will either use FDL.FLL (mind the difference between XSL and FLL extensions) or [name].FLL. The FLL files are the COMPILED language files that came from FDL.LAN or [name].LAN and should be found in the DOS-path. For SuperBBS <tm> this can be implemented as follows: - It is rather the same as with Remote Access but now you should use FDL.SBE (same as FDL.RAT but now for SuperBBS) and it should use *X and not *S as the macro in the type 7 menu. The rest will work the same. The number of LANGUAGE statements in FDL.CFG is unlimited. Be aware though that many (obsolete) lines in FDL.CFG will result in a longer init-time when FileDoor is called. As you could see, in both setups, FileDoor also can use different ANS/ASC files (when needed and if implemented). The normal directory where FileDoor finds these files is set with the FIELDOORDIR option. With language support, FileDoor will obtain an alternative directory from the LANGUAGE option ! Another option to review is the USERMACRO option. The USERMACRO option also uses the name of the language. If you don't support different languages and/or there is a chance of passing a language-name for which there isn't a LANGUAGE option, you need to use ENGLISH as the name to use on the USERMACRO. So when you use USERMACRO options, you should (at least) include one with the language-name ENGLISH ! 2.2 Related files ──────────────────────────────────────────────────── As you have read in 2.1, FileDoor uses a couple of special files for the language support. These are: - FDL.LAN The default language-file that should be compiled to FDL.FLL. - [name].LAN The specific language-file(s) that can be used, like DEUTSCH.LAN, DUTCH.LAN, STARTREK.LAN and so on. These should be compiled to [name].FLL; - FDL.FLL The default (compiled) language. It should ALWAYS be present. Even if you don't use different languages (but just one), this file must be present. English users can use the supplied FDL.LAN file in the release archive. FileDoor will use this file when there is no language-support or when a language is used for which there isn't a LANGUAGE option ! - [name].FLL The specific (compiled) language files, like DEUTSCH.FLL, DUTCH.FLL or STARTREK.FLL. If there IS a LANGUAGE option with [name] but the file isn't available, FileDoor will use FDL.FLL ! - FDL.XSL This is a temporary file that is created by the BBS program and will contain the name of the language in one line (with EOF mark). FileDoor will delete the file after it has been read; - FDL.SBE The template-file for SuperBBS. Must be in the current directory (e.g. the line-directory); - FDL.SBE The template-file for Remote Access. Must be in the current directory (e.g. the line-directory); FLL-files can be created with the FLL.EXE program. The *.FLL files must be put in a directory on the DOS-path OR the directory that contains FDL.EXE (or whatever you have named it) OR in the current directory (this will be expensive when you use different lines). All files are read in shared mode, so many lines can read from ONE language file. Only the FDL.XSL file will be opened in DENY mode because FileDoor will delete this file after the file is read ! 2.3 New language files ──────────────────────────────────────────────────── When you create or obtain a new language file (*.LAN), you should do the following: - Add the language in the BBS and write down the name of the language; - Rename the *.LAN language file for FIleDoor that contains this language to the name you have written down; - Compile the file with FLL.EXE, correct the errors and place the resulting *.FLL file alongside the other language files; - Add the LANGUAGE option in FDL.CFG; - Add the correct USERMACRO options in FDL.CFG (if needed); For example, you receive GERMAN.RAL (for Remote Access) and the DEUTSCH.LAN file for FileDoor. Now add GERMAN.LAN to the BBS, rename DEUTSCH.LAN to GERMAN.LAN, compile the file, add the LANGUAGE option with GERMAN and the USERMACRO with GERMAN. A special case are languages with double names like 'StarTrek English', Kreuzberg Deutsch, Fries Nederlands or Retro Romanian. You can still use this languages on FileDoor, as long as you add an underscore in the name (LANGUAGE Startrek_English ...... and so on). ┌───────┬─────────────────────────────────────────────────────────────┐ │ 3 │ Format of the language file │ └───────┴─────────────────────────────────────────────────────────────┘ 3.1 Creating your own language file ──────────────────────────────────────────────────── Creating a language file (ANY language file for ANY program) is worse than downloading a 700K package on 300 baud for the sake of only one 3K file inside this package. I can only supply some general rules: - Always start with the FDL.LAN file from the release package; - Start translating; - Keep all lines within the same bounds as in FDL.LAN or you must know what you are doing. Keep in mind that the macros will be substituted with values of a different length in any of the lines. Looking at FileDoor with FDL.LAN as language file, will help in determining the correct translated line; - You can leave out lines (keep them empty by placing only a CRLF macro) and you can add lines (by placing a CRLF PLUS the next line); - You can change questions and even leave out questions; - Test, test and again test the file WITHOUT and WITH users to see if the lines fit and to see if the questions and answers are OK; Some help comes from FLL.EXE. In the near future (when this language format is implemented in other DISP-products) a special language editor will be available. 3.2 General format of the language file ──────────────────────────────────────────────────── The uncompiled language file (*.LAN) is a ASCII flat-file that can be edited with a normal line-oriented text-editor. All lines must have their value starting on column 1 and the maximum line-size is 255 bytes (or less). There are three types of records in the ASCII-version of the language file. These are: - Records starting with % in column 1 These records are treated as comment-records. You can put almost anything behind the record, to comment lines below or above (see the included default FDL.LAN file in the release-archive); - Records starting with a ! in column 1 These records contain a META-command which is interpreted by the language compiler (FLL.EXE). You can call it a kind of compiler directive; - Records starting with a number on column 1 These are the actual language records. For each product, there is a number of used record-numbers. These numbers don't have to be in a specific order and I have left out some numbers to leave room for future updates. In all cases, you should examine the supplied FDL.LAN file to see the used format. One example can tell more than a whole lot of text. For FileDoor, the language-records run from 1 to 400 with holes in number-sequence. In the comments you can see various blocks of numbers which are all related to each other. When you create (or change) a language-file, you MUST leave all the numbers inside the file. If you leave them out, it could result in empty lines on the remote screen where actually some text was needed. Some language-records *CAN* have macros ($1..$9) that will be replaced with a value that comes from FileDoor itself. FileDoor knows which language-records can contain substitution macros and which won't. If, for example, you add a $1 to a line where there is no $1 expected, FileDoor will show nothing at the remote side (there is no macro to substitute for such a line). If a line in the example contains $1 and you remove it, FileDoor will not add the substitution value to the final line. 3.3 Meta-command reference ──────────────────────────────────────────────────── As you have seen in 3.2, the *.LAN file can contain a number of special meta-commands that are used by FLL.EXE. These are: - !NAME [name] The name of the author who created the language-file. This will be displayed when FileDoor terminates. It is bad behavior to replace the name with that of your own, in files that you did not create yourself. In the final release, you can send your language-file to me, and you will receive a special code (when it is original) that can be added to the !PROT meta-command so the file is protected from a change of name, but currently this option is NOT PRESENT. [name] can be your name (spaces are allowed) and can be up to 35 characters. Any underscore symbol '_' is also replaced by a space; -!VERS [version] When you update a language file, you can give it a version-number of your own. This number van be placed in this meta-command. [version] can be up to 7 characters and can NOT contain any spaces. If you want to code one or more spaces, you must replace them by an underscore character; - !CYRL YES|NO If you code !CYRL YES, FileDoor will use the cyrilic uppercase routine. Because this mechanism is not working correctly at this moment (the release version will work OK), you should not use it. Use !CYRL NO in your *.LAN file instead ! - !FONT YES|NO This option can be set to YES if the remote user has to change the font inside his PC. This is the case with cyrilic but can also be the case with Greek, Hebrew and so on. If your language doesn't need any special upcase/locase routines, you can use this option. If the option is set to YES, FileDoor will also display language record number 400. This record must contain something like 'toggle your font-set' or can be left empty when the font is always on. Languages like ENGLISH, GERMAN, FRENCH and so on, need !FONT to be set to NO; - !PROT YES|NO Not implemented yet. Use !PROT NO if you want to code this command; - !HEBR YES|NO Not active yet. Don't include this option yet. It will be used for Hebrew language support (when implemented); Currently these are all meta-commands that are implemented or that will be implemented ! 3.4 Macro reference ──────────────────────────────────────────────────── Any language-record can contain one or more macro-commands that will be replaced by FileDoor. These macros can be split into two categories: - Macros that will SOMETIMES be substituted by FileDoor These are the $1, $2 .. $9 macros. FileDoor will know itself for which lines these macros (and how many) have to be changed. All other lines (or superfluous macros) will not be changed. In that case FileDoor will replace them with nothing (so actually remove them when the line is displayed remote); - Macros that will ALWAYS be substituted by FileDoor These are all other macros (see list below). FileDoor will try to substitute as many of these macros as possible. The only limitation is the maximum length of 255. When the line (after substitution) will be longer than 255, FileDoor will truncate the line at the end. This can be a problem when the substitution is an ANSI-string. In that case, the remote user will see trash on his/her screen. Keep the number color-change of macros low ! - Macros that only have a meaning with questions There is one special macro (or language-record syntax) that is meant for questions (see below for details). The following list is a complete list of all 'normal' macros that will be substituted: ^A Will be replaced by the NORMAL LOW color ^B Will be replaced by the NORMAL HIGH color ^C Will be replaced by the ATTENTION color ^D Will be replaced by the STATUS-BAR color ^E Will be replaced by the ERROR color ^F Will be replaced by the TEXT-1 color ^G Will be replaced by the TEXT-2 color ^H Will be replaced by the TEXT-3 color ^I Will be replaced by the TEXT-4 color ^J Will be replaced by the TEXT-5 color ^K Will be replaced by the TEXT-6 color ^O Will be replaced by the color at the start of FDL.EXE ^Txx Start the following text on column 'xx (for example '^T24Download' will cause 'Download' to be written on column 24. The ^T macros must be in order of column and should not overlap ! ^7 Will be replaced by one bell-sound (CTRL-7) at the REMOTE (not local) side; | Will be replaced by a CR-LF (X13X10) combination (e.g. a new line); _ Will be replaced by a space (only needed at the start or end of a language record). Spaces in the middle can be coded as spaces; │ (CTRL-L) will be replaced by a clear-screen sequence; An example: ^AFile: ^C$! ^ASize: ^C$2|As you can see^T50^E!!!!!^7^7 Will result in: File: xxxxxxxx.xxx Size xxxxxx As you can see !!!!! Because, ^A, ^C and ^E will change colors on the correct locations, FileDoor will substitute $1 with a filename (for THIS record) and $2 with the size (idem). Also '!!!' will start at column 50 of the screen and the bell will be sounded twice ! A special case are the questions inside FileDoor. You need a special kind of coding in the language record to submit a question to the user. It is only possible to submit a question when FileDoor expects a question on a given language-record (otherwise, no question is asked even if you included one). The general format of a question is best explained with an example: ^ADo you need this file <y>es, <N>o, <v>iew or <s>top: ^B_ [[NYNVS]] \/│\--/\/ Start of a question-macro -----------------------------------│ │ │ │ │ │ Default answer when user uses [ENTER] ------------------------ │ │ │ │ The possible answers in the order FILEDOOR expects them --------- │ │ End of a question-macro ------------------------------------------- As you can see, the question is imbedded by the '[[' and ']]' (without quotes) characters. The first letter after '[[' is the default answer that FileDoor will get passed when [ENTER] is used. The remaining letters are the possible answers. The letters must be in the same order as you can see in the default FDL.LAN file but the letters can be of a different value. The same example in dutch: ^AWilt U dit bestand, <j>a, <N>ee, <b>ekijk of <e>ind: ^B_ [[NJNBE]] The order is still the same, but the letters are different. The first (default) letter can be present in the set of letters that follow but this does not have to be the case. If you use a different letter, Filedoor will assume NO default. If you want to remove the <V>iew option from the list of possible answers, you do the following: ^ADo you need this file <y>es, <N>o or <s>top: ^B_ [[NYNΓS]] On the location where you earlier coded the 'V', you now see the 'Γ' character. This is a high character that can not be used by the remote user. You could also use the X'255' character or something different. In this way, you have removed the <v>iew option in a smart way. If you include the same letter more than once, the result is unpredictable. The order in which each question is tested by FileDoor itself will then deside which routine is called and which isn't ! It needs a lot of experiments and looking at the example to be a fast (and good) language-file writer. It is difficult because it is very flexible but the final result is a screen-layout that is almost completely created by yourself. ┌───────┬─────────────────────────────────────────────────────────────┐ │ 4 │ Compilation │ └───────┴─────────────────────────────────────────────────────────────┘ 4.1 FLL.EXE ──────────────────────────────────────────────────── When you receive (or create/change) a *.LAN file, you must compile the file with FLL.EXE to create the *.FLL file that FileDoor uses. FLL.EXE is called with the following syntax: FLL {drive:}{dir}[filename]{.LAN} {drive:}{dir}[filename]{.FLL} or FLL {drive:}{dir}[filename]{.LAN} FLL always delete the target *.FLL file first. When you want to run a simulation, you should point to a temporary directory, so the original *.FLL file is not overwritten. FLL.EXE uses the FDL.CFG to detect the colors you use. This is needed because FLL.EXE will test if the target-line will cause overflow. On screen you will see the final result which can be viewed line-by-line. When you change the COLOR option in FDL.CFG, you DON'T need to recompile the language-files again. Though FLL.EXE will show the final line it will NOT write the colors in the compiled file. These colors will be substituted again by FileDoor (each time, at run-time). FLL can be used with some command-line parameters of which -Q is the most obvious. It will cause FLL.EXE to display each and every single line before processing the next one. This will help you in debugging a new (or changed) language file. Use FLL /? to see a list of command-line options ! [=================== END OF DOCUMENT =================================]