~TL README Utility - (C) 1995-96 FormGen Inc. ~BT 95 @C@B Introduction The @EFormGen README Utility @Eis a very small and fast README file viewer that supports a number of user configurable text formatting and display options to jazz up your README files. All color values and attributes used by README are controlled from within the readme text file itself, no external configuration file is required. There are two basic sets of options, those that control color attributes and the title that appears on the top line of your screen, and those that affect the display of various lines of text. By default, README loads a formatted text file named README.DAT. If not found, it searches for a README.TXT file. @C@BTitle and Colors The title and color values can only appear on the top line of the README.DAT file. The basic format is a tilde character (~) plus a two character code. These codes are not case sensitive. When README scans the file, it extracts and processes these codes on the top line, but never actually displays the line itself. The following options are available : @E~TL@E Title on the top line of the screen. @E~TN@E Color of the top and bottom lines. @E~TH@E Color of highlighted text on the top line. @E~DV@E Color of the divider line at the top and bottom of the screen. @E~NT@E Normal text color. @E~BT@E Bold text color. @E~ET@E Emphasized text color. @E~FK@E Function key color. All colors are entered as a standard combined attribute value, for example 23 for grey text on a blue background etc. To create, for example, a top line for a program named 'DingBat Solitaire', with a header and footer color of white on red, a title highlight of bright white on red, function key colors of bright yellow on red, and a bold text color of bright red on a blue background, the top line would read : @C@E ~TL DingBat Solitaire ~TN71 ~TH79 ~FK78 ~BT28 In this example, we have separated the various switches and settings with spaces for clarity, although this not required by README. If you want to see what this example looks like, just edit this README.DAT file, copy this sample line to the top line of the file, and then run README. A somewhat tasteless example, but one that gets the points across !! Be aware that if the utility is run on a monochrome system, any color values entered on the top line will be ignored and README will use its own defaults. Also, any colors that are not set on the top line will assume README's default values. @C@BText Processing There are two types of text processing commands, text formatting and color attributes. The various text processing commands should appear at the beginning of a line of text. This is not manditory, but it does help the legibilty of the text file. The color attribute commands can appear at the begining of a line, or used as markers to highlight a word or phrase. The only rule is that only one color attribute can be used on a single line. If you are highlighting a phrase, only one pair of color attributes can appear on a single line. The basic format of these options is an (@) symbol plus a one character code. Once again, these codes are not case sensitive. @E@ L@E Left Justify line. @E@ R@E Right Justify Line. @E@ C@E Center Line. @E@ B@E Paint line or phrase in bold color. @E@ E@E Paint line or phrase in emphasized color. In the above listing, the space between the (@) symbol and the letter key is there only to prevent wild justification of the above lines. If you inadvertently place both an @ E and a @ B code on the same line, then the first attribute will be used for the line, and the others will appear within the displayed text. When formatting text for use with README, a line should not contain more than 78 characters of text, excluding the embedded codes. README automatically removes its own codes and then truncates the balance to 78 characters. When assigning color attributes, a single attribute at the begining of a line tells README to paint the entire line in the appropriate color. A pair of matching color attributes tells README to paint only the text delimited by the markers. @C@BText Output You may wish to enable your customers to print out the README.TXT file supplied with your software. If they printed the supplied file, it would of course include all of the formatting and color codes. The README utility therefore provides a Text Output function assigned to the [Enter] key. When a user presses [Enter], the contents of the text buffer are written out to an ASCII text file called README.OUT, in the same format as displayed on their screen. The only difference is that no attributes are assigned to allow their printer to print bold text etc.. A beep is sounded to confirm the output to the text file. An error message will appear on the bottom line of the screen if there is no room on the disk for the new file, or the media is unwritable (for example if README is run on a CD-ROM). @C@B Odds and Sods The README utility display a page number in the upper right corner of the top line. This is actually a screen page number intended to provide the user with a rough idea of where they are in a potentially long text file. If a file name is not added to the command line when you start README, the utility first searches for a README.DAT file, the default formatted text file. If README.DAT does not exist in the current directory, then README goes looking for an alternate file named README.TXT. If this file is not found, then a message saying 'File Not Found' will appear and you will return to the DOS prompt. The README.DAT file provides a way for you to supply a formatted text file for your application that a user would not likely try to load into an editor or viewer of some sort. If README has any problem opening the README.DAT or README.TXT files, or creating the README.OUT file, then it will immediately quit back to DOS.