TR - how it works and how to use it
===================================

                                  Overview
                                  ========

TR was written, in large part, because of my own frustration with
answering the same questions over and over again from my callers who,
generally having little experience with a command line environment, just
couldn't understand why programs on the BBS didn't work in similar
fashion to the programs they were using on their own PCs. A lot of those
questions were a result of file display: why can't I page backward in
this file? ... why can't I download the file I'm viewing? ... etc.

I decided to write a TDBS program that would have many of the same kind
of features my callers were accustomed to: lightbar menus, context help,
extended help, status information, as well as some BBS specific
functionality such as integrated download and file forwarding via
e-mail.

The result was TR, which proved to be quite popular with my callers as
well as making my life a bit easier.  TR has run on my system for about
three years now, undergoing occasional enhancement.  A number of people
have requested that I make it commercially available, so I've undertaken
to add a number of new features which I had no need of but which may be
useful to others, as well as adding a greater degree of configurability.

Since I'd like to see it become easier for SysOps of start-up systems to
become successful without having to make a large, up-front investment,
I've decided to make a fully-functional two-line + console version of TR
available free of charge to any SysOp who would like to use it.  This
free version may also be considered a demo for those considering
purchasing the unlimited line count version.  I hope to continue this
policy with any future programs I may write, and I would invite other
TDBS developers to adopt this approach as well.

---

I hope you enjoy TR and find it useful.

---

Packing List and Installation Guide
-----------------------------------

Unzip the files in TR.ZIP into the directory of your choice.

Along with TR.TPG, the main program, you should have received a number
of data files including menu definition files (*.MNU) and user help
files (*.HLP).  You should also have received two additional programs:
TRCFG.TPG, which assists in setting up a custom configuration for TR,
and DEMOTR.TPG (source code in DEMOTR.PRG) which provides a quick way
for you to see TR in action and try out some of it's features.

Licensing
---------

TR licensing is a simple affair:  TR is licensed on a per CPU basis.

The licensed, unlimited line count version may exist in multiple copies
on a single system so long as you are a registered licensee and so long
as all copies are executed by the same CPU.

You may use as many copies of the two-line + console, demonstration
version on as many CPUs as you like, without charge.  Regardless of the
number of copies you are running, you are still programatically limited
to three simultaneous users  :)

You can give copies of the demonstration version away, make them
available as downloads, and hand them out as party favors <g>.  You can
do anything you like with the demonstration version except sell it.


                                   Details
                                   =======
Tracking Files
--------------

TR's ability to move quickly from point to point throughout a file is
achieved through the use of a tracking file which is created the first
time a file is displayed and which contains information about the
number, size, and starting location of each screen full of text to be
displayed.

Tracking files are retained for future use, so that the next time the
text file is to be displayed, TR will not have to re-calculate the
information stored in its associated tracking file.  TR compares a
tracking file's date and time stamp with the associated text file to
make sure that the tracking file is current and that modification of
a text file will cause TR to update the tracking file.

Tracking files have the same name as the file about which they contain
information, but they are given the extension ".TRK".  This imposes an
inherent limitation: you should use TR with sets of files that are
distinguished by their filename and *not* those distinguished by file
extension.  For example, 1001.txt, 1002.txt, and 1003.txt will all
result in unique tracking files (1001.trk 1002.trk, and 1003.trk).

However the file set: news.100, news.200, and news.300 would not be
appropriate for use with tracking files as they would all result in the
tracking file: news.trk and TR would have no way of determining to
which text file this tracking file belonged.  If you must use TR with
files named in this manner, you should use the /k command line parameter
which will force TR to create temporary tracking files only.

Temporary tracking files, which are named with an extension based on the
number of the incoming line in use, are also created for those callers
whose UserLog settings indicate a non-standard number of screen lines.
Such temporary tracking files are erased by TR upon exiting.

In some cases, such as when using TBBS as a node on a network where the
TBBS system has read-only access to the directories where the files to
be displayed are stored, you may wish to use permanent tracking files,
but store them in the TR home path.  This is possible using the /l command
line parameter.  Unfortunately, this means that the number of tracking
files stored in a single directory can become quite large and this may
mean that you will be unable to run TR from a RAM drive.

Custom Configuration
--------------------

If you would rather not use one of the three built-in color schemes, TR
comes with a companion program, TRCFG, which allows you to create a
custom color configuration which you can enable with TR's /c command
line parameter.  This allows you a fair amount of flexibility in making
TR 'fit in' with existing color schemes/screens on your system.

TR does not support multiple configuration files, but it is perfectly
permissible to use multiple copies of TR in different directories to
achieve this effect.  This is not a violation of your license to use TR.

