.*
.* Software tools introductory document
.*
.dm ITAL /.sf 3/%1 %2 %3 %4 %5 %6 %7 %8 %9/.sf 0/
.dm BOLD /.sf 2/%1 %2 %3 %4 %5 %6 %7 %8 %9/.sf 0/
.rm 72
.sp 15
.sf 2
.ce 5
Software Tools

for the

IBM Personal Computer
.sp 26
.sf 0
.sf 1
.fo !Version: 2.0!!Date:    08/01/83!
.sf 0
.bp 1
.hd 0 Introduction
Presented here are some useful tools, which were originally presented
in the book "Software Tools in Pascal" by Brian W. Kernighan and
P. J. Plauger.  The conversion was non-trivial, and in some cases
the tools have been enhanced, but all in all the tools are
very similiar.  Thus, the reader should refer to this book
for extensive descriptions of the commands and how they were
implemented.

The commands described on the following pages have several
features in common, as follows:

.in 3
.ti -3
1)@Input and Output from all commands may be redirected to any device.
The commands all read from "Standard Input" and write to "Standard
Output" by default, although some allow filenames to be specified
on the command line.  Most however act only as
.ital filters,
reading from STDIN and writing to STDOUT.  STDIN and STDOUT both
default to the terminal if unspecified.  However, if an argument
of the format "{filename" is found, it will be assumed that STDIN
must come from that file.  Likewise, an argument of the format
"}filename" redirects standard output.  The filename may be
any special device (eg. 'PRN:' or 'LPT1').

.bold Note:
Be careful with this.  If you accidentally enter }filename when you
meant to enter {filename, the file is immediately set to 0 bytes
in size (that is, it is destroyed).  A prompt might be nice... if
you can find the time to add it to the 'initio' routine.

.bold Note2:
If you are using DOS 2.0, it also allows you to redirect input and output
with the < and > characters.  However, because of a bug in DOS 2.0 or
a bug in the Pascal Runtime routines for I/O, if you redirect input to
one of these utilities using the < character, it will hang the system!
So please be careful to use the { character.  Redirection of output with
the > character should cause no problems.

.ti -3
2)@If an argument is found with the special characters "?" or "*"
in it, it is assumed to be a general name for a filename, and
the argument will be replaced with all files which match the
pattern.  That is, if the argument is '*.fmt' and the files
.ital a.fmt, b.fmt,
and
.ital c.fmt
exist, then giving the command:

fmt *.fmt

is equivalent to the command:

fmt a.fmt b.fmt c.fmt

The names will be in sorted order on the command line.

.ti -3
3)@If you need to have an argument with a ?, *, or imbedded blanks
passed to a program, you may place it in double quotes (") or
single quotes ('), or precede a single special character with a
backslash (\).
.bp
.hd 0 Source Code Arrangement
.bold Note:
There is a whole bunch of stuff here, and most of the useful tools
are so large that a hard disk is almost required to load all the
source, object, and include files on the same disk.  I'm sure if
you tried hard enough, it could be done on 2 double sided floppys
however (1 tool at a time).
.sp
All source for each tool is contained in an 'archive' file.
The following archive files exist:
.sp
.nf
ARCHIVE  AR     12621  10-27-82  11:14p
CHARCNT  AR       732  11-03-82   1:44a
ECHOARG  AR       827  10-27-82  11:55p
FINDP    AR      2202  10-27-82  11:50p   <-- Needed for Change
FMT      AR     35615   3-07-83  11:26p
KWIC     AR      1612  11-03-82   8:12p
LINECNT  AR       753  11-03-82   1:43a
MACRO    AR     23691  10-27-82  11:45p
PRIMS    AR     18467  11-02-82  10:51p   <-- General primitives
PRINTF   AR      2809  11-03-82   1:45a
SORTF    AR     15103   1-09-83   1:52p   <-- Needed for Sortf & Kwic
TED      AR     41318  11-03-82   2:11a   <-- Needed for Ted, Findp, & Change
TRANSLIT AR      3798  11-02-82  11:26p
UNIQUE   AR       870  11-03-82   1:49a
UNROTATE AR      1365  11-03-82   1:50a
UTILITY  AR      8388  10-30-82  11:18a   <-- General utilities
WORDCNT  AR       902  11-03-82   1:43a
.fi
.sp
The general procedure to create an executable version of a tool
is as follows:
.sp
.nf
   1) Make sure you have all .DCL, .INC, and .OBJ files on the
      current disk.
   2) Give command 'archive -x y:xxxxx.ar' where "xxxxx" is the name of
      the tool you are building and y: is the disk the .AR file is on.
      This extracts the files from the archive file.
   3) Give command 'mktool xxxxx'.
.fi
.sp
General Notes:
.br
.in +5
1)@One tricky thing about these tools is they have the type 'STRING'
redefined as 'PACKED ARRAY[1..MAXSTR] of 0..255'.  This is so the
tools are easily portable to any environment (even EBCDIC machines).
.sp
2)@Even the simplest of these tools has a HUGE runtime .EXE file.
This is because IBM Pascal has a huge runtime library, which for
some reason insists on loading together (even if most of the
routines are unused).
.bp
.im archive.man
.bp
.im change.man
.bp
.im charcnt.man
.bp
.im echoarg.man
.bp
.im findp.man
.bp
.im fmt.man
.bp
.im kwic.man
.bp
.im linecnt.man
.bp
.im macro.man
.bp
.im printf.man
.bp
.im sortf.man
.bp
.im ted.man
.bp
.im translit.man
.bp
.im unique.man
.bp
.im unrotate.man
.bp
.im wordcnt.man