ftp.wwiv.com/ftp.wwiv.com.zip/ftp.wwiv.com/pub/MISC/DEMO510.ZIP/LANGUAGE.INS/LANGUAGE.DOC

Text File | 1999-01-25 | 14KB | 280 lines

           -----------------------------------------------
                          Searchlight BBS
                  Language File Format and Editing
           -----------------------------------------------


INTRODUCTION ........................................................

    Beginning with verison 4.0, Searchlight BBS uses external files to
contain all of the text strings and messages used online.  The default
language file, DEFAULT.LNG, is included with Searchlight; other language
files can be obtained.  This document shows you how to create your own
language files by modifying the default language.

    If you are familiar with earlier versions of Searchlight, the
DEFAULT.LNG file replaces the STRINGS.SYS file.  The physical format of
DEFAULT.LNG is exactly the same as STRINGS.SYS, so you can use existing
utilities that operate on STRINGS.SYS with DEFAULT.LNG.  Searchlight 4.0
adds many new entries to the file, including entries for internal menus
which were previously hard-coded and could not be modified.

    Note that language files contain only the messages normally displayed
to callers.  They do not contain messages that appear on the local console,
such as the messages from the CONFIG program or file transfer status
screens.


A WORD TO THE WISE ..................................................

    Before you make any changes to your DEFAULT.LNG file, be sure you have
a safe back-up copy of the original.  In the event that you make any
mistakes, you will need your original DEFAULT.LNG file to restore your
system to normal operation.  Also, you will need your original DEFAULT.LNG
file if you wish to port your changes to future releases of SLBBS.

    Searchlight contains a facility for managing multiple languages.
Rather than change your default language file, you may wish to copy the
default file, modify the copy, and enter it as a new language choice in
your configuration.  See your manual for more information.

    Any changes you make to the strings in the DEFAULT.LNG file must be
done with regard to the context in which the string appears in Searchlight.
While the DEFAULT.LNG file allows you to change string lengths, many
strings used by Searchlight contain leading or trailing spaces and must be
maintained at a certain fixed string length.  For example, strings which
form headings should not be shortened or lengthened.  Many strings, such as
menu description strings, have a maximum length that allows them to be
displayed in a particular format on the screen.  When changing any string,
examine its context in the program and related strings to make sure that
you do not exceed the maximum allowable width.

    All language file editing is done AT YOUR OWN RISK.  We cannot
guarantee that Searchlight will operate correctly with any *.LNG file other
than the original file provided or alternate language files obtained from
us, nor can we guarantee that your changes will be compatible with future
versions of SLBBS (although we will do our best to see that they are).


UNPACKING THE LANGUAGE FILE: XSYS.EXE ..............................

    The program XSYS.EXE 'unpacks' a language data file into a plain-text
file that can be edited by your word processor or text editor.  To use it,
type 'XSYS.EXE <languagefle> <filename>' where the <languagefile> is the
name of a language file (like DEFAULT.LNG) and <filename> is the name of a
plain text file to receive the text.  For example:

    C> XSYS DEFAULT.LNG DEFAULT.TXT

    This command will write a text file called DEFAULT.TXT that contains
the default Searchlight language strings as plain text.  By examining
DEFAULT.TXT with your word processor, you will discover a series of lines
which look like this:

    10 'Searchlight BBS DOS Shell -- Type EXIT to return to SLBBS'
    11 'Enter Filename:'
    12 'Can't open file $'
    13 '--- Log Open at '
    14 '    Online: $'
    15 'Message from $ on line $'

    The format consists of a line number, followed by a space and a line of
