.\" Copyright (c) 1980, 1991, 1993
.\"	The Regents of the University of California.  All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\" 4. Neither the name of the University nor the names of its contributors
.\"    may be used to endorse or promote products derived from this software
.\"    without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\"     @(#)ul.1	8.1 (Berkeley) 6/6/93
.\" $FreeBSD$
.\"
.Dd November 8, 2016
.Dt UL 1
.Os
.Sh NAME
.Nm ul
.Nd translate underlining and other Teletype Model 37 effects
.Sh SYNOPSIS
.Nm
.Op Fl i
.Op Fl t Ar terminal
.Op Ar
.Sh DESCRIPTION
The
.Nm
utility reads the named files (or standard input if none are given)
and translates various control sequences as found on model 37
Teletypes (TTY-37) to control sequences for the terminal in use,
writing the translated results to its standard output.
Such input is generated, for examples, by the original
.Xr nroff 1
utility, or by the GNU
.Xr groff 1
utility (if instructed with its
.Fl P-c
option to run
.Xr grotty 1
in TTY-37 mode, rather than the normal ECMA-48 mode).
.Pp
The terminal in use is specified by the environment variable
.Ev TERM .
If the
.Ev TERM 
environment variable is unset and
.Nm
is invoked with the name "cul" and its standard output is not a
terminal, it chooses the terminal type
.Li lpr .
.Ss Input control sequences
.Pp
A subset of the model 37 Teletype control sequences is understood:
.Bl -bullet -width indent
.It 
The CR (carriage return) control character resets the output position
to the first column.
.It 
The LF (line feed) control character advances to a new line.
.It 
The TAB (horizontal tab) character advances to the next column that is
a multiple of 8.  It does not cease advancing at the right margin, and
can cause a line wrap.  TAB is non-destructive, in line with the
effect on an actual TTY-37 of overstriking with a space; it does not
change characters to blanks.
.It 
The BS (backspace) control character moves the output position back by
one column, until it hits the left margin.  It does not auto-wrap back
onto previous lines, and it is non-destructive as on a real TTY-37.
.It 
Overstriking is performed by moving the current output position back
over a previous character position and outputting another printable
character.  This can be done with the CR (carriage return) or BS
(backspace) control characters.  Multiple backspace characters can be
used to move the current output position back more than one position.
.Pp
If an underscore character
.Pq Sq _
overstrikes another character, or another character overstrikes an
underscore, this signifies that the (non-underscore) character is to
be underlined.
.Pp
If a character is overstruck with itself, this signifies that the
character is to be boldfaced.  An underscore overstruck with itself
signifies underlining, not boldface.
.Pp
Any other overstriking ignores the second character and retains the
character originally in the output position.
.It 
The SI (shift in) and SO (shift out) control characters denote
switching to and from reverse video mode.
.It 
The ESC
.Li 7
sequence instructs a full reverse linefeed.
.It 
The ESC
.Li 8
sequence (half reverse linefeed) switches to superscript mode, or
performs a full reverse linefeed if used twice.
.It 
The ESC
.Li 9
sequence (half forward linefeed) switches to subscript mode, or performs
a full forward linefeed if used twice.
.El
.Pp
Unknown sequences beginning with ESC (escape) cause
.Nm
to abort with an error message.  Other zero-width characters,
including the C0 and C1 control characters, are ignored and have no
effect.  There is an automatic right margin at column 512.
.Pp
Some of these effects are also understood by
.Xr more 1 and
.Xr less 1 ;
although those two implement overstrike slightly differently, and in a
more restricted way, to how
.Nm
does.
.Ss Output translation
.Pp
The 
.Xr termcap 5
database is used to determine the appropriate control sequences to
output.  If there is no entry for the current terminal, a
.Li dumb
terminal is assumed that has the
.Va os
capability.
.Pp
If the terminal has the
.Va os
capability,
.Nm
uses overstriking for underline and boldface, using cursor motions to
print characters on top of already printed characters.  It also uses
overstriking for underline if there is no capability for underline (or
standout) mode at all nor any underline last character 
.Pq Va uc
capability, and the terminal has the
.Va ul
capability.  If there is no capability for underline or standout mode,
but there is the
.Va uc
capability, it is used for underlining.  Full reverse and forward
linefeeds use up and down cursor motions.
.Pp
Otherwise:
.Bl -bullet -width indent
.It 
Boldface uses the terminal's
.Va md 
capability, falling back if that is not present to the
.Va mr 
capability or then the
.Va so 
capability.
(i.e. Boldface is rendered as boldface, or reverse video, or
standout.)
.It 
Underline uses the terminal's
.Va us 
and 
.Va ue
capabilities, falling back to its
.Va so 
and 
.Va se
capabilities.  (i.e. Underline is rendered as true underline, or
standout.)
.It 
Reverse video uses the terminal's
.Va mr 
capability, falling back if that is not present to the
.Va so 
capability.  (i.e. Reverse video is rendered as true reverse video, or
standout.)
.It 
Superscript uses the terminal's
.Va mh 
and
.Va us 
capabilities, with the latter falling back if not present as per
underline.  (i.e. Superscript is rendered as dim underlined, or dim
standout.)
.It 
Subscript uses the terminal's
.Va mh 
capability, falling back if that is not present to the
.Va so 
capability.  (i.e. Subscript is rendered as dim or standout.)
.El
.Ss Differences from a real Teletype Model 37
.Pp
.Nm
is geared towards the outputs of
.Xr nroff 1 ,
.Xr groff 1 , 
and their ilk, which differ from strictly accurate TTY-37 semantics.
It understands the multibyte encoding of the current locale and
operates internally in terms of the C library's wide characters.  It
also has a carriage width of 512 columns.
.Pp
A real Teletype Model 37 only understands 7-bit input and is only 80
columns wide.  Similarly, a real TTY-37 has no reverse video and SI
and SO (shift in and out) would denote switching between two trays of
type.  The half-line motions are true feed motions that cause
overprinting of the top/bottom halves of other lines.
.Sh OPTIONS
.Pp
The following options are available:
.Bl -tag -width indent
.It Fl i
Instead of using terminal control sequences, TTY-37 effects are
indicated by a separate line containing marker characters for the
various effects.  This is useful when you want to look at the effects
that are present in an
.Xr nroff 1
output stream on a CRT-terminal.  Underline is denoted by
.Ql _ ,
boldface by
.Ql \&! ,
superscript by
.Ql ^ ,
subscript by
.Ql v ,
reverse video by
.Ql g ,
and combined modes (see
.Sx BUGS )
by
.Ql X .
.It Fl t Ar terminal
Overrides the terminal type specified in the environment with
.Ar terminal .
.El
.Sh ENVIRONMENT
The
.Ev LANG , LC_ALL , LC_CTYPE
and
.Ev TERM
environment variables affect the execution of
.Nm
as described in
.Xr environ 7 .
.Sh EXIT STATUS
.Ex -std
.Sh SEE ALSO
.Xr colcrt 1 ,
.Xr ascii 7 ,
.Xr man 1 ,
.Xr nroff 1
.Sh HISTORY
Bill Joy wrote a
.Xr iul 6
(indicate underline) command in
.Bx 1 ,
as a standalone version of the
.Ic :indicateul
command in
.Xr ex 1 .
This behaved like
.Nm
.Fl i
except that it did not understand ESC control sequences, shift in/out,
or overstriking for boldface.  It had a 500-column carriage width, an
automatic right-hand margin, and discarded the second character when
overstriking as
.Nm
does.
.Pp
The
.Nm
command appeared in
.Bx 2.9 
and was written by Mary Ann Horton (known as Mark Horton at the time).
.Bx 2.9 
also contained a related
.Xr greek 8 
command.
.Sh BUGS
.Pp
Attempts to combine multiple modes are not rendered properly.
.Nm
simply punts to using the terminal's standout mode if two or more
TTY-37 effects are combined.
.Pp
.Xr groff 1
in TTY-37 mode uses various overstriking effects that
.Nm
does not implement but that a real TTY-37 would.  For example, groff
generates the bullet points in this very manual page as a plus sign
.Pq Sq +
overstruck by a lower case letter O
.Pq Sq o
with the intention of producing a crossed circle.
.Xr less 1
and
.Xr more 1
do not handle this overstriking either, and display only the last
character struck, in this case the 
.Sq o .
.Nm
displays only the
.Em first
character struck, the
.Sq + .
.Pp
The
.Ql g
marker for reverse video has an obscure derivation as "graphics" or
"greek", as those are what shift in and shift out generally mean with
an actual TTY-37.  The second tray of type usually contained greek
letters or a set of graphics characters.
.Pp
Double superscript is not output properly anywhere other than the
beginning of a line.
.Pp
.Fl i
does not work well with forward and reverse linefeeds.
.Pp
The handling of FF (form feed) incorrectly assumes that it means form
feed on the current terminal also.  This is not the case for common
DEC VT terminals and terminal emulators, where FF is a line index.  
FF should translate to the
.Va cl
termcap capability.
.Pp
The handling of width greater than 1 characters in the last column can cause
buffer overflow.