."\ Master source for 78bit : /usr/src/local/man/src/78bit.rof
.TH 78bit P "Manual V1.1 for Program V1.2" "Julian Stacey" "Julian Stacey, Vector Systems Ltd"
.\" A4 the cludgy way.
.pl 29.6c
.UC 4
.SH NAME
78bit \- Interchange 8 bit bytes with 7 bit text sequences.
.SH SYNTAX
.B 78bit [files]
.SH SUMMARY
Converts between data streams of 8 bit bytes (that may include parity bits
and null characters), and 7 bit ascii text (with extra inserted sequences
where parity bits or null bytes occur).
This utility is useful as a pre and post tool/filter for the many 7 bit
programs such as screen and stream editors,
that cannot preserve and manipulate parity bits and null bytes.
.SH DESCRIPTION
.in +2
.ti -2
- The default mode of operation is to convert 8 bit data to 7 bit, 
as follows (unless -r/-8 is specified,
when the whole conversion operation sequence is inverted):
.in +4
The data stream is input a file at a time, and treated in a loop as follows:
Input is copied to output, each time a parity bit is detected,
an "Escape >" sequence is inserted,
then the input has its parity bit stripped before the data is sent to the output;
When a byte is encountered without parity bit set,
an "Escape #" sequence is inserted before input is copied to output.
Before data from the previously described stage is actually output,
the following expansions are also performed:
.ce 2
 "null" to "back slash 0" 
 "back slash" to "back slash back slash" 
.in -4

.ti -2
- You may combine usage of
.I 78bit
as both pre and post processor of 8 bit data, regardless of whether data is destined
for Epson compatible or non Epson compatible devices or programs, so long as 
you abide by the following restriction:
.in +4
.I 78bit
must be used twice, as a matched pair, first converting 8 to 7 bit
representation,
the data then being manipulated by your 7 bit limited program(s),
the data then being converted from 7 back to 8 bit representation,
before finally being applied to your 8 bit program(s) or device(s).
.in -4

.ti -2
- If you do not want to use
.I 78bit
in a matched pair mode, note that the escape sequences used by
.I 78bit
are compatible with the widely implemented Epson printer control sequences,
.\" available on such other printers as the Brother M-1509
but the delimiting of null and back slash characters is not supported by the Epson escape sequences, (but is a well used Unix/C representation).

.ti -2
- If
.I 78bit
processes more than one file, the memory of whether the input data stream
had parity asserted is cleared before each file is processed (so that
the contents of the previous file cannot affect how the next file is converted).
If this does not suit you use a syntax such as
.ce
cat file_1 file_2 | 78bit
.br
rather than
.ce
78bit file_1 file_2
.ti -2
- 
.I 78bit
Works on multiple files, writes result back to same file[s].
.ti -2
- 
.I 78bit
Works as a pipe, if no arguments are given.
.ti -2
- To save IO on unix,
for regular files,
.I 78bit
writes data to a file in the same directory as the source file, then moving the written file to the source file;
however
.I 78bit
understands that hard and symbolic links, special files, directories! and
sockets should not be moved, but should be rewritten.
.ti -2
- A temporary file is always used at present, malloc may later be used 
as a speed up for smallish files.
.ti -2
- Naming convention:
To avoid the strain of multi-lingual number articulation,
please note this program is called `seven eight bit' (or
`sieben acht bit' in German, or `sept huite bit' in French),
please do not call it `seventy eight bit' (or `acht und siebzig bit' in German,
or `soixantes dix huite' bit in French).
.in -2
.SH OPTIONS
Parameters must precede file names.
Parameters available include :-
.TP
.B \-d or \+d
.br
Preserve original date of file.
.TP
.B \-r or \+r
and
.B \-8 or \+7
.br
Reverse the normal process of character and parity manipulation. 
Convert 7 bit data without nulls back to 8 bit data with nulls.
.TP
.B \-7 or \+7
.br
Convert 8 bit data with nulls to 7 bit data without nulls but with escape sequences. (This is the default action, this option is here merely to allow 
symetrical back & forth invocation syntax.)
.TP
.B \-v or \+v
.br
Verbose mode, announce each file as processed.
.TP
.B \-V or \+V
.br
Print sccs version number.
.SH EXAMPLE
Example of how to edit a binary file with a 7 bit editor (vi).
.ce
78bit file ; vi file ; 78bit -r file
.br
or
.ce
78bit -7 file ; vi file ; 78bit -8 file

Example of how to stream edit a binary file with a 7 bit stream editor (sed).
.ce
cat 8bit_data | 78bit | sed -f edit_script | 78bit -r > /dev/printer
.br
or
.ce
cat 8bit_data | 78bit -7 | sed -f edit_script | 78bit -8 > /dev/printer

Example of how 8 bit data is represented in 7 bit format by the 
.I 78bit
program:

.nf
8 bit Data with Nulls:
.\" the next bit has back slash before multiple spaces to prevent
.\" tab -e mangling the nroff source of this manual.
.in +2
Data Byte \ : 12 \ \ \ ?? \ \ \ 12 ? \ 12 \\\ \ 12 \ \ \ \ ? ?? ? \ ?? \ \ \ 12
High Nibble: 33 \ \ \ BB \ \ \ 33 0 \ 33 5 \ 33 \ \ \ \ 8 BB D \ BB \ \ \ 33
Low \ Nibble: 12 \ \ \ 12 \ \ \ 12 0 \ 12 C \ 12 \ \ \ \ 0 12 C \ 12 \ \ \ 12
.in -2
Equivalent 7 bit data with escape sequences:
.in +2
Data Byte \ : 12 ?> 12 ?# 12 \\0 12 \\\\\ 12 ?> \\0 12 \\\\ 12 ?# 12
High Nibble: 33 13 33 12 33 53 33 55 33 13 53 33 55 33 12 33
Low \ Nibble: 12 BE 12 B3 12 C0 12 CC 12 BE C0 12 CC 12 B3 12
.in -2
.fi
.SH EXIT CODE
0 if no errors, else number of files that failed.
.SH BUGS
None known.
.SH HOST OP SYSTEM
This utility runs on both Msdos 3.2 & Unix.
.SH COPYRIGHT
Program and Document Copyright Julian H. Stacey, Munich, 25th June 1990;
.so author.jhs
.SH FILES
Temporary files with names of type 78XXXXXX are created in the same directory.
.\ End of file