text contained within single quote marks.  The single quotes are not
absolutely neccesary, but they are provided so that lines with trailing
spaces (such as line #13 above) will be clearly shown and will not be
truncated (many word processors truncate trailing spaces).

    Line numbers are not continuous.  This is done deliberately to
facilitate expansion of the language file.  Messages are generally grouped
in the order that they appear in Searchlight, although this is not always
the case.  Finally, replaceable parameters are implemented in some strings
via the '$' character.  Upon printing these strings, Searchlight replaces
the '$' with an actual name, number or other value.  For example, in string
#15, the username and node number of the station sending a message is
substituted into the string before it is printed.

    To change messages, edit your 'plain text' file with any ASCII word
processor.  If using a Wordstar-type editor, be sure to select 'non-
document' mode.  In general, simple word processers or program editors are
best used as these will not introduce any unwanted characters into the
data.

    When making changes, do not change or add line numbers and do not add
or remove '$' characters from strings.  While you can change the position
of '$' characters if you wish, you cannot change the order in which
parameters will appear in strings containing more than one '$'.  As
mentioned above, many strings are formatted to a particular length and it
is best to leave these the same length.  In some cases you may change an
entire group of strings to a different length.  However, you cannot change
the format with which Searchlight displays actual listings and data, so I
suggest that you do not try to change list headings, etc.  The maximum
length of most strings should not normally exceed 80 characters (a few
strings contain color codes and are longer than 80 characters).

    It's worth noting that you can insert any additional, non-numbered
lines into the source text as comments.  The MSYS program reads only
numbered lines, and will ignore anything else.


REPACKING THE LANGUAGE FILE: MSYS.EXE ...............................

    Once you have made the desired changes to the 'plain text' copy of the
strings, you'll will need to convert the source text back into a language
file for Searchlight to use.  To do that, use the MSYS program provided by
typing 'MSYS <filename> <languagefile>', where <filename> is the name of
your plain-text file and <languagefile> is the name of a language file
(like DEFAULT.LNG).  For example, type

    C> MSYS DEFAULT.TXT DEFAULT.LNG

to regenerate DEFAULT.LNG from the DEFAULT.TXT file used in the above
example.  Run Searchlight and check that your string changes have been
installed.

    MSYS.EXE requires the input file to be in numerical order, and will
abort if it finds unordered lines in the input.  If you end up with an out
of order file, you can sort it with the DOS SORT command before repacking
it with MSYS.

    To create more changes in the future, simply edit your plain text file
again and run MSYS as required to regenerate the new language file.


UPGRADING TO NEW VERSIONS OF SEARCHLIGHT ..........................

    Each new version of Searchlight will likely contain a newly revised
DEFAULT.LNG file.  In order to maintain your customizations across
versions, we recommend the following procedure:

    - Unpack the ORIGINAL, unmodified DEFAULT.LNG files from the old and
new versions of Searchlight to separate files.  Use a file compare utility
to pinpoint the differences between the two files.

    - Take any NEW strings that appear in the newer copy of DEFAULT.LNG and
merge them into your modified plain-text strings file.  Examine any CHANGED
strings between the versions and replace the old version of the string with
the new.  Finally, delete any strings which no longer appear in the new
language file.

    - Use MSYS to repack your custom language file.  Never attempt to run
any new version of Searchlight with an old language file until you update
the old file.


NOTES AND TIPS ......................................................

    o You cannot add your own colors to the internal Searchlight strings,
nor can you change the default colors with which strings and parameters are
shown (except of course by changing your color settings in the CONFIG
program).

    o Strings used as choices on Options menus are expressed as
'Choice1/Choice2/Choice3' etc.  These may be editied if desired, but do not
change the number of choices in the string.

    o Some strings, in particular 'Yes/No' option strings and other short,
common messages, are used in many different places in the program.  By
changing these strings, you affect every part of the program in which they
appear.

    o Strings for internal menus (like the menu that appears following a
message or the new user menu) appear in a format that looks like this:

    311 Reply/R/R/Reply to this message

The string is divided into four sections: text of the command, the command
hotkey, the internal command letter, and a description (some commands of
this type lack the description).  If you want to edit a string of this
type, you can change the command, hotkey and description.  Never change the
internal command letter, otherwise the command will not work.  For example,
if we wanted to change 'Reply' to 'Answer' and make 'A' the function
hotkey, we could change this line to read:

    311 Answer/A/R/Answer this message

Notice that the internal command letter (R) remains the same.  Callers will
never see the internal command letter, however.

You can remove commands from a particular internal menu by blanking the
string that controls the command.  For example, if you wanted to eliminate
the Reply command from the choices following a message, you could blank
string number 311.  You cannot add new choices to an internal menu.

Here is another example of a correct modification:

  Original line: 1050 Yes/Y/Y    Translations: 1050 Sure/S/Y
                                               1050 Oui/O/Y

Notice that in each case, the hot key is changed to match the new command
word, but the internal function letter is always "Y".

If you are familiar with pre-Searchlight 4.0 strings files, strings for
menu choices can generally be found at the same location in the language
file as the descriptions of the menu choices in previous versions.  Most
other new additions can be found at index locations 1040 through 1100,
including the following:

o Data for Yes, No, Cancel and Quit choices are at locations 1049 to 1052.
  Modifying these lines affects all the Yes/No/Quit prompts.

o Data for the Continue, Stop, Tag prompt appears in lines 1053-1055.

o Data for the OK box in RIP mode is on line 1056. (In general, RIP mode
  uses the same string numbers as ANSI mode for the same functions, so
  modifying the strings once is good for both modes. However, be sure that
  new commands are short enough to fit within the RIP buttons allocated for
  them).

o The text of the "Press [Enter]" prompt is on lines 1062 & 1063.

o The text for the days of the week (Sun, Mon, Tue, etc.) is located in
  strings 1080 through 1086. These can be edited up to a maximum of 20
  characters each. As with other strings of this type, be aware that
  formatting problems can occur in some displays if long strings are used.


LANGUAGE TRANSLATIONS AND ADDITIONAL HELP ...........................

    Searchlight Software offers predefined language files for a number of
common languages. Contact us for more information, or if you need
assistance in translating the default language file for your needs.


LANGUAGE FILE FORMAT ................................................

    You do not need to know or use the internal file format of language
files to modify them with the XSYS and MSYS utilities.  However, we discuss
the language file format here for those who wish to write their own
procedures.

    Searchlight's language files implement a logical array of up to 2048
variable-length strings.  Each string has a fixed position in the array;
many array positions are unoccupied and thus reserved for future expansion.
Within Searchlight, strings are referenced by number only.  The language
file contains an index which allows fast, random access to the string data.

    The language file format is extremely simple.  At the beginning of the
file there is a 2048-byte record consisting of one byte binary string
lengths for all 2048 possible strings.  The string lengths are followed
immediately by the string texts, in ascending numerical order, without
delimiters.  Unused strings are represented by zeros in the string length
table and NO text appears for these strings within the textual portion of
the file.

    Searchlight uses language files by reading the string length table at
start-up, then computing a larger table containing the lengths and starting
address of each string.  The starting address is computed by consecutively
adding string lengths together.  At this point, any string in the file is
quickly accessed by performing a seek to its starting address, followed by
a read of the requisite number of bytes into a string buffer.  Where
parameters are concerned, subsequent processing replaces '$' characters
with the actual values from an internal stack.

    Language files are not difficult to use and you may wish to develop
your own procedures for processing and maintaining them, especially if you
are attempting a large scale translation.

--------------------------------------------------------------------
                                               Frank LaRosa 6/27/89
                                                    Updated 5/08/94