READ.TXT                             1                         Mar 10, 2001

WinXX NOTICE:  As with  most  DOS-based  utilities,  this  program  doesn't
understand the weird subdirectories,  long  filenames,  invalid  characters
that are possible under Windows.  This is not a bug.  It's just the way DOS
applications work.  For compatibility reasons,  most  versions  of  Windows
maintain a short filename for each file (in WinNT,  you  can  probably  say
"DIR /X" in DOS to find them).  The short filenames are the ones  with  "~"
characters in them (like "MYFILE~1.TXT").  The  short  filenames  are  what
these utilities will process.

READ allows you to view any ASCII text document with 16,000 lines  or  less
(about 900,000 bytes).  You can also search for  text  within  a  document,
scroll around in the document, and split up big files into small files  for
printing or copying to another file.


Features of the READ program:
  * Handles files up to 16,000 lines only.
  * Supports a mouse scroll bar  at  the  top  if  a  compatible  mouse  is
    detected.
  * Handles DOS text files (lines end with CR/LF), Mac  text  files  (lines
    end with CR), or Unix text files (lines end with LF).
  * Allows text to be blocked and copied or printed.
  * Supports 43/50-line mode under EGA and VGA.
  * Allows jumping to DOS as well as allowing you to turn off this  feature
    (useful for public-use terminals).
  * Supports printer-initializing strings for wide and normal-width text.
  * Allows the user to adjust terminal colors.
  * Allows  text  searching  within  the  file,  either  case-sensitive  or
    case-insensitive.
  * Shows a ruler line if desired.
  * Shows the file before it has finished loading so you can start  reading
    sooner.
  * Can Ctrl-PgUp/Ctrl-PgDn among up to 100 files.
  * Expands tabs on display.
  * The file date format shown is based on your country setting.
  * Pressing escape stops the program early.


Specifying parameters:

Parameters for this program can be set in the  following  ways.   The  last
setting encountered always wins:
  - Read from an *.INI file (see BRUCEINI.TXT file),
  - Through the use of an environmental variable (SET READ=whatever), or
  - From the command line (see "Syntax" below)



READ.TXT                             2                         Mar 10, 2001

The READ.INI file:

