[net.sources] MAN Page for Banner Program

brf (04/13/83)

.tr ~"
.TH BBAN 1 "5246 Local"
.SH NAME
.I bban
\- a
.IR b etter
.IR ban ner
program
.SH SYNOPSIS
.I bban
.RB [ \-abcdefghijklmnopqrstuvwx ]
textarg
.RB [ \- ]
.RB [ ... ]
.SH DESCRIPTION
.I bban
writes characters as large block letters, subject to a bewildering
array of optional flags, on the standard output file.
Characters are defined by entries in a 7\(mu7 matrix normally
centered in a 9\(mu9 space area.
.PP
Arguments are taken from the command line, or from the standard input,
one argument per line.  A leading minus
.RB ~ \- ~
identifies flag arguments; anything else is assumed to be
text to be printed.  A minus by itself causes
.I one
line to be read from the standard input and interpolated into the
command line at the point where the minus appears.
If no command line arguments follow the minus, additional
arguments are read from the standard input until end-of-file.
.PP
If the first argument is a flag argument it is used to reset the
defaults used for all following text arguments.
Flag arguments other than the first normally apply only to the
first text argument following them.  This allows the general plan
for a multi-line banner to be coded in the first argument and then
overridden as desired for subsequent individual lines.
Most flags are defined in pairs, so that one flag can be used to set
a default, the other to override it.  Within an individual flag
argument, flags are interpreted left-to-right.
If conflicting flags occur, the rightmost will take precedence.
Flags may be either upper or lower case.
.PP
Related flags are grouped into four categories
to simplify their comprehension:
.SS Page Positioning Flags (wiblrc)
.PP
The
.RB ( wib )
flags are immediately followed by a numerical value, interpreted as
described below.  A missing value is assumed to be zero.
.TP 6
.BR \-w #
.RI ( W idth)
The page width is set to #.
.TP
.BR \-i #
.RI ( I ndent)
# extra blanks are inserted at the beginning of each output line.
.RS 6
.TP 6
.IR Note :
Input arguments that will not fit in the
.RB ( w \- i )
spaces available for printing will be truncated on the right.
.RE
.TP
.BR \-b #
.RI ( B "lank lines)"
# extra blank lines will be output before the following
text is printed.  If
.RB ( b )
is default or if it occurs after the last text argument,
blank lines will be output after the last text argument also.
# may be negative, in which case an appropriate number of
reverse line feeds
.RI ( ascii
code
.IR esc \-7)
will be output, suitable for ingestion by
.IR col .
Some interesting results can be obtained in this manner.
Note that the
.I col
.B \-b
flag may be needed to prevent overstriking
of output characters.
.TP
.B \-lrc
.RI ( L eft,
.IR R ight,
.IR C entered)
These three flags control the justification of text output within
the boundaries defined by the
.RB ( wi )
flags.
.SS Character Spacing and Size (jotvfh)
.TP 6
.B \-jo
.RI ( J ammed,
.IR O pen)
The
.B \-j
flag causes the one space border normally surrounding the normal 7\(mu7
output character matrix to be omitted on the top and left hand side.
.B \-j
with a lower-case argument gives results similar in appearance
but one space smaller than
.B \-o
with an upper-case argument.
.TP
.B \-tv
.RI ( T all,
.IR V "ertically normal)"
The
.B \-t
flag causes each row of the 7\(mu7 matrix to be output twice,
resulting in characters that are elongated vertically.
.TP
.B \-fh
.RI ( F at,
.IR H "orizontally normal)"
The
.B \-f
flag causes each column of the 7\(mu7 matrix to be output twice,
resulting in characters that are elongated horizontally.
.IP
The
.RB ( jofh )
flags interact to determine the number of expanded banner
characters that will fit in a given printer line width.
The following table may be used as a guide:
.DS
.RS 6
.nf
.lg 0
.cs 1 24
.sp
flag  size  -w=> 72  80  81 120 132 158 174 217 225
 -hj    8         9  10  10  15  16  19  21  27  28
 -ho    9         8   8   9  13  14  17  19  24  25
 -fj   15         4   5   5   8   8  10  11  14  15
 -fo   16         4   5   5   7   8   9  10  13  14
.cs 1
.lg
.fi
.RE
.DE
.SS Marking Type (mskdaupn)
.TP 6
.B \-ms
.RI ( M "ark string,"
.IR S elf)
The
.B \-m
flag causes the
.I
next input argument
to be read and stored for use in forming the expanded banner characters.
Printable characters of the mark argument are used cyclicly to produce
a regular pattern.  Unprintable characters are ignored.  The
.B \-s
flag causes each text argument character to be used in forming itself.
Both
.B \-m
and
.B \-s
flags override the
.B \-k
option, see next.
.TP
.B \-kd
.RI (mar K ,
.IR D "efault mark)"
The
.B \-k
flag uses the text argument string to mark itself,
cyclicly, as described above for the
.B \-m
flag.  The
.B \-d
flag turns off this option, allowing an
.B \-s
or
.B \-m
flag that may have preceded it in the default flag specification to re-emerge.
.TP
.B \-au
.RI ( A sis,
.IR U ppercase)
These flags cause marking characters generated under the
.B \-s
or
.B \-k
options to be used
.IR A sis
or converted to
.IR U ppercase,
respectively.
.TP
.B \-pn
.RI ( P ositive,
.IR N egative)
The
.B \-p
flag causes those points on the 7\(mu7 matrix which define the expanded
character to be marked and the other points left blank.
.B \-n
reverses this process, leaving blank the points defining the expanded
character and marking the others,
.I including
the nominal 9\(mu9 surrounding area.  Note that since lower-case
letters are defined in the lower right corner of the 7\(mu7 matrix,
.B \-jn
"lower-case" gives similar (but smaller) results to
.B \-on
"CAPS".
.SS Miscelaneous Flags (exgq)
.TP 6
.B \-ex
.RI ( E cho,
.RI e X pand)
The
.B \-e
flag causes arguments to be passed through to the output without
expansion to banner size.  Page positioning information
.RB ( wiblrc
flags) will be applied to
.BR e -mode
output.  All flags dealing with character size, spacing, and
marking are ignored.
.B \-x
resumes the normal banner expansion of output.
.TP
.B \-g
.RI ( G lobal)
The
.B \-g
flag causes the current settings of the other flags, including the
remainder of the current flag argument, to become the defaults for
the rest of the following text arguments, rather than only for the
immediately following text argument.  It is as if the flag argument
containing the
.B \-g
flag was the first argument to
.IR bban ;
refer to the general description of flag arguments above.
.TP
.B \-q
.RI ( Q uit)
This flag causes the remainder of the current flag argument
to be ignored.  It is useful for including comments in a "canned"
banner processed from a file via input redirection.
.SS Defaults
.PP
The default flag settings are:
.BR \-lovhsupxw 120 i 0 b 0
.SH EXAMPLES
.I bban
.B \-jm
\&'\\#' text
.br
(Gives results similar to the
.I banner
command.)
.PP
.I bban
.B \-m
\&'\\' EST
.BR \-b \-8 i 1 s
EST |
.I col
.B \-b
.PP
.I bban
.B \-cjmn
NUTS '<12 blanks >'
.B \-tfo
\&' NUTS ' '<12 blanks>'
.PP
.I bban
.B \-j
LO VE |
.I bban
.B \-j
.B \-
.SH SEE ALSO
.IR banner (1),
.IR col (1),
.IR sbanner "(1, HO loc)"
.SH BUGS
It would be nice if the larger size expanded characters
.RB ( \-tf )
had more detail than allowed by the current 7\(mu7 format.
They do not.