Annotation of src/usr.bin/ul/ul.1, Revision 1.17
1.17 ! schwarze 1: .\" $OpenBSD: ul.1,v 1.16 2016/01/18 17:34:26 schwarze Exp $
1.1 deraadt 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.
1.10 millert 15: .\" 3. Neither the name of the University nor the names of its contributors
1.1 deraadt 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: .\"
1.17 ! schwarze 33: .Dd $Mdocdate: January 18 2016 $
1.1 deraadt 34: .Dt UL 1
1.4 aaron 35: .Os
1.1 deraadt 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
1.14 sobrado 43: .Op Ar
1.1 deraadt 44: .Sh DESCRIPTION
1.5 aaron 45: .Nm
1.1 deraadt 46: reads the named files (or standard input if none are given)
1.16 schwarze 47: and translates various kinds of in-band markup to forms
48: appropriate for the terminal in use, as specified
1.1 deraadt 49: by the environment variable
1.16 schwarze 50: .Ev TERM
51: and the
52: .Xr terminfo 5
53: database.
54: In particular,
55: .Xr man 1
56: .Fl T Cm ascii ,
57: .Fl T Cm utf8 ,
58: and
59: .Fl T Cm locale
60: produce output that
61: .Nm
62: can handle as input.
63: .Pp
64: The following control characters are handled in the input stream:
65: .Bl -tag -width Ds
66: .It backspace (ASCII 0x08)
67: Reset the output display column to the beginning of the previous
68: character, to prepare for overstriking.
69: The display width of the previous character does not matter:
70: backing up over a double-width character does not require two
71: backspace characters.
72: However, if a double-width character is followed by two backspace
73: characters, the second one is discarded, for compatibility with
74: .Xr fold 1 .
75: .It tabulator (ASCII 0x09)
76: Advance the output display column to the next multiple of 8.
77: Tabs are always expanded into blanks.
78: .It newline (ASCII 0x0a)
79: End the current output line.
80: .It carriage return (ASCII 0x0d)
81: Reset the output display column to the beginning of the line,
82: to prepare for overstriking.
83: .It shift out (ASCII 0x0e)
84: Switch on reverse video mode.
85: .It shift in (ASCII 0x0f)
86: Switch off reverse video mode.
87: .It escape 7 (ASCII 0x1b 0x37)
88: Full reverse line feed.
89: .It escape 8 (ASCII 0x1b 0x38)
90: Half reverse line feed.
91: Sometimes used for superscripts.
92: .It escape 9 (ASCII 0x1b 0x39)
93: Half forward line feed.
94: Sometimes used for subscripts.
95: .El
96: .Pp
97: The following kinds of markup are handled:
98: .Bl -tag -width Ds
99: .It underline
100: Requested by putting an underscore into the same display cell as
101: another character, by using backspace or carriage return characters.
102: The usual sequence to request an underlined character is "character
103: backspace underscore", but "underscore backspace character" works,
104: too.
105: If the terminal cannot underline, standout mode is tried as a fallback.
106: .It boldface
107: Requested by putting two copies of the same character into the same
108: display cell, by using backspace or carriage return characters.
109: The usual sequence to request a boldface character is "character
110: backspace character".
111: If the terminal does not provide boldface display, reverse video and
112: standout mode are tried as fallbacks.
113: .It reverse video
114: Switched on and off by the shift out and shift in control characters,
115: respectively.
116: If the terminal does not provide reverse video, standout mode is
117: tried as a fallback.
118: .El
119: .Pp
120: If the input text contains markup the terminal cannot handle and
121: no working fallback is available, that markup is ignored.
122: Non-printable characters and invalid bytes are discarded.
123: Unknown escape sequences cause
1.5 aaron 124: .Nm
1.16 schwarze 125: to abort with an error message and a non-zero exit code.
1.1 deraadt 126: .Pp
1.5 aaron 127: The options are as follows:
1.1 deraadt 128: .Bl -tag -width Ds
129: .It Fl i
1.16 schwarze 130: Markup is not applied.
131: Instead, after each output line containing at least one marked-up
132: character, an additional line is printed, containing the following
133: ASCII codes below each character they apply to:
134: .Pp
135: .Bl -tag -width 1n -compact
136: .It _
137: underline
138: .It !
139: boldface
140: .It g
141: inverse video
142: .It ^
143: one half line above the current line (superscript)
144: .It v
145: one half line below the current line (subscript)
146: .It X
147: more than one kind of markup
148: .El
1.1 deraadt 149: .It Fl t Ar terminal
150: Overrides the terminal type specified in the environment with
151: .Ar terminal .
152: .El
153: .Sh ENVIRONMENT
1.16 schwarze 154: .Bl -tag -width LC_CTYPE
155: .It Ev LC_CTYPE
1.17 ! schwarze 156: The character encoding
1.16 schwarze 157: .Xr locale 1 .
1.17 ! schwarze 158: It decides which byte sequences form characters, which characters
! 159: are printable, and what their display width is.
1.16 schwarze 160: If set to
161: .Qq C ,
162: .Qq POSIX ,
163: or an unsupported value, each ASCII character except the control
164: characters listed above is regarded as a character, and if it is
165: printable, of display width 1.
1.1 deraadt 166: .It Ev TERM
1.6 aaron 167: Used to relate a tty device
1.1 deraadt 168: with its device capability description (see
1.16 schwarze 169: .Xr terminfo 5 ) .
1.1 deraadt 170: .Ev TERM
171: is set at login time, either by the default terminal type
172: specified in
173: .Pa /etc/ttys
174: or as set during the login process by the user in their
175: .Pa login
176: file (see
1.9 jmc 177: .Xr environ 7 ) .
1.1 deraadt 178: .El
1.16 schwarze 179: .Sh EXIT STATUS
180: .Ex -std
1.1 deraadt 181: .Sh SEE ALSO
1.16 schwarze 182: .Xr man 1 ,
183: .Xr terminfo 5
1.7 aaron 184: .Sh HISTORY
185: The
186: .Nm
187: command appeared in
188: .Bx 3.0 .
1.16 schwarze 189: .Sh BUGS
190: Half reverse and half forward line feeds only work on few terminals,
191: and full reverse line feeds aren't very portable, either.
192: .Pp
193: If more than one kind of markup is applied to the same character,
194: all these markups are ignored and standout mode is used instead.
![[BACK]](/icons/back.gif){kind=icon}
Return to ul.1 CVS log ![[TXT]](/icons/text.gif){kind=icon}
![[DIR]](/icons/dir.gif){kind=icon}
Up to [local] / src / usr.bin / ul