Software of the Month Club 1995 December/SOFM_Dec1995.bin/pc/dos/utility/isam/ready.doc

Text File | 1995-10-31 | 18KB | 409 lines

READY.DOC                            1                         Revised: 09/09/95

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

                        [phone]

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.

Foreign users:  Please provide an Internet e-mail address in all  correspondence
or and just e-mail your problems to me at [e-mail]


The READY.EXE program is a text file viewer and offers most of the functions  of
the similar READ.EXE program.  It is, however, a stripped-down version  of  READ
and it processes files in a totally different  way  so  it  has  some  different
features.


Features of the READY program:
  * Handles files of an unlimited number of lines.
  * 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.
  * Allows a user-specified string after partial or full text is 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).
  * Allows case-insensitive text searching within the file.
  * Shows a ruler line if desired.
  * Shows the file before it has finished loading so you can start reading
    sooner.
  * Provides the ability to show line numbers on the screen.
  * Expands tabs for display.
  * Allows lines over 80 characters to be either truncated, wrapped, or split so
    they fit on one screen.
  * Allows specified words to be highlighted throughout the text so they can be
    identified more easily.  (This is different from the typical "Find"
    feature.)
  * Can Ctrl-PgUp/Ctrl-PgDn among up to 100 files.
  * Allows the user to adjust terminal colors.



READY.DOC                            2                         Revised: 09/09/95

READY's advantages over READ:
  * It can handle files of unlimited line counts.
  * It can be very quick processing files the second time they are viewed.
  * It takes up much less memory than READ requires.
  * It provides the ability to show line numbers on the screen.
  * Expands tabs for display (READ displays them as little circles).
  * Wraps or splits up long lines for display.
  * Allows word highlighting throughout a document.
  * Allows the user to specify a range of lines to read.


READY's disadvantages over READ:
  * It handles files by rewriting them out to (by default) your C drive.  So a
    large file will take up considerable disk space.
  * Any lines that are wider than 80 characters are truncated, wrapped, or
    split up instead of being able to view them all.
  * It does not support some of the special functions that READ handles.
    Specifically, forget all of the following (although they could be added if
    people really demanded them):
      Ctrl-P         Printer formfeed
      /              Case-sensitive search (only non-sensitive searches work)
      #line          Skip to a specified line number
      -line          Move backward x-number of lines
      +line          Move forward x-number of lines
  * It does not provide any printer setup options.
  * It does not provide any mouse support.

However, in many cases, this is a very useful command.



READY.DOC                            3                         Revised: 09/09/95

Temporary file:

The program writes out a random-access file as (by default) C:\READY.TMP.   This
file contains one 80-character record for every line in your original file.   In
general, this file will be much  larger  than  your  original  file.   When  the
program finishes, by default it deletes the temporary file.

The process of reading and writing the file can  take  awhile  for  large  files
although it's fairly quick for small files.

You can retain the temporary file if you'd like and the file can be written to a
networked drive if desired.  This makes secondary reads quicker.

If the temporary file is retained, the program is smart enough  to  compare  the
file date and time of the original file with the file stored  in  the  temporary
file.  If the original file has been updated  or  is  different  from  the  file
stored in the temporary file,  the  program  will  reprocess  the  source  file.
Otherwise, it will just read the temporary file.

For example, if you run the program with this command:

        READY J:\EBBNEW\DATA\BULL12.TXT /TJ:\EBBNEW\BULL12.TMP /KEEP

the  first  time  the  program  is  run,  it  will  create  the  temporary  file
(BULL12.TMP) based on BULL12.TXT and then will keep  the  temporary  file.   The
next time you (or someone) issues the same command,  it  will  notice  that  the
BULL12.TXT file hasn't been  updated  so  it  will  immediately  work  with  the
temporary file.  If the source file (BULL12.TXT) gets updated, the program  will
notice it's been updated and reprocess the file.



READY.DOC                            4                         Revised: 09/09/95

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 below),
  - Through the use of an environmental variable (SET READ=whatever), or
  - From the command line (see "Syntax" below)

