."\ Master source for overlay manual : /usr/src/local/man/src/overlay.rof
.TH OVERLAY P " V1.0 13 July 89 for Prog. V1.6" "Julian Stacey" "Julian Stacey, Vector Systems Ltd"
.\" A4 the cludgy way.
.pl 29.6c
.UC 4
.SH NAME
overlay \- Overlay 2 files characater for character to output.

.SH SYNTAX
.B overlay
[ [-b] [-s] in_file_1 [in_file_2] [-o output_file [-f] ] ]

.SH SUMMARY
Overlays 2 files, producing a merged file,
white space is allowed to overlap, but nothing else,
for each occurence where non white space characters overlay
each other, a ^G is output, and the location of the first
overlay error is reported after output is completed.

.I Overlay
can be used as a post filter to
.I nroff,
to add letter-heads.

.SH DESCRIPTION
.I Overlay
is not a standard Unix command, it is unique to VSL systems with the Ournix overlay.

Typically use is to merge a headed letter template with an actual letter,
or to merge a standard monthly invoice with particular numbers.
Input can be either one or two files, if just one is specified, then stdin
is taken as the second input.
Output is to stdout, unless otherwise specified by -o.
Stderr is used if it is necessary to report the position of a first error.

.SH OPTIONS
Parameters must precede file names.
Parameters available include :-
.TP
.B \-b
Brother Printer
.br
Try to compensate for a nasty printer that does a single pixel down shift after each underline character.
A compensation sequence is prepended at the beginning of each line containing an
underscore.
.TP
.B \-o
Specify that output is to go to a named file.
-o - makes the named file stdout.
If
.I overlay
detects an error no output is produced.
So far as described, functionality of
.I overlay
-o is similar to the -o flag of
.I cc,
however see -f flag description.
.TP
.B \-s
Silent, no normal output, just returns error output & status.
.TP
.B \-f
Force output if -o has been invoked, even if an error is detected, (normally
-o only produces output if there is no everlay error.

Note
.ti +5
.I overlay
-o -f output_file
.br
would result in a listing to stdout (as the command syntax above is wrong),
two correct syntax examples are :-
.ti +5
.I overlay
-o output_file -f source_1 source_2
.br
or
.ti +5
.I overlay
-f -o output_file source_1 source_2

Note -s & -f cannot be used together.

.SH RESTRICTIONS

.I Overlay
treats most characters apart from \\n as a continuous byte stream,
.I overlay
has no understanding of tabs, backspace, form feed, epson escape sequences, etc.
Underscore (_), is allowed for however ( so an underscore line can merge with data).
Overlaying a line with tabs, and a line with spaces, produces unpleasant
results, so use tab -d first.
If input files are plain text, conside using
.I tab -d
 (or possibly)
.I tab -e,
on both files before passing data to
.I overlay.

.SH EXAMPLE

.I overlay
letter header | lpr

Overlays the body of a letter, with a company letterhead, and pipes it to the print spooler.

.SH EXIT CODE

0 if no error has occured, -1 if a file access or parameter error occurs,
else line number of first overlaying error error.

.SH HOST OP SYSTEM

This utility runs on both Msdos 3.2 & Unix UCB BSD 4.2.

.SH COPYRIGHT

Program and Document Copyright Julian H. Stacey, Munich, May 1989.
.so author.jhs
.SH ENHANCEMENTS LATER

Allow more than 2 input files.
.br
-t tabs flag
.br
-e epson escape flag

.SH FILES

Unix:	overlay_XXXXXX
.br
Msdos:	/tmp/ovXXXXXX

.SH SEE ALSO

tab(P)
.\ End of file