ul |
[-i ] [-t
terminal] [file ...] |
ul
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 TERM
and the
terminfo(5) database. In
particular, man(1)
-T
ascii
,
-T
utf8
, and
-T
locale
produce output
that ul
can handle as input.
The following control characters are handled in the input
stream:
- 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
fold(1).
- tabulator (ASCII 0x09)
- Advance the output display column to the next multiple of 8. Tabs are
always expanded into blanks.
- newline (ASCII 0x0a)
- End the current output line.
- carriage return (ASCII 0x0d)
- Reset the output display column to the beginning of the line, to prepare
for overstriking.
- shift out (ASCII 0x0e)
- Switch on reverse video mode.
- shift in (ASCII 0x0f)
- Switch off reverse video mode.
- escape 7 (ASCII 0x1b 0x37)
- Full reverse line feed.
- escape 8 (ASCII 0x1b 0x38)
- Half reverse line feed. Sometimes used for superscripts.
- escape 9 (ASCII 0x1b 0x39)
- Half forward line feed. Sometimes used for subscripts.
The following kinds of markup are handled:
- 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.
- 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.
- 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.
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
ul
to abort with an error message and a non-zero
exit code.
The options are as follows:
-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:
- _
- underline
- !
- boldface
- g
- inverse video
- ^
- one half line above the current line (superscript)
- v
- one half line below the current line (subscript)
- X
- more than one kind of markup
-t
terminal
- Overrides the terminal type specified in the environment with
terminal.
LC_CTYPE
- The character encoding
locale(1). It decides which
byte sequences form characters, which characters are printable, and what
their display width is. If set to "C", "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.
TERM
- Used to relate a tty device with its device capability description (see
terminfo(5)).
TERM
is set at login time, either by the default
terminal type specified in /etc/ttys or as set
during the login process by the user in their
login file (see
environ(7)).
The ul
utility exits 0 on success,
and >0 if an error occurs.
A predecessor called
iul first
appeared in 1BSD. The ul
command appeared in 3BSD.
The original 3BSD implementation was
written by Mary Ann Horton. Bill
Joy significantly extended it for 4.0BSD and
4.2BSD.
Half reverse and half forward line feeds only work on few
terminals, and full reverse line feeds aren't very portable, either.
If more than one kind of markup is applied to the same character,
all these markups are ignored and standout mode is used instead.