Note that the READY program allows you to provide the same  parameters  accepted
by the READ program.  READY just ignores any parameters that it does not in fact
support.  It even reads the READ.INI file by default.


The READ.INI file:

READY will read a READ.INI file if one is found.  (You can specify  a  different
file name if desired.) The file is an  ASCII  text  file  that  can  be  created
maintained by hand.  The file can consist or one or more command line parameters
(only those that begin with a "/"), one statement per line.  For example:
        /MONO
        /-DOS
        /COLOR=123 134 145 156

The file can also contain comments which are blank lines or any  line  beginning
with:
        ;    (semi-colon)
        :    (colon)
        '    (quote)

READ looks for the initialization file in your default subdirectory  first.   It
then searches for it in the subdirectory where the executable was and then  goes
through your DOS path.

Passing in "/-I" or "/INULL" skips  loading  the  INI  file.   This  saves  some
execution time as the program does not need to search your path for the file.

You can combine *.INI files from this and other routines I have out there.  This
is useful if you're tired of having a lot of *.INI files out there.  To do this,
make a single *.INI file (such as  ALL.INI)  and  include  blocks  in  it.   The
routine will look for the block that's the name of the  core  routine  (in  this
case, "[READ]") and only processes the records within that block.  For example,

        ; ALL.INI -- contains all of the INI statements
        [DATES]
        /SORT
        [FILL]
        /ON
        /SPLIT
        [READ]
        /MONO

You can either pass in the name of the INI file  ("/IALL.INI")  or  the  routine
will use a "SET  BG=filename"  (e.g.  "SET  BG=ALL.INI")  parameter  if  one  is
provided.



READY.DOC                            5                         Revised: 09/09/95

Syntax:

    READY { filename | /Tfilename } [ /KEEP | /-KEEP ]
      [ /TRUNCATE | /SPLIT | /WRAP ] [ /INDENT=n ] [ /H word [ word ]... ]
      [ /DATE | /-DATE ] [ /TIME | /-TIME ] [ /DOS | /-DOS ]
      [ /PORT=port ] [ /AFTERP=string ] [ /AFTERF=string ]
      [ /Iinitfile | /-I ] [ /MONO | /COLOR ] [ /EGA | /VGA ]
      [ /COLOR=nnn nnn nnn nnn nnn ] [ /n | /n1-n2 | /n1+n2 | -n ] [ /? ]

where:

"filename" is the input file to be processed.  Note that either an input file or
a temporary file has to be provided; if neither is provided, you'll be  prompted
for the file name to view.  You can specify  both  if  you'd  like.   Full  path
specifications work fine and wildcards are supported.

"/Tfilename" specifies the name of the temporary file.  The  file  will  contain
one 80-character record for each line in the source file plus one line which  is
used to identify the input file.  The temporary file is  stored  by  default  as
C:\READY.TMP so "/TC:\READY.TMP"  is  the  default  value  for  this  parameter.
Wildcards are not allowed for the temporary file name.

"/KEEP" says to keep the temporary file around after you leave the command.   By
default, the temporary file is saved if a temporary file is explicitly provided.

"/-KEEP" says to delete the temporary file no matter what.

"/TRUNCATE" says to truncate any line over 80 characters  (any  text  after  the
80th character are deleted).  This is initially the default.

"/SPLIT" says, for display purposes, to truncate any  line  over  80  characters
(any text  after  the  80th  character  is  wrapped  to  the  next  line).   The
continuation lines are indented  by  the  number  of  spaces  specified  in  the
/INDENT=n parameter.  Line counts shown will be the number of wrapped lines, not
the original number of lines.  Note that if you print or copy to disk  the  file
from within READY, it will write out the lines as  split  lines,  not  in  their
original format.

"/WRAP" says, for display purposes, to split any lines  over  80  characters  by
looking for the last full word before 80 characters and  wrapping  the  line  at
that point.  The continuation lines are trimmed of leading spaces and  are  then
indented by the number of spaces specified in the /INDENT=n parameter.  See  the
"/SPLIT" parameter above for additional caveats.

