path: root/usr.bin/ul/ul.1

.\"	$OpenBSD: ul.1,v 1.18 2017/10/29 22:00:22 schwarze Exp $
.\"	$NetBSD: ul.1,v 1.3 1994/12/07 00:28:23 jtc Exp $
.\"
.\" 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.
.\" 3. 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
.\"
.Dd $Mdocdate: October 29 2017 $
.Dt UL 1
.Os
.Sh NAME
.Nm ul
.Nd do underlining
.Sh SYNOPSIS
.Nm ul
.Op Fl i
.Op Fl t Ar terminal
.Op Ar
.Sh DESCRIPTION
.Nm
reads the named files (or standard input if none are given)
and translates various kinds of in-band markup to forms
appropriate for the terminal in use, as specified
by the environment variable
.Ev TERM
and the
.Xr terminfo 5
database.
In particular,
.Xr man 1
.Fl T Cm ascii ,
.Fl T Cm utf8 ,
and
.Fl T Cm locale
produce output that
.Nm
can handle as input.
.Pp
The following control characters are handled in the input stream:
.Bl -tag -width Ds
.It backspace (ASCII 0x08)
Reset the output display column to the beginning of the previous
character, to prepare for overstriking.
The display width of the previous character does not matter:
backing up over a double-width character does not require two
backspace characters.
However, if a double-width character is followed by two backspace
characters, the second one is discarded, for compatibility with
.Xr fold 1 .
.It tabulator (ASCII 0x09)
Advance the output display column to the next multiple of 8.
Tabs are always expanded into blanks.
.It newline (ASCII 0x0a)
End the current output line.
.It carriage return (ASCII 0x0d)
Reset the output display column to the beginning of the line,
to prepare for overstriking.
.It shift out (ASCII 0x0e)
Switch on reverse video mode.
.It shift in (ASCII 0x0f)
Switch off reverse video mode.
.It escape 7 (ASCII 0x1b 0x37)
Full reverse line feed.
.It escape 8 (ASCII 0x1b 0x38)
Half reverse line feed.
Sometimes used for superscripts.
.It escape 9 (ASCII 0x1b 0x39)
Half forward line feed.
Sometimes used for subscripts.
.El
.Pp
The following kinds of markup are handled:
.Bl -tag -width Ds
.It underline
Requested by putting an underscore into the same display cell as
another character, by using backspace or carriage return characters.
The usual sequence to request an underlined character is "character
backspace underscore", but "underscore backspace character" works,
too.
If the terminal cannot underline, standout mode is tried as a fallback.
.It boldface
Requested by putting two copies of the same character into the same
display cell, by using backspace or carriage return characters.
The usual sequence to request a boldface character is "character
backspace character".
If the terminal does not provide boldface display, reverse video and
standout mode are tried as fallbacks.
.It reverse video
Switched on and off by the shift out and shift in control characters,
respectively.
If the terminal does not provide reverse video, standout mode is
tried as a fallback.
.El
.Pp
If the input text contains markup the terminal cannot handle and
no working fallback is available, that markup is ignored.
Non-printable characters and invalid bytes are discarded.
Unknown escape sequences cause
.Nm
to abort with an error message and a non-zero exit code.
.Pp
The options are as follows:
.Bl -tag -width Ds
.It Fl i
Markup is not applied.
Instead, after each output line containing at least one marked-up
character, an additional line is printed, containing the following
ASCII codes below each character they apply to:
.Pp
.Bl -tag -width 1n -compact
.It _
underline
.It !
boldface
.It g
inverse video
.It ^
one half line above the current line (superscript)
.It v
one half line below the current line (subscript)
.It X
more than one kind of markup
.El
.It Fl t Ar terminal
Overrides the terminal type specified in the environment with
.Ar terminal .
.El
.Sh ENVIRONMENT
.Bl -tag -width LC_CTYPE
.It Ev LC_CTYPE
The character encoding
.Xr locale 1 .
It decides which byte sequences form characters, which characters
are printable, and what their display width is.
If set to
.Qq C ,
.Qq POSIX ,
or an unsupported value, each ASCII character except the control
characters listed above is regarded as a character, and if it is
printable, of display width 1.
.It Ev TERM
Used to relate a tty device
with its device capability description (see
.Xr terminfo 5 ) .
.Ev TERM
is set at login time, either by the default terminal type
specified in
.Pa /etc/ttys
or as set during the login process by the user in their
.Pa login
file (see
.Xr environ 7 ) .
.El
.Sh EXIT STATUS
.Ex -std
.Sh SEE ALSO
.Xr man 1 ,
.Xr terminfo 5
.Sh HISTORY
A predecessor called
.Sy iul
first appeared in
.Bx 1 .
The
.Nm
command appeared in
.Bx 3 .
.Sh AUTHORS
.An -nosplit
The original
.Bx 3
implementation was written by
.An Mary Ann Horton .
.An Bill Joy
significantly extended it for
.Bx 4.0
and
.Bx 4.2 .
.Sh BUGS
Half reverse and half forward line feeds only work on few terminals,
and full reverse line feeds aren't very portable, either.
.Pp
If more than one kind of markup is applied to the same character,
all these markups are ignored and standout mode is used instead.