The READ.INI file  (see  BRUCEINI.TXT)  is  very  useful  because  READ.EXE
doesn't have a default for setting compressed mode on your printer when you
print things.  If you have a Hewlett-Packard  printer,  it  is  recommended
that you create a READ.INI file that's stored in the same directory as  the
READ.EXE file.  The READ.INI should have at least the following lines:

        /INITT=\027E
        /INITW=\027E\027(s16.66H
        /AFTERF=\012\027E
        /AFTERP=\012\027E

The READ.INI file can be created with any text editor.  You  can  also  use
the free READINIT.EXE program if you have it.


Syntax:

    READ [ filespec | @listfile | /PROMPT ] [ /TITLE="title" ]
      [ /DATE=NONE ]
      [ /line ] [ /COLOR=nnn nnn nnn nnn ] [ /MONO ] [ /EGA | /VGA ]
      [ /-MOUSE ] [ /DOS | /-DOS ] [ /PORT=port ] [ /INITT=string ]
      [ /INITW=string ] [ /AFTERP=string ] [ /AFTERF=string ]
      [ /Iinitfile | /-I ] [ /Q ] [ /-ENV ] [ /? ] [ /?HEX ]

where:

"filespec" is the file specification you want to view.  You can use a  path
specification and a single wildcard  if  you'd  like.   Unless  /PROMPT  is
specified, it defaults to three  wildcard  selections;  *.DOC,  *.TXT,  and
*.BAT.  If more than one document in the directory  matches  the  wildcard,
you can  switch  back  and  forth  between  documents  with  Ctrl-PgUp  and
Ctrl-PgDn.  The program allows you to view up to 100 files in a single pass
(it will skip the 101st *.TXT file).

"@listfile" is a text file that contains the names of any  files  you  want
READ to process.  The text file should contain one filename, with  path  if
desired, per line.  You can include an optional title after any of the file
name references (see /TITLE="title" option).

"/PROMPT" tells the program to ignore the default for  the  input  filespec
and always prompt the user for an input filespec unless one is specifically
provided.  This is primarily used when you're invoking the program  from  a
menuing program like Windows.  Defaults to "/-PROMPT".

"/TITLE="title" " lets you specify an optional descriptive title to  appear
at the bottom of the screen instead of the file name.  The title can be  up
to 29 characters in length unless /PAGE=NONE is specified in which case  it
can be up to 44 characters in length.  Multi-word titles should  appear  in
quotation marks.

"/DATE=NONE" says to leave off the date-time stamp  for  the  file  on  the
status line.  This allows a user-defined title to be up to 44 characters in
length.


READ.TXT                             3                         Mar 10, 2001

"/line" puts line "line" at the top of  the  screen.   Only  applicable  if
"filespec" (vs "@listfile") is used.

"/COLOR=nnn nnn nnn nnn" specifies the color settings to use for (in order)
(1) regular text, (2) the status line, (3) marked text, and (4) found text.
Each setting must  consist  of  three  digits,  the  first  two  being  the
foreground color and the last being the background color.   The  foreground
color should be padded on the left with a 0 if it  is  only  one  digit  in
length.  You can stop providing numbers at any point  after  the  first  if
you're willing to accept the default colors.

  For /COLOR, default is /COLOR=150 151 157 143
  For /MONO, default is  /COLOR=150 007 157 087

Foreground colors:

        Low intensity           High intensity

        0 = black                8 = dark grey
        1 = blue                 9 = light blue
        2 = green               10 = light green
        3 = cyan                11 = light cyan
        4 = red                 12 = light red
        5 = magenta             13 = light magenta
        6 = brown (or yellow)   14 = light yellow
        7 = white               15 = bright white

Adding 16 to any foreground color will make  the  text  blink.   Note  that
blinking text under Windows only works if your DOS window is  full  screen.
This can be set in the DOS properties or else just say Alt-Enter to make it
full screen.

Background colors can consist of 0 to 7 above.  Bright white on  blue,  for
example, would be "151".

"/MONO" (or "/-COLOR") forces the system into monochrome mode.

"/COLOR" (or  "/-MONO")  forces  the  system  into  color  mode.   This  is
typically the default.

"/EGA" or "/VGA" will put you in 43/50-line mode if your  monitor  supports
this.  The two options are actually synonymous (you'll get  the  best  your
monitor supports).  You can also switch to and from 25-line and  43/50-line
mode within the program by using Alt-E.

"/MOUSE" says to present the mouse menu bar even if a mouse is not present.
The program typically presents the mouse menu automatically if a  mouse  is
detected.

"/-MOUSE" says to present the  non-mouse  menu  bar  even  if  a  mouse  is
present.  The program typically presents a slightly  different  menu  if  a
mouse is not detected.


READ.TXT                             4                         Mar 10, 2001

"/DOS" allows access to the jump to DOS feature of the program (by pressing
Alt-J).  This is initially the default.

"/-DOS" prohibits jumping to DOS.  This is primarily of  use  in  libraries
where they don't want people to access  the  operating  system.   Initially
defaults to "/DOS".

"/PORT=port"  specifies  the  printer  port  to  use  for  printing.   This
typically defaults to /PORT=LPT1:.

"/INITT=string" ("initialize thin") provides the string that will  be  sent
to the printer before  printing  if  all  lines  in  the  document  are  80
characters  or  less  in  length.   The  string  can  include  decimal  and
hexadecimal characters (see BRUCEHEX.TXT file).  "\027" is the code for the
special character Escape.  You can specify /INITT=NULL if desired. Defaults
to "/INITT=NULL".

"/INITW=string" ("initialize wide") provides the string that will  be  sent
to the printer before printing if any lines in the document (not  just  the
section printed) exceed  80  characters  in  length.   See  "/INITT=string"
description.  Defaults to "/INITW=NULL".

For a Hewlett-Packard LaserJet, the  following  codes  would  typically  be
used:
        /INITT=\027E             (portrait mode, 80 column)
        /INITW=\027E\027(s16.66H (portrait mode, 132 column)

"/AFTERP=string" specifies the string to print after a partial document  is
printed.  This string can include a page eject character  ("\012")  or  any
printer  reset  codes  ("\012\027E")  you  want.   Initially  defaults   to
"/AFTERP=\012".

"/AFTERF=string" specifies the string to print after  a  full  document  is
printed.  See "/AFTERP=string" description.  Defaults to "/AFTERF=\012".

"/Iinitfile" says to  read  an  initialization  file  with  the  file  name
"initfile".  The file specification *must* contain a period.  Initfiles are
described in the BRUCEINI.TXT file.  Initially defaults to "/IREAD.INI".

"/-I" (or "/INULL") says to skip loading the initialization file.

"/Q" suppresses a message that shows up while the program searches for your
initfile.

"/ENV" says to look for %var% occurrences in the command line  and  try  to
resolve any apparent environmental variable references.   See  BRUCEINI.TXT
for more information.  This is initially the default.

"/-ENV" says to skip resolving apparent %var% occurrences  in  the  command
line.  Initially defaults to "/ENV".

"/?" or "/HELP" shows you the syntax for the command.

"/?HEX" gives you a hexadecimal and decimal conversion table.



READ.TXT                             5                         Mar 10, 2001

Viewing options:

While you're viewing a document with the READ  command,  you  can  use  the
following keys:

Cursor movement keys (up/down):

     Up                moves up one line
     Down              moves down one line
     Home              moves to the top line of the document
     End               moves to the bottom line of the document
     PgUp              moves up one screen's worth
     PgDn              moves down one screen's worth
     #line or Gline    moves to the given line in the document (goto line)
     +line             moves forward a number of lines
     -line             moves backward a number of lines

Cursor movement keys (right/left):

     Right             moves one column to the right
     Left              moves one column to the left
     Tab               moves 8 columns to the right
     Shift-Tab         moves 8 columns to the left
     Ctrl-Right        moves to the far right of the document
     Ctrl-Left         moves to the far left of the document

Search for text:

     \ or F or f       search for text within the document
                       (the search is case-insensitive; "/COMMERCE" will
                       find "Commerce", "commerce", and "COMMERCE")
     /                 search for exact (case-sensitive) text within the
                       document
     F3                search for the next occurrence of that text
     F9                search for the previous occurrence of that text

Marking lines:

     Alt-M             mark top line for copy or print
     Alt-B             mark bottom line for copy or print
     Alt-U             unmark all lines


READ.TXT                             6                         Mar 10, 2001

Copying/printing lines (can copy/print either marked lines, all  lines,  or
just the lines that are currently on the screen):

     Alt-C or Alt-D    copy (duplicate) lines to a file
     Alt-P             print lines

Next/previous documents:

     Ctrl-PgUp         go to the previous file viewed
     Ctrl-PgDn         go to the next file specified on the input line

Miscellaneous:

     Alt-E             toggles between 25-line and 43-/50-line mode (if
                       your system supports EGA and VGA respectively)
     Alt-J or Alt-G    jumps (goes) to DOS; say EXIT to get back to
                       program; this feature can be turned off using the
                       /-DOS switch
     Alt-R             shows ruler at the top of the listing
     Ctrl-P or Ctrl-F  do a form feed to the printer
     F1                show key help screen
     Esc               leave READ program

Note that you can't view beyond the beginning or end of the document.  This
is obvious but you cannot scroll to the right if you're already seeing  the
far right of the display.



READ.TXT                             7                         Mar 10, 2001

Marking and copying text:

If you need to copy a portion of your file to the  printer  or  to  another
text file, you will typically want to mark sections of the text first. This
is done using the mark functions:  Alt-M marks the top line on  the  screen
and Alt-B marks the bottom line on the screen.

For example, you might decide that you have a 2,000-line document  and  you
want to print 50 lines of it.  Go to the first line you want  to  print  or
copy (you can use the search options if you want to).   Get  that  line  at
either the top of the screen or the bottom of  the  screen.   If  it's  the
bottom line, press Alt-B; if it's the top line, press Alt-M.

Now go to the last line you want to print or copy.  Again, get that line at
either the top of the screen or the bottom of the screen and press Alt-B or
Alt-M appropriately.  Having marked two lines, the program tags those lines
and all those lines between them.  You can use the F1 (help) key;  it  will
tell you the first and last lines that are marked.

Now press Alt-C (or Alt-D) to Copy the lines elsewhere or  Alt-P  to  print
them.  When you select these functions, you'll be  asked  if  you  want  to
process the whole file, just those lines on  the  current  screen,  or  the
lines that are marked.  Ask for the marked lines.  If you  selected  Alt-C,
you'll be asked for the file name to  copy  the  lines  to.   If  the  file
already exists, you'll be allowed to overwrite the existing file or  append
to it.

Note that you can say "LPT1:" or "PRN:" when you're doing  Alt-C  in  which
case the text will go to the printer.  The differences  between  Alt-C  and
Alt-P are:

(1) Alt-P will remove linefeeds during printing whereas Alt-C  leaves  them
in.  Typically, Alt-C will result in double-spaced printing.

(2) Alt-P may reset the printer based on the width of the current  document
if a READ.INI file is used.



READ.TXT                             8                         Mar 10, 2001

Return codes:

READ returns the following ERRORLEVEL codes:

        0 = no problems
      254 = input file(s) not found
      255 = syntax problems, or /? requested


Author:

                        Bruce Guthrie
                        Room H-4885
                        U.S. Dept of Commerce/ESA/STAT-USA
                        Washington, DC 20230

                        voice: (202) 482-3234
                        e-mail: bruce.guthrie@mail.doc.gov

You may freely copy and  re-distribute  this  program;  however,  the  U.S.
Department of Commerce neither guarantees nor assures compatibility of  the
program with all computer software or hardware.

Additional information about this and other Bruce Guthrie programs  can  be
found in the file BRUCE.TXT which should be included in  the  original  ZIP
file.  The recent change  history  for  this  and  the  other  programs  is
provided in the HISTORY.ymm file which should be in the same ZIP file where
"y" is replaced by the last digit of the year and "mm"  is  the  two  digit
month of the release; HISTORY.611 came out in November 1996.

The ZIP file that contained this program and its  associated  documentation
files is named with a two-digit year followed by  a  two-digit  month.   So
READ0001.ZIP came out in January 2000.

Comments and suggestions can be sent to the  following.   Realistically,  I
will not be revising this DOS-based program  much  in  the  future  but  it
doesn't hurt to suggest things anyway.

Please provide an Internet e-mail address on all correspondence.