"/INDENT=n" specifies that n-spaces are  to  be  added  to  the  start  of  each
continued line.  Defaults to "/INDENT=3".  If you don't want any indentation  at
all, specify "/INDENT=0".


READY.DOC                            6                         Revised: 09/09/95

"/H word..." highlights up to 10 words throughout  the  text.   Highlighting  is
done on a word-by-word basis; not by phrase.  So the words to highlight  do  not
have to appear together in the text to be found.  You can also ask for or change
the words to be highlighted by using "H" within the program.

"/DATE" displays the file date and time on the status line; this is the default.

"/-DATE" skips displaying the file date and time on the  status  line.   If  you
want to display the file time but not the date, specify /-DATE before /TIME.

"/TIME" displays the file  time  on  the  status  line;  this  is  the  default.
Specifying "/-DATE" will turn off the time display by default.

"/-TIME" skips displaying the file time on the status line.   Specifying  "/DATE
will turn on the time display by default.

"/DOS" allows the user to say Alt-J to  jump  to  DOS.   Initially  defaults  to
"/DOS".

"/-DOS" prohibits jumping to DOS.

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

"/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.  If no drive or path information
is specified, the program will search for initfile  beginning  in  your  default
subdirectory  and  then  going  throughout  your  DOS  path.   The  use  of   an
initialization file is optional.  Initially defaults to "/IREAD.INI".

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

"/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.


READY.DOC                            7                         Revised: 09/09/95

"/COLOR=nnn nnn nnn nnn nnn" specifies the color settings to use for (in  order)
(1) regular text, (2) the status line, (3) marked text, (4) found text, and  (5)
highlighted words.  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.  Defaults to "/COLOR=150 151 157 143 127".  You  can  stop  providing
numbers at any point after the first if you're willing  to  accept  the  default
colors.

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               14 = light yellow
        7 = white               15 = bright white

Adding 16 to any color will make the text blink.  Background colors can  consist
of 0 to 7 above.  Bright white on blue, for example, would be "151".

"/n" says to process lines beginning with line n.  For example, "/1000" says  to
read the file beginning with line 1000.

"/n1-n2" says to process lines n1 through  n2.   For  example,  "/500-700"  will
process lines 500 to 700.

"/n1+n2" says to  process  n2  lines  beginning  with  line  n1.   For  example,
"/500+500" will process lines 500 to 999.

"/-n" (or "/+n") says to stop after processing the first n lines.  For  example,
"/+100" says to process only the first 100 lines of the file.

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



READY.DOC                            8                         Revised: 09/09/95

Viewing options:

While you're viewing a  document  with  the  READY  command,  you  can  use  the
following keys.  These are a subset of the commands  available  in  the  regular
READ command:

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

Search for text:

     \ or F or f or /  search for text within the document
                       (the search is case-insensitive; "/COMMERCE" will find
                       "Commerce", "commerce", and "COMMERCE")
     F3                search for the next occurrence of that text
     F9                search for the previous occurrence of that text
     H or h            highlights up to 10 words throughout your text;
                       highlighting is done on a word-by-word basis, not by
                       phrase, so the words do not have appear near each other
                       to be highlighted (the search for text option, above, on
                       the other hand, looks for phrases, not words)

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

Copying and printing lines (if lines are marked, the program  copies/prints  the
marked lines; if no lines are  marked,  the  program  copies/prints  the  entire
file):

     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
     Alt-N             shows line numbers on the left side of the screen
     F1                show key help screen
     Esc               leave READY program


READY.DOC                            9                         Revised: 09/09/95

Marking and copying/printing text:

If you need to copy/print a portion of your 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  (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.  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.

Now press Alt-P to print them.  All marked lines will be printed.

Copying works similarly.  Use Alt-C (or Alt-D) to copy the lines to a file.

Note that the program truncates any lines over 80 characters so those  will  not
be printed or copied.