DISPLAY Version 1.5

(c) Copyright William C. Parke and Douglas Clark 1987

Command DISPLAY
----------------

Purpose: To quickly display the contents of an ASCII text file, page by
page or a single page, with the ability to show intense,
reverse video, underline, color, and blinking characters using
simple text codes which can be entered from within a standard
text editor.

DISPLAY is particularly useful in batch files because of its
screen display speed and the ability to display words with
special attributes set.

Format: DISPLAY [d:][path]filename [/switch]

Requirements: MS-DOS 2.0 or higher; IBM PC or Compatible

Remarks:

Operation: If no file name is given, DISPLAY shows a help
screen. If no page is given, DISPLAY loads the given file into
memory and shows its first page (24 lines). Use the PgDn key
to show the next page, PgUp the previous page, Home to show the
first page, and End to return to the last shown page. Use the
ESC key or CRTL-C to exit DISPLAY. Note, however, that DISPLAY
will automatically exit if the file has no more than one page
of text.

If /p=string switch is given, then DISPLAY will load the
given file into memory and search for the given page string
which is enclosed in a double carot prefix and suffix. For
example, if /p=MENU is on the command line, then the string

^^MENU^^

will be searched for. If it is not found, an error message is
generated. If it is found, then the 24 lines of text following
the string '^^MENU^^' will be shown, unless there is another
page string within the 24 lines, in which case only the text up
to the next page string will be shown. Afterwords, DISPLAY will
exit automatically, putting the cursor at the end of that text.

If /i (ignore) switch is given, then DISPLAY will ignore the
special attribute setting codes given below. For files longer
than one page, typing the 'i' keyboard character will toggle
between the 'ignore special attributes' display and a display
with attributes shown.

DISPLAY in Batch Files:

A principle use of DISPLAY is the fast generation of several
lines of text and extended IBM character graphics (including
boxes) from within batch files (command text files with the
extension BAT).

The 'standard' way for showing text from a batch file is to use
the ECHO command. As users of BAT files know, several such
ECHO lines are generated at noticeably slow speeds compared to
screen updates they may be accustomed to. Moreover, it is
often desirable to enhance menu choices in BAT files with
color, intense text, and graphic boarders.

DISPLAY lets the user generate a screen for his BAT file using
his favorite text editor. By including special text codes,
enhanced displays can be designed. Several such screens can be
put into one text file, with each screen labeled by a page
identifying string. By including

DISPLAY file /p=string


as a line in the BAT file, a very rapid display of the custom
screen identified by the string will be shown when the BAT file
is run.

Using Special Text Enhancements:

By including a backslash character followed by a one or two
letter mnemonic code, one can turn on special text enhancements
and attributes, such as intense, color, reverse video, etc.
The attributes will remain in effect until changed or turned
off by a second such code.

The table below gives the code necessary to control text
attributes from within a text file:

Monochrome: Start Stop Color: Character Screen
--------------------------------------------------
hide \H \h none \cn \sn
underline \U \u blue \cb \sb
reverse video \R \r green \cg \sg
blinking \B \b turquoise \ct \st
intense \I \i red \cr \sr
violet \cv \sv
alternate ibm- yellow \cy \sy
character set \A \a white \cw \sw

Some combinations of attributes are meaningful. For example,
\I\cr\sb will set intense red text characters on a blue
background screen.

If you wish to display the backslash character itself using
DISPLAY, include two backslash characters next to each other:
\\.

Example Commands:

1. DISPLAY \WORDS\MENU.DOC

Displays the file MENU.DOC in the WORDS subdirectory. If
MENU.DOC has 24 or fewer lines, DISPLAY will exit after
displaying the file.

2. DISPLAY MENUS /p=first-menu

Searches for the string, ^^first-menu^^ in the file MENUS. If
found, 24 lines after this string are displayed, unless a new
page marker is found, in which case the display terminates just
before the second marker. In either case, DISPLAY exits after
showing the page of text.

3. DISPLAY DOCUMENT.TXT /i

DISPLAY shows the file DOCUMENT.TXT on the screen without
interpreting any of the special attribute codes which start
with a backslash.

Setting Special DISPLAY Character Attributes in a Text File:

The word \I'intense'\i in this sentence would be shown as
'intense' in bold characters if displayed using DISPLAY. The
phrase \R'reverse video'\r would be shown as 'reverse video'
with a light to dark reversal. The string, "\\Inormal\i"
would not be shown with an intense attribute, since the first
backslash character is repeated. Instead, it would be seen as
"\Inormal". The string, \AMMMMMMMMMMMMMMMM\a would show as a
horizontal double line from the IBM alternate character set.
The alternate set numbered from decimal 128 to 255 can be found
in most BASIC manuals for the IBM PC. DISPLAY generates the
alternate character by adding 128 to the standard ASCII
character. Thus to find the appropriate text character to use
after starting the alternate set, subtract 128 from the
alternate character decimal value to get the decimal value for
the standard character. For example, the double line graphics
characters for constructing a box can be found below:


Alternate Graphic Standard ASCII
Character Value Value and Character

right top 201 - 128 = 73 I
left top 187 - 128 = 59 ;
hor. bar 205 - 128 = 77 M
vert. bar 186 - 128 = 58 :
right bottom 200 - 128 = 72 H
left bottom 188 - 128 = 60 <

If your editor lets you use the ALT-Keypad-Number-key
combination to generate the alternate character set, you do not
need to use the \A code.

If you plan to format your text, it would be wise to do so
before inserting the attribute codes.

Example Text File:

The file SAMPLE.TXT can be used to test the capabilities of
DISPLAY. It contains the page string, '^^show^^' and special
attribute codes. Try both:

DISPLAY SAMPLE.TXT /p=show

and
DISPLAY SAMPLE.TXT

to see the difference between single page and multiple page
displays.

Summary of Operational Keys for Multipage Displays:

PgDn Display Page one screen Down
PgUp Display Page one screen Up
Home Return to first page
End Jump to last page displayed
i Toggle the Ignore attribute switch
ESC Exit Display
^C Exit Display


Notes:
Even though DISPLAY will let you examine any standard text file
with an extremely rapid video generation (even faster than
Vernon Buerg's LIST utility), its principle purpose is the
quick display of special text from within batch files. In this
spirit, we have not expanded the file buffer beyond 48K bytes.
The authors still recommend LIST for general viewing of large
documents.

The control character used to indicate a special attribute is
taken to be the backslash character. You may change this
character by patching at hex 104. For example, to use a tilde
instead of a backslash, the procedure would be:

DEBUG DISPLAY.COM
E104 '~'
W

Similarly, the page marker can be changed by patching hex
103.

Version History:

1.0 Fast display of single pages in BAT files. 10-10-87
1.1 Added attribute codes for color, intensity, etc.
Expanded to allow paging through larger files. 10-20-87
1.2 Added ignore switch. 10-30-87
1.3 Changed /cp and /sp to /cy and /sy (pink to yellow). 11-7-87
1.5 Added /cn and /sn to allow black color. 5-29-88

Distribution:

DISPLAY is supplied for personal, private use only. The
authors can be reached through CHUG, the Capitol Heath/Zenith
Users' Group, Arlington, Virginia.