1.\" $OpenBSD: ul.1,v 1.16 2016/01/18 17:34:26 schwarze Exp $ 2.\" $NetBSD: ul.1,v 1.3 1994/12/07 00:28:23 jtc Exp $ 3.\" 4.\" Copyright (c) 1980, 1991, 1993 5.\" The Regents of the University of California. All rights reserved. 6.\" 7.\" Redistribution and use in source and binary forms, with or without 8.\" modification, are permitted provided that the following conditions 9.\" are met: 10.\" 1. Redistributions of source code must retain the above copyright 11.\" notice, this list of conditions and the following disclaimer. 12.\" 2. Redistributions in binary form must reproduce the above copyright 13.\" notice, this list of conditions and the following disclaimer in the 14.\" documentation and/or other materials provided with the distribution. 15.\" 3. Neither the name of the University nor the names of its contributors 16.\" may be used to endorse or promote products derived from this software 17.\" without specific prior written permission. 18.\" 19.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 20.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 21.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 22.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 23.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 24.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 25.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 26.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 27.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 28.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 29.\" SUCH DAMAGE. 30.\" 31.\" @(#)ul.1 8.1 (Berkeley) 6/6/93 32.\" 33.Dd $Mdocdate: January 18 2016 $ 34.Dt UL 1 35.Os 36.Sh NAME 37.Nm ul 38.Nd do underlining 39.Sh SYNOPSIS 40.Nm ul 41.Op Fl i 42.Op Fl t Ar terminal 43.Op Ar 44.Sh DESCRIPTION 45.Nm 46reads the named files (or standard input if none are given) 47and translates various kinds of in-band markup to forms 48appropriate for the terminal in use, as specified 49by the environment variable 50.Ev TERM 51and the 52.Xr terminfo 5 53database. 54In particular, 55.Xr man 1 56.Fl T Cm ascii , 57.Fl T Cm utf8 , 58and 59.Fl T Cm locale 60produce output that 61.Nm 62can handle as input. 63.Pp 64The following control characters are handled in the input stream: 65.Bl -tag -width Ds 66.It backspace (ASCII 0x08) 67Reset the output display column to the beginning of the previous 68character, to prepare for overstriking. 69The display width of the previous character does not matter: 70backing up over a double-width character does not require two 71backspace characters. 72However, if a double-width character is followed by two backspace 73characters, the second one is discarded, for compatibility with 74.Xr fold 1 . 75.It tabulator (ASCII 0x09) 76Advance the output display column to the next multiple of 8. 77Tabs are always expanded into blanks. 78.It newline (ASCII 0x0a) 79End the current output line. 80.It carriage return (ASCII 0x0d) 81Reset the output display column to the beginning of the line, 82to prepare for overstriking. 83.It shift out (ASCII 0x0e) 84Switch on reverse video mode. 85.It shift in (ASCII 0x0f) 86Switch off reverse video mode. 87.It escape 7 (ASCII 0x1b 0x37) 88Full reverse line feed. 89.It escape 8 (ASCII 0x1b 0x38) 90Half reverse line feed. 91Sometimes used for superscripts. 92.It escape 9 (ASCII 0x1b 0x39) 93Half forward line feed. 94Sometimes used for subscripts. 95.El 96.Pp 97The following kinds of markup are handled: 98.Bl -tag -width Ds 99.It underline 100Requested by putting an underscore into the same display cell as 101another character, by using backspace or carriage return characters. 102The usual sequence to request an underlined character is "character 103backspace underscore", but "underscore backspace character" works, 104too. 105If the terminal cannot underline, standout mode is tried as a fallback. 106.It boldface 107Requested by putting two copies of the same character into the same 108display cell, by using backspace or carriage return characters. 109The usual sequence to request a boldface character is "character 110backspace character". 111If the terminal does not provide boldface display, reverse video and 112standout mode are tried as fallbacks. 113.It reverse video 114Switched on and off by the shift out and shift in control characters, 115respectively. 116If the terminal does not provide reverse video, standout mode is 117tried as a fallback. 118.El 119.Pp 120If the input text contains markup the terminal cannot handle and 121no working fallback is available, that markup is ignored. 122Non-printable characters and invalid bytes are discarded. 123Unknown escape sequences cause 124.Nm 125to abort with an error message and a non-zero exit code. 126.Pp 127The options are as follows: 128.Bl -tag -width Ds 129.It Fl i 130Markup is not applied. 131Instead, after each output line containing at least one marked-up 132character, an additional line is printed, containing the following 133ASCII codes below each character they apply to: 134.Pp 135.Bl -tag -width 1n -compact 136.It _ 137underline 138.It ! 139boldface 140.It g 141inverse video 142.It ^ 143one half line above the current line (superscript) 144.It v 145one half line below the current line (subscript) 146.It X 147more than one kind of markup 148.El 149.It Fl t Ar terminal 150Overrides the terminal type specified in the environment with 151.Ar terminal . 152.El 153.Sh ENVIRONMENT 154.Bl -tag -width LC_CTYPE 155.It Ev LC_CTYPE 156The character set 157.Xr locale 1 . 158It decides which byte sequences form characters, which characters are 159printable, and how many output display columns each character occupies. 160If set to 161.Qq C , 162.Qq POSIX , 163or an unsupported value, each ASCII character except the control 164characters listed above is regarded as a character, and if it is 165printable, of display width 1. 166.It Ev TERM 167Used to relate a tty device 168with its device capability description (see 169.Xr terminfo 5 ) . 170.Ev TERM 171is set at login time, either by the default terminal type 172specified in 173.Pa /etc/ttys 174or as set during the login process by the user in their 175.Pa login 176file (see 177.Xr environ 7 ) . 178.El 179.Sh EXIT STATUS 180.Ex -std 181.Sh SEE ALSO 182.Xr man 1 , 183.Xr terminfo 5 184.Sh HISTORY 185The 186.Nm 187command appeared in 188.Bx 3.0 . 189.Sh BUGS 190Half reverse and half forward line feeds only work on few terminals, 191and full reverse line feeds aren't very portable, either. 192.Pp 193If more than one kind of markup is applied to the same character, 194all these markups are ignored and standout mode is used instead. 195