! CTOOLS.HLP   Created by Martin Minow, 20-Feb-81, edited 4-Jan-82
! Edited 11-Nov-84 by TMK for RSTS/E 8.0-07
!
The following "Software Tools" are available -- all are written in
C, using the Decus compiler.  Note that all are available on an
as-is basis.
*Redirection
Except as noted in the indivdual tools, all programs support
Unix-style I/O redirection:

  tool <input.fil      Read commands from input.fil instead of
                       from the user's terminal.
  tool >output.fil     Write to output.fil instead of to the
                       user's terminal.
  tool >>output.fil    Append to output.fil (not on native RT11).

Note that this use of '<' and '>' may conflict with VMS directory
specification usage.
*Definition
Most tools are controlled by including arguments in the invocation
line. Tools can be invoked by the CRUN utility program:
               CRUN TOOL arguments

Also, if a tool is RUN, it will prompt "Argv:" for it's arguments.
*ARCH
  Usage: arch -options [-z logfile] archive_name file[s]

ARCH manages a library of text modules.  Important options include:

  -c  Force creation of new archive.
  -d  Delete file from archive.
  -i  Insert, same as update.
  -p  Print files on standard output.
  -r  Replace, same as update.
  -l  List archive contents (directory).
  -u  Update, same as replace and insert.
  -x  Extract named files.
  -v  Verbose - document all actions.
  -z  Write verbose log to indicated file.

For example:
  arch -c macfil.arc *.mac     -- Build an archive of macro programs.
  arch -x macfil.arc xyz.mac   -- Extract "xyz.mac" from the archive.
*BUILD
  Usage: build -options [-l library] [-o out_file] files

BUILD generates command files to compile C programs.  Important
options include:
  -x opsys    Operating system name, if not the one under
              which BUILD was compiled.
  -v          Verbose
  -l library  Build a library, the argument is the file name to write
              the library onto.

Programs to be build must have a "/*)BUILD ... */" comment in their
source file.
*COMM
  Usage: comm [- [123]] file_1 file_2 [out_file]

COMM compares two files for equality on a line-by-line basis.
Lines which are only in file 1 are printed in the leftmost column;
those which are only in file 2 are indented by one <TAB>; those in
both files are indented by two tabs.  Specifing options 1, 2, or 3
supress printing of the indicated column.  If the output file is
not specified, output is to the terminal (standard output).
*DETAB
  Usage: detab infile outfile

DETAB copies input to output, replacing sequences of tabs with a
string of blanks (presupposing tab stops every 8 columns). Trail-
ing blanks are removed. If the file arguments are missing, the 
standard input and output are used.
*DIFF
  Usage: diff [- [be]] file1 file2

Diff compares two files, showing what must be changed to make them
identical.  Either file1 or file2 (but not both) may refer to
directories.  If that is the case, a file in the directory whose name
is the same as the other file argument will be used.  The standard input
may be used for one of the files by replacing the argument by "-".
Except for the standard input, both files must be on a disk device.

Options:

  -b  Remove trailing whitespace (blanks and tabs) and compress
      all other strings of whitespace to a single blank.
  -e  Output is in an "editor script" format which is compatible
      with the Unix 'ed' editor.
*ENTAB
  Usage: entab [-t] infile outfile

ENTAB copies input to output, replacing sequences of blanks and tabs
by the minimum number of tabs and blanks required to give the same
visual effect. Trailing blanks and tabs are removed. Options are:

  -t  Replace a single blank with a tab if applicable.
*GREP
  Usage: grep [options] regular__expression [ file ...]

Grep searches each specified file (if none are specified, it reads
the standard input) for lines matching the given pattern.  Grep
allows wild-card file names in the file list.  The following options
are recognized:

  -c  Only print a count of matching lines.
  -f  Print file name option, see below.
  -n  Preceed each line by its line number.
  -v  Print non-matching lines.

Invoke "GREP ?" for on-line help.
*KWIK
  Usage: kwik [- [sr]] [-t offset] file_list ...

Kwik constructs a keyword in context (kwik) index using the data in
the named files, writing the resulting index to the standard output.
The standard input is read if no files are specified;
kwik may be used as a filter.  The following options are defined:

  -s  The kwik index normally excludes common (stop) words.  This
      option causes the following words to be included:
          a  an  and  by  for  from  in  of  on  to  the  with
  -r  Make the index in reverse alphabetic order.
  -t  To build index tables, the source data is entered in the format
          name<TAB>index text
      The index will be output with the name in column 1 and the
      kwik'ed text in the column indicated by the -t option.
*LEX
Usage: lex [-options] [-i grammar] [-o outfile] [-t table]

Lex compiles a lexical analyser from a grammar and description of
actions.  It is described more fully in lex.doc.  The options include:

  -a         Enable (disable?) 7-bit ascii mode.
  -i file    Read the grammar from the file instead of from the
             standard input.
  -o file    Write the output to the file instead of to lextab.c.
  -t table   Name the recognizer "table" instead of "lextab"  If -o
             is not given, output will be written to file "table.c".
  -v [file]  Verbose -- write internal tables to the file, if given,
             or to lex.out.
*LINEPR
  Usage: linepr [-o outfile] [file ...]

LINEPR prints files with line numbers and headers. The default
output is to the terminal unless the -o option is given. The
program accepts wildcard file input.
*MC
Usage: mc [-options] file_list

Mc (multi-column) writes the input files to stdout in a multi-column
format.  If no files are specified, stdin is converted.

Options:

  -c value   Number of columns, default is 2
  -h value   Height: number of lines per page, default is 60
  -w value   Width: number of columns per line, default is 132