The configuration program is also used to supply TR with the information
it needs to be used with the /e, e-mail option.

E-Mail
------

Under TBBS v2.3 or greater, TR can be configured to permit users to
send themselves displayed files via local e-mail.  You must run TRCFG
and supply certain information prior to enabling e-mail support with
TR's /e command line parameter.  Specifically, you will need to tell
TRCFG the name of the message board you wish TR to use, and you will
need to tell it the maximum message size (between 2048 - 9999) as
defined in CEDIT.  You may specify a smaller message size than that
defined in CEDIT (down to a minimum of 2048 bytes) if you wish.

TR e-mails files smaller than this size as plain text messages.  Files
larger than this are e-mailed as file enclosures.  This brings us to
the last requirement for using the e-mail feature: make sure you have
defined a file enclosure area in CEDIT.  <grin>

Note that when a user e-mails themselves a file, the Mail menu option is
then removed from their menu.  This prevents the inattentive from
mailing themselves the same file a half-a-dozen times.

Titles
------

TR uses the first 40 characters of the first line of a text file as a
title, which it displays on the first line of the screen, regardless of
where the user is when browsing the file.  This title is also used as
the message subject line when a user e-mails themselves a file.

If TR does not find any text on the first line of the file to be displayed,
it uses "Title Unknown" instead.

You can optionally suppress display of a title using the /b command line
parameter.  This can be useful when displaying files which have been
created by programs rather than by hand-editing.

Performance Issues
------------------

Although TR has been written to be make efficient use of CPU and memory
resources, like any program which does a significant amount of file
handling, TR has the potential to use a disproportionate amount of
system resources when used in a heavily loaded environment.

On systems with a high line count or a large number of concurrently
running TBBS option modules and TDBS programs, it is strongly suggested
that you consider placing TR and its associated files in a RAM drive.

If you decide to do this to enhance performance on your system, make
certain that you allocate an adequate number of file entries in your RAM
drive.  In standard operation, TR may use up to twenty files for its own
use and could theoretically create up to 96 temporary tracking files (on
a 96 line TBBS) in its home directory.  DOS's RAMDRIVE.SYS only
allocates 64 entries by default.  You may need to increase this
allocation based on your system's requirements.

ANSI Tricks
-----------

Although TR is primarily intended for displaying plain text files, it
can be used to display files which contain ANSI escape sequences.  To
display properly with TR, such files must contain only ANSI sequences
which affect the current line (line clears and color changes are okay,
screen clears and cursor re-positioning are not).

If the number of characters (including the ANSI sequences) in a line is
greater than 79, or you wish to have TR re-assert its text coloring
after each ANSI line, you will need to use the /t command line parameter
to suppress line trimming and you will need to  make sure than the
number of display characters in the line (characters other than ANSI
escape sequences) does not exceed 79 characters and that all the
characters in the line do not exceed 254.

This sound a little complex, but it is quite simple in practice: if an
ANSI file's lines will display within 79 characters and it doesn't do
any kind of screen clearing or 'animation', you can probably use that
file with TR without problem if you use the /t parameter.

I have frequently used files created with programs such as ANSI
Publisher(tm) and have found these files to work with well with TR.

Here is a quick example of incorporating ANSI into the display file:

