Jason Aller Floppy Collection/176.img/SLBBS76M.ZIP/STRINGS.ZIP/STRINGS.DOC

Text File | 1989-06-27 | 12KB | 239 lines

           -----------------------------------------------
                  Searchlight BBS Extended Versions
                 STRINGS.SYS File Format and Editing
           -----------------------------------------------


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

    Searchlight BBS Extended Versions beginning with 1.70 use and
external file called STRINGS.SYS to contain most of the text strings
and messages used by the system.  Besides saving RAM space, this
allows the system's text messages to be edited without the need to
change the EXE program files and allows your customizations to be
ported to future releases of the software.  Possible uses for the
STRINGS.SYS file include the translation of the software into other
languages.

    The following discusses the format and use of the STRINGS.SYS
file and provides two simple programs for unpacking and repacking
the system strings.  Please read this entire file before attempting
to make any changes to your STRINGS.SYS file.


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

    Before you make any changes to your STRINGS.SYS 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 STRINGS.SYS file
to restore your system to normal operation.  Also, you will need
your original STRINGS.SYS file if you wish to port your changes to
future releases of SLBBS.

    Any changes you make to the strings in the STRINGS.SYS file must
be done with regard to the context in which the string appears in
the program.  While the STRINGS.SYS 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 STRINGS.SYS file editing is done AT YOUR OWN RISK.  We
cannot guarantee that Searchlight will operate correctly with any
STRINGS.SYS file other than the original, 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 STRINGS.SYS FILE: XSYS.EXE ............................

    The program XSYS.EXE 'unpacks' the STRINGS.SYS data file into a
plain-text file that can be edited by your word processor or text
editor.  To use it, type 'XSYS.EXE strings.sys <filename>' where the
<filename> is the name of a plain text file to receive the text.
For example:

    C> XSYS STRINGS.SYS STRINGS.TXT

This command will write a text file called STRINGS.TXT that contains
the Searchlight strings as plain text.  By examining STRINGS.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 STRINGS.SYS file.  Messages are
generally grouped in the order that they appear in the program,
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
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 STRINGS.SYS 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 STRINGS.SYS file for Searchlight to use.  To do that, use the
MSYS program provided by typing 'MSYS <filename> STRINGS.SYS', where
<filename> is of course the name of your plain-text file.  For
example, type

    C> MSYS STRINGS.TXT STRINGS.SYS

to regenerate STRINGS.SYS from the STRINGS.TXT file used in the
above example.  Remember to make sure you have a back-up copy of the
original STRINGS.SYS before you begin, as MSYS will overwrite it
with the changed data.  Run SLBBS 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 system 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
STRINGS.SYS file.


UPGRADING TO NEW VERSIONS OF SLBBS ..................................

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

    - Unpack the ORIGINAL, unmodified STRINGS.SYS files from the old
and new versions of SLBBS 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
STRINGS.SYS 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 STRINGS file.

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


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

    - 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).

    - Actual menu commands are not contained in STRINGS.SYS and thus
cannot be edited at this time (command descriptions can be edited,
but try to keep their lengths unchanged).

    - 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.

    - 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.

    - As of this writing (version 1.73), some strings remain
internal to the SYSOP program module.  These will be added to the
STRINGS.SYS file at a later date.  Also as of this writing, some
strings requiring parameters are expressed as two or more strings.
These will likely be converted to a single string in the future.


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

    Please contact me on Searchlight or Wise Byte BBS if you have
any questions about the STRINGS.SYS file.  In particular, I would
like to hear from anyone who would like to attempt a translation of
Searchlight into another language as I will be happy to provide any
additional documentation or help that you need.


STRINGS.SYS FILE FORMAT .............................................

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

    Searchlight's STRINGS.SYS file implements 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 the SLBBS software, strings are
referenced by number only.  The STRINGS.SYS file contains an index
which allows fast, random access to the string data.

    The STRINGS.SYS 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 the STRINGS.SYS file 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.

    The STRINGS.SYS format is not difficult to use and you may wish
to develop your own procedures for processing and maintaining it,
especially if you are attempting a large scale translation.

--------------------------------------------------------------------
                                               Frank LaRosa 6/27/89