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 . 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. 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:  ANSI example line clear and color change and some complex lines:  ³  ô  ³  ô   ô  ³ ÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ  ÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ¿ ³  õô  ³  õô  ³  õô  ³ ³ÚÄÄÄÄÄÄÄÄÄÄÄÄÄ¿Û  ³ ÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ¿ ³ ³  õðô  ³  õðô  ³  õðô  ³ ³³ Rank & File ³Û  ³ ³ Current High Score ³ ³ ³  õô  ³  õô  ³  õô  ³ ³ÀÄÄÄÄÄÄÄÄÄÄÄÄÄÙÛ  ³ ³ ================== ³ ³ ³  õ  ³  õ   õ  ³ ßßßßßßßßßßßßßßßß  ³ ³ ³ ³ ÃÄÄÄÄÄÄÄÄÄÅÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÁÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ¿ ³ ÀÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÙ ³ ³  ô  ³  ô   ô   ô   ô  ³ ³ ³ ³  õô  ³  õô  ³  õô  ³  õô  ³  õô  ³ ³ ÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ¿ ³ ³  õðô  ³  õðô  ³  õðô  ³  õðô  ³  õðô  ³ ³ ³ Your Current Score ³ ³ ³  õô  ³  õô  ³  õô  ³  õô  ³  õô  ³ ³ ³====================³ ³ ³  õ  ³  õ   õ   õ   õ  ³ ³ ³ 100 ³ ³ ÃÄÄÄÄÄÄÄÄÄÅÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´ ³ ÀÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÙ ³ ³  ô  ³  ô   ô   ô   ô  ³ ³ ³ ³  õô  ³  õô  ³  õô  ³  õô  ³  õô  ³ ³ ÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ¿ ³ ³  õðô  ³  õðô  ³  õðô  ³  õðô  ³  õðô  ³ ³ ³Enter your wager as ³ ³ ³  õô  ³  õô  ³  õô  ³  õô  ³  õô  ³ ³ ³a percent... ³ ³ ³  õ  ³  õ   õ   õ   õ  ³ ³ ÀÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÙ ³ ÃÄÄÄÄÄÄÄÄÄÅÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´ ³ ³ ³  ô  ³  ô   ô   ô   ô  ³ ³ ÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ¿ ³ ³  õô  ³  õô  ³  õô  ³  õô  ³  õô  ³ ³ ³Your Wager >   % ³ ³ ³  õðô  ³  õðô  ³  õðô  ³  õðô  ³  õðô  ³ ³ ³Higher or Lower >   ³ ³ ³  õô  ³  õô  ³  õô  ³  õô  ³  õô  ³ ³ ÀÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÙ ³ ³  õ  ³  õ   õ   õ   õ  ³ ÀÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÙ  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 ==