[36;44m[K  ANSI example line clear and color change and some complex lines:
[36;40m[K
[40;35m [44;37m      [1;40m [0;35m [44;37m      [1;40m   [0;44m      [1;40m [0;35m[1;45m   [40;37m  [44;34m[0;44;30m
[40;35m [44;37m     [1;40m [0;35m [44;37m     [1;40m [0;35m [44;37m     [1;40m [0;35m[1;45m [0;45;30m[1;35m[0;45;30m [1;40;37m  [44;34m [47;37m[0;47;30m[44m 
[40;35m [44;37m    [1;40m [0;35m [44;37m    [1;40m [0;35m [44;37m    [1;40m [0;35m[1;45m [0;45;30m [1;36mRank & File [35m[0;45;30m [1;40;37m  [44;34m [47;37m [0;47;30mCurrent High Score [44m 
[40;35m [44;37m     [1;40m [0;35m [44;37m     [1;40m [0;35m [44;37m     [1;40m [0;35m[1;45m [0;45;30m[1;35m[0;45;30m [1;40;37m  [44;34m [47;37m [0;47;30m================== [44m 
[40;35m [44;37m      [1;40m [0;35m [44;37m      [1;40m   [0;44m      [1;40m [0;35m[1;45m  [0;45;30m [1;40;37m  [44;34m [47;37m                    [0;47;30m[44m 
[40;35mĿ [1;44;34m [47;37m[0;47;30m[44m 
[40;35m [44;37m      [1;40m [0;35m [1;44;37m [0;44m     [1;40m   [0;44m      [1;40m   [44m [0;44m     [1;40m   [0;44m      [1;40m [0;35m [1;44;34m                        [0;44;30m
[40;35m [44;37m     [1;40m [0;35m [1;44;37m [0;44m    [1;40m [0;35m [44;37m     [1;40m [0;35m [1;44;37m [0;44m    [1;40m [0;35m [44;37m     [1;40m [0;35m [1;44;34m [0;46;30m[1;36m[0;44;30m 
[40;35m [44;37m    [1;40m [0;35m [1;44;37m  [0;44m  [1;40m [0;35m [44;37m    [1;40m [0;35m [1;44;37m  [0;44m  [1;40m [0;35m [44;37m    [1;40m [0;35m [1;44;34m [0;46;30m Your Current Score [1;36m[0;44;30m 
[40;35m [44;37m     [1;40m [0;35m [1;44;37m    [0;44m [1;40m [0;35m [44;37m     [1;40m [0;35m [1;44;37m    [0;44m [1;40m [0;35m [44;37m     [1;40m [0;35m [1;44;34m [0;46;30m====================[1;36m[0;44;30m 
[40;35m [44;37m      [1;40m [0;35m [1;44;37m     [0;44m [1;40m   [0;44m      [1;40m   [44m     [0;44m [1;40m   [0;44m      [1;40m [0;35m [1;44;34m [0;46;30m        100         [1;36m[0;44;30m 
[40;35mĴ [1;44;34m [0;46;30m[1;36m[0;44;30m 
[40;35m [44;37m      [1;40m [0;35m [1;44;37m [0;44m     [1;40m   [0;44m      [1;40m   [0;44m      [1;40m   [0;44m      [1;40m [0;35m [1;44;34m                        [0;44;30m
[40;35m [44;37m     [1;40m [0;35m [1;44;37m [0;44m    [1;40m [0;35m [44;37m     [1;40m [0;35m [44;37m     [1;40m [0;35m [44;37m     [1;40m [0;35m [1;44;34m [0;46;30m[1;36m[0;44;30m 
[40;35m [44;37m    [1;40m [0;35m [1;44;37m  [0;44m  [1;40m [0;35m [44;37m    [1;40m [0;35m [44;37m    [1;40m [0;35m [44;37m    [1;40m [0;35m [1;44;34m [0;46;30mEnter your wager as [1;36m[0;44;30m 
[40;35m [44;37m     [1;40m [0;35m [1;44;37m    [0;44m [1;40m [0;35m [44;37m     [1;40m [0;35m [44;37m     [1;40m [0;35m [44;37m     [1;40m [0;35m [1;44;34m [0;46;30ma percent...        [1;36m[0;44;30m 
[40;35m [44;37m      [1;40m [0;35m [1;44;37m     [0;44m [1;40m   [0;44m      [1;40m   [0;44m      [1;40m   [0;44m      [1;40m [0;35m [1;44;34m [0;46;30m[1;36m[0;44;30m 
[40;35mĴ [1;44;34m                        [0;44;30m
[40;35m [44;37m      [1;40m [0;35m [44;37m      [1;40m   [0;44m      [1;40m   [0;44m      [1;40m   [0;44m      [1;40m [0;35m [1;44;34m [0;47;30m[1;37m[0;44;30m 
[40;35m [44;37m     [1;40m [0;35m [44;37m     [1;40m [0;35m [44;37m     [1;40m [0;35m [44;37m     [1;40m [0;35m [44;37m     [1;40m [0;35m [1;44;34m [0;47;30m[1;37mYour Wager > [44;36m    [47;37m % [0;44;30m 
[40;35m [44;37m    [1;40m [0;35m [44;37m    [1;40m [0;35m [44;37m    [1;40m [0;35m [44;37m    [1;40m [0;35m [44;37m    [1;40m [0;35m [1;44;34m [0;47;30m[1;33mHigher or Lower > [1;44;36m [47;37m [0;44;30m 
[40;35m [44;37m     [1;40m [0;35m [44;37m     [1;40m [0;35m [44;37m     [1;40m [0;35m [44;37m     [1;40m [0;35m [44;37m     [1;40m [0;35m [1;44;34m [0;47;30m[1;37m[0;44;30m 
[40;35m [44;37m      [1;40m [0;35m [44;37m      [1;40m   [0;44m      [1;40m   [0;44m      [1;40m   [0;44m      [1;40m [0;35m [1;44;34m[0;44;30m

[36;40m[K
Back to standard, plain text.

In general use, TR may not be appropriate for complex ANSI files such as
ANSI art files, but it is usually quite suitable for things like
ANSI-colorized listing and report files.

== END OF FILE ==