*MP
Usage: mp infile[.c] [outfile[.mpc]]

Mp is a full-scale macro preprocessor for C programs.  If only one input
file is given, output is to "infile.mpc".  It is generally used as follows:

  mp  infile.c
  xcc infile.mpc -m
  xas infile -d
  delete infile.mpc;*

The -m option to xcc skips the Decus C preprocessor.
*NM
Usage: nm [-options] files[.obj]

Nm (NameList) reads through an object file or a TKB symbol table and
prints a list of all the symbols it finds.  Wild card filenames are
allowed.  Options include:

  -1  Output names in one column, default is four columns per line.
  -b  Include RSX-11M control block symbols.
  -c  Include C compiler internal symbols.
  -d  Differences.  The symbol table is sorted by address and the
      symbol value printed is the difference between it and the
      next symbol.  This may be used to see how large each module is.
  -f  Print symbols in file order.  No sort is performed.
  -g  Print only global symbols.  (Supress internals).
  -m  Map Radix-50 "." to underscore for C symbols.
  -r  Reverse the direction of the sort.
  -u  Print undefined symbols.  These are normally supressed.
  -v  Sort by value; the default is sort by name.
  -x  Output a cross reference of global symbols in the named files.
      The program currently allows up to 25 object files to be processed.
*OD
Usage: od [-options] [-f recordnumber] [-l recordnumber] file

Od dumps binary files in human-readable format.  Note that formatting
options may be combined.  Options include:

  -a  Dump ASCII characters
  -b  Dump octal bytes
  -f  Set first record to the argument, default is 0
  -l  Set last record to the argument, default is EOF
  -u  Unformatted:  dump physical blocks
  -w  Dump octal words
  -x  Dump hexadecimal bytes
  -5  Dump radix 50 words.
*PR
Usage: pr file_list

Each file in the argument is printed.  Each line of the output
is numbered.
*SCAT
Usage: scat [file_list]

Scat performs a wild-card lookup on all files in the argument list.
It sorts these on ascending file name, copying them, in that
order, to the standard output.  It does some limited cleanup of the
output text file.
*SORTC
  Usage: sortc [-nr] [-o outfile] [file ...]

Sortc sorts all of the named files together and writes the result
to the standard output.  The standard input is sorted if no file
names are supplied; sort may be used as a filter.  Note that
all files are assumed to be in "readable ASCII".

The sort key is the entire input line.  Default ordering is
lexicographic in ASCII collating sequence with upper and lower
case considered different.

Options:

  -o file  Write output to the named file instead of to the
           standard output.
  -n       Sort on ascending arithmetic on a leading numeric field
           consisting of digits and an optional sign.
  -r       Sort in reverse order.
*T
  Usage: t [+columns_per_line] [-lines_per_page] [file_list]

T writes files, one screen at a time, on the user's terminal.  The
argument list may contain wildcard file specifiers.  After each screen
has been printed, the user should type <space> or <Carriage-Return>
to get the next screen.  If the user types <backspace>, <linefeed>,
<delete>, '^', or <escape>, the program will back up one page.
All other characters are ignored.

Note that t works only on video terminals.  If no file_list is specified,
t prompts for each file.

T erases overstruck underline and boldface from the input text.  It does not
transmit escape sequences in the file to the user terminal.
*TODAY
 Usage: today [- | x] | [date]

Today prints the date, time, and phase of the moon in English.
If no options are given, it prints today's date and time.
The following options are available:

  - or x  Read date strings from the standard input
  date    Print information for the indicated date.

Date and time information is given in ISO numeric notation.  For
example, November 6, 1980 would be represented as "801106".  If
a time is needed, it would be appended to the date, using 24-hour
notation: "801106110402" would be a time which is exact to the
second.  To specify the century, the two-digit century number
may be prepended as "+18801106".

Non-numeric separators between the various fields are permitted:
"+1776.07.04-11:15:21".  Always give the full two-digit entries.
*TR
  Usage: tr from-chars to-chars

TR copies the standard input to the standard output with sub-
stitution or deletion of specified characters. If from-chars
and to-chars are the same length, characters in to-chars are
substituted for characters in from-chars. Case is significant.
If to-chars is left out or explicitly null, any characters in
from-chars are deleted. If to-chars is non-null but shorter 
than from-chars, all characters in from-chars beyond the last 
one in to-chars translate into the last character in to-chars,
BUT any stream of consecutive characters so translated is re-
duced to just one character long.
*UNIQ
  Usage:  uniq -options [-fields] [+letters] [ input [output] ]

Uniq reads an input file, writing each unique line.  The following
options are defined:

  -u  Only print unique lines.
  -d  Only print duplicate lines.
  -c  Print the number of times each line occurred along with
      the line.
  -N  Skip over the first N words before checking for uniqueness.
  +N  Skip over the first N letters (in the indicated field).

A word is defined as "optional spaces or tabs" followed by text up to
the first space, tab, or end of line.

If the output file is not specified, uniq will write to the standard
output.  If the input file is not specified, uniq will read from the
standard input.

For online help, invoke "uniq ?"
*WC
  Usage: wc [file_list]

Count the number of bytes, words, and lines in one or more files.
Wc accepts wild-card file name arguments.
*XRF
  Usage: xrf [-options] [-o outfile] [file ...]

Xrf prepares a cross-reference listing for C source programs.
Xrf accepts wild-card file specifiers.  Options:

  -n  Narrow output (80 columns).  The default is 132 columns.
  -s  Spool output to the default line printer.
  -o  Write output to the named file.  The default is the first
      input file encountered with a filetype (extension) of ".x".

