Annotation of src/usr.bin/infocmp/infocmp.1tbl, Revision 1.6
1.1 millert 1: '\" t
1.6 ! millert 2: .\" $OpenBSD: infocmp.1tbl,v 1.5 1999/12/12 04:49:19 millert Exp $
1.1 millert 3: .\"
4: .\"***************************************************************************
5: .\" Copyright (c) 1998 Free Software Foundation, Inc. *
6: .\" *
7: .\" Permission is hereby granted, free of charge, to any person obtaining a *
8: .\" copy of this software and associated documentation files (the *
9: .\" "Software"), to deal in the Software without restriction, including *
10: .\" without limitation the rights to use, copy, modify, merge, publish, *
11: .\" distribute, distribute with modifications, sublicense, and/or sell *
12: .\" copies of the Software, and to permit persons to whom the Software is *
13: .\" furnished to do so, subject to the following conditions: *
14: .\" *
15: .\" The above copyright notice and this permission notice shall be included *
16: .\" in all copies or substantial portions of the Software. *
17: .\" *
18: .\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS *
19: .\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF *
20: .\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. *
21: .\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, *
22: .\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR *
23: .\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR *
24: .\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. *
25: .\" *
26: .\" Except as contained in this notice, the name(s) of the above copyright *
27: .\" holders shall not be used in advertising or otherwise to promote the *
28: .\" sale, use or other dealings in this Software without prior written *
29: .\" authorization. *
30: .\"***************************************************************************
31: .\"
1.4 millert 32: .\" $From: infocmp.1m,v 1.21 1999/06/15 23:12:25 tom Exp $
1.1 millert 33: .TH infocmp 1 ""
34: .ds n 5
35: .ds d /usr/share/terminfo
36: .SH NAME
37: \fBinfocmp\fR - compare or print out \fIterminfo\fR descriptions
38: .SH SYNOPSIS
1.4 millert 39: \fBinfocmp\fR [\fB-dceEGgnpILCuV1\fR] [\fB-v\fR \fIn\fR] [\fB-s d\fR| \fBi\fR| \fBl\fR| \fBc\fR]
1.1 millert 40: .br
1.4 millert 41: [\fB-w\fR\ \fIwidth\fR] [\fB-A\fR\ \fIdirectory\fR] [\fB-B\fR\ \fIdirectory\fR]
42: .br
43: [\fItermname\fR...]
1.1 millert 44: .SH DESCRIPTION
45: \fBinfocmp\fR can be used to compare a binary \fBterminfo\fR entry with other
46: terminfo entries, rewrite a \fBterminfo\fR description to take advantage of the
47: \fBuse=\fR terminfo field, or print out a \fBterminfo\fR description from the
48: binary file (\fBterm\fR) in a variety of formats. In all cases, the boolean
49: fields will be printed first, followed by the numeric fields, followed by the
50: string fields.
51: ..
52: .SS Default Options
53: If no options are specified and zero or one \fItermnames\fR are specified, the
54: \fB-I\fR option will be assumed. If more than one \fItermname\fR is specified,
55: the \fB-d\fR option will be assumed.
56: ..
57: .SS Comparison Options [-d] [-c] [-n]
58: \fBinfocmp\fR compares the \fBterminfo\fR description of the first terminal
59: \fItermname\fR with each of the descriptions given by the entries for the other
60: terminal's \fItermnames\fR. If a capability is defined for only one of the
61: terminals, the value returned will depend on the type of the capability:
62: \fBF\fR for boolean variables, \fB-1\fR for integer variables, and \fBNULL\fR
63: for string variables.
64:
65: The \fB-d\fR option produces a list of each capability that is different
66: between two entries. This option is useful to show the difference between two
67: entries, created by different people, for the same or similar terminals.
68:
69: The \fB-c\fR option produces a list of each capability that is common between
70: two entries. Capabilities that are not set are ignored. This option can be
71: used as a quick check to see if the \fB-u\fR option is worth using.
72:
73: The \fB-n\fR option produces a list of each capability that is in neither
74: entry. If no \fItermnames\fR are given, the environment variable \fBTERM\fR
75: will be used for both of the \fItermnames\fR. This can be used as a quick
76: check to see if anything was left out of a description.
77: ..
78: .SS Source Listing Options [-I] [-L] [-C] [-r]
79: The \fB-I\fR, \fB-L\fR, and \fB-C\fR options will produce a source listing for
80: each terminal named.
81:
82: .TS
83: center tab(/) ;
84: l l .
85: \fB-I\fR/use the \fBterminfo\fR names
86: \fB-L\fR/use the long C variable name listed in <\fBterm.h\fR>
87: \fB-C\fR/use the \fBtermcap\fR names
88: \fB-r\fR/when using \fB-C\fR, put out all capabilities in \fBtermcap\fR form
89: .TE
90:
91: If no \fItermnames\fR are given, the environment variable \fBTERM\fR will be
92: used for the terminal name.
93:
94: The source produced by the \fB-C\fR option may be used directly as a
95: \fBtermcap\fR entry, but not all parameterized strings can be changed to
96: the \fBtermcap\fR format. \fBinfocmp\fR will attempt to convert most of the
97: parameterized information, and anything not converted will be plainly marked in
98: the output and commented out. These should be edited by hand.
99:
100: All padding information for strings will be collected together and placed
101: at the beginning of the string where \fBtermcap\fR expects it. Mandatory
102: padding (padding information with a trailing '/') will become optional.
103:
104: All \fBtermcap\fR variables no longer supported by \fBterminfo\fR, but which
105: are derivable from other \fBterminfo\fR variables, will be output. Not all
106: \fBterminfo\fR capabilities will be translated; only those variables which were
107: part of \fBtermcap\fR will normally be output. Specifying the \fB-r\fR option
108: will take off this restriction, allowing all capabilities to be output in
109: \fItermcap\fR form.
110:
111: Note that because padding is collected to the beginning of the capability, not
112: all capabilities are output. Mandatory padding is not supported. Because
113: \fBtermcap\fR strings are not as flexible, it is not always possible to convert
114: a \fBterminfo\fR string capability into an equivalent \fBtermcap\fR format. A
115: subsequent conversion of the \fBtermcap\fR file back into \fBterminfo\fR format
116: will not necessarily reproduce the original \fBterminfo\fR
117: source.
118:
119: Some common \fBterminfo\fR parameter sequences, their \fBtermcap\fR
120: equivalents, and some terminal types which commonly have such sequences, are:
121:
122: .TS
123: center tab(/) ;
124: l c l
125: l l l.
126: \fBterminfo/termcap\fR/Representative Terminals
127: =
128: \fB%p1%c/%.\fR/adm
129: \fB%p1%d/%d\fR/hp, ANSI standard, vt100
130: \fB%p1%'x'%+%c/%+x\fR/concept
131: \fB%i/%i\fRq/ANSI standard, vt100
132: \fB%p1%?%'x'%>%t%p1%'y'%+%;/%>xy\fR/concept
133: \fB%p2\fR is printed before \fB%p1/%r\fR/hp
134: .TE
135: .SS Use= Option [-u]
136: The \fB-u\fR option produces a \fBterminfo\fR source description of the first
137: terminal \fItermname\fR which is relative to the sum of the descriptions given
138: by the entries for the other terminals \fItermnames\fR. It does this by
139: analyzing the differences between the first \fItermname\fR and the other
140: \fItermnames\fR and producing a description with \fBuse=\fR fields for the
141: other terminals. In this manner, it is possible to retrofit generic terminfo
142: entries into a terminal's description. Or, if two similar terminals exist, but
143: were coded at different times or by different people so that each description
144: is a full description, using \fBinfocmp\fR will show what can be done to change
145: one description to be relative to the other.
146:
147: A capability will get printed with an at-sign (@) if it no longer exists in the
148: first \fItermname\fR, but one of the other \fItermname\fR entries contains a
149: value for it. A capability's value gets printed if the value in the first
150: \fItermname\fR is not found in any of the other \fItermname\fR entries, or if
151: the first of the other \fItermname\fR entries that has this capability gives a
152: different value for the capability than that in the first \fItermname\fR.
153:
154: The order of the other \fItermname\fR entries is significant. Since the
155: terminfo compiler \fBtic\fR does a left-to-right scan of the capabilities,
156: specifying two \fBuse=\fR entries that contain differing entries for the same
157: capabilities will produce different results depending on the order that the
158: entries are given in. \fBinfocmp\fR will flag any such inconsistencies between
159: the other \fItermname\fR entries as they are found.
160:
161: Alternatively, specifying a capability \fIafter\fR a \fBuse=\fR entry that
162: contains that capability will cause the second specification to be ignored.
163: Using \fBinfocmp\fR to recreate a description can be a useful check to make
164: sure that everything was specified correctly in the original source
165: description.
166:
167: Another error that does not cause incorrect compiled files, but will slow down
168: the compilation time, is specifying extra \fBuse=\fR fields that are
169: superfluous. \fBinfocmp\fR will flag any other \fItermname use=\fR fields that
170: were not needed.
171: ..
172: .SS Changing Databases [-A \fIdirectory\fR] [-B \fIdirectory\fR]
173: The location of the compiled \fBterminfo\fR database is taken from the
174: environment variable \fBTERMINFO\fR . If the variable is not defined, or the
175: terminal is not found in that location, the system \fBterminfo\fR database,
176: in \fB/usr/share/terminfo\fR, will be used. The options \fB-A\fR
177: and \fB-B\fR may be used to override this location. The \fB-A\fR option will
178: set \fBTERMINFO\fR for the first \fItermname\fR and the \fB-B\fR option will
179: set \fBTERMINFO\fR for the other \fItermnames\fR. With this, it is possible to
180: compare descriptions for a terminal with the same name located in two different
181: databases. This is useful for comparing descriptions for the same terminal
182: created by different people.
183: ..
184: .SS Other Options [-s d|i|l|c] [-1FTVefip] [-Rsubset] [-v \fIn\fR] [-w \fIwidth\fR]
185: The \fB-s\fR option sorts the fields within each type according to the argument
186: below:
187: ..
188: .TP 5
189: \fBd\fR
190: leave fields in the order that they are stored in the \fIterminfo\fR database.
191: .TP 5
192: \fBi\fR
193: sort by \fIterminfo\fR name.
194: .TP 5
195: \fBl\fR
196: sort by the long C variable name.
197: .TP 5
198: \fBc\fR
199: sort by the \fItermcap\fR name.
200:
201: If the \fB-s\fR option is not given, the fields printed out will be
202: sorted alphabetically by the \fBterminfo\fR name within each type,
203: except in the case of the \fB-C\fR or the \fB-L\fR options, which cause the
204: sorting to be done by the \fBtermcap\fR name or the long C variable
205: name, respectively.
206: .TP 5
207: \fB-1\fR
208: causes the fields to be printed out one to a line. Otherwise,
209: the fields will be printed several to a line to a maximum width
210: of 60 characters.
211: .TP 5
212: \fB-F\fR
213: compare terminfo files. This assumes that two following arguments are
214: filenames. The files are searched for pairwise matches between
215: entries, with two entries considered to match if any of their names do.
216: The report printed to standard output lists entries with no matches in
217: the other file, and entries with more than one match. For entries
218: with exactly one match it includes a difference report.
1.3 millert 219: .TP
220: \fB-G\fR
221: Display constant literals in decimal form
222: rather than their character equivalents.
1.1 millert 223: .TP 5
224: \fB-R\fR\fIsubset\fR
225: Restrict output to a given subset. This option is for use with archaic
226: versions of terminfo like those on SVr1, Ultrix, or HP/UX that don't support
227: the full set of SVR4/XSI Curses terminfo; and outright broken ports like AIX
228: that have their own extensions incompatible with SVr4/XSI. Available terminfo
229: subsets are "SVr1", "Ultrix", "HP", and "AIX"; see \fBterminfo\fR(\*n) for
230: details. You can also choose the subset "BSD" which selects only capabilities
231: with termcap equivalents recognized by 4.4BSD.
232: .TP 5
233: \fB-T\fR
234: eliminates size-restrictions on the generated text.
235: This is mainly useful for testing and analysis, since the compiled
236: descriptions are limited (e.g., 1023 for termcap, 4096 for terminfo).
237: .TP 5
238: \fB-V\fR
239: prints out the version of the program in use on standard error and exits.
240: .TP 5
241: \fB-e\fR
242: Dump the capabilities of the given terminal as a C initializer for a
243: TERMTYPE structure (the terminal capability structure in the \fB<term.h>\fR).
244: This option is useful for preparing versions of the curses library hardwired
245: for a given terminal type.
1.4 millert 246: .TP 5
247: \fB-E\fR
248: Dump the capabilities of the given terminal as tables, needed in
249: the C initializer for a
250: TERMTYPE structure (the terminal capability structure in the \fB<term.h>\fR).
251: This option is useful for preparing versions of the curses library hardwired
252: for a given terminal type.
253: The tables are all declared static, and are named according to the type
254: and the name of the corresponding terminal entry.
255: .sp
256: Before ncurses 5.0, the split between the \fB\-e\fP and \fB\-E\fP
257: options was not needed; but support for extended names required making
258: the arrays of terminal capabilities separate from the TERMTYPE structure.
1.1 millert 259: .TP
260: \fB-f\fR
261: Display complex terminfo strings which contain if/then/else/endif expressions
262: indented for readability.
263: .TP
264: \fB-g\fR
265: Display constant character literals in quoted form
266: rather than their decimal equivalents.
267: .TP 5
268: \fB-i\fR
269: Analyze the initialization (\fBis1\fR, \fBis2\fR, \fBis3\fR), and reset
270: (\fBrs1\fR, \fBrs2\fR, \fBrs3\fR), strings in the entry. For each string, the
271: code tries to analyze it into actions in terms of the other capabilities in the
272: entry, certain X3.64/ISO 6429/ECMA-48 capabilities, and certain DEC VT-series
273: private modes (the set of recognized special sequences has been selected for
274: completeness over the existing terminfo database). Each report line consists
275: of the capability name, followed by a colon and space, followed by a printable
276: expansion of the capability string with sections matching recognized actions
277: translated into {}-bracketed descriptions. Here is a list of the DEC/ANSI
278: special sequences recognized:
279:
280: .TS
281: center tab(/) ;
282: l l
283: l l.
284: Action/Meaning
285: =
286: RIS/full reset
287: SC/save cursor
288: RC/restore cursor
289: LL/home-down
290: RSR/reset scroll region
291:
292: ISO DEC G0/enable DEC graphics for G0
293: ISO UK G0/enable UK chars for G0
294: ISO US G0/enable US chars for G0
295: ISO DEC G1/enable DEC graphics for G1
296: ISO UK G1/enable UK chars for G1
297: ISO US G1/enable US chars for G1
298:
299: DECPAM/application keypad mode
300: DECPNM/normal keypad mode
301: DECANSI/enter ANSI mode
302:
303: DEC[+-]CKM/application cursor keys
304: DEC[+-]ANM/set VT52 mode
305: DEC[+-]COLM/132-column mode
306: DEC[+-]SCLM/smooth scroll
307: DEC[+-]SCNM/reverse video mode
308: DEC[+-]OM/origin mode
309: DEC[+-]AWM/wraparound mode
310: DEC[+-]ARM/auto-repeat mode
311: .TE
312: .sp
313: It also recognizes a SGR action corresponding to ANSI/ISO 6429/ECMA Set
314: Graphics Rendition, with the values NORMAL, BOLD, UNDERLINE, BLINK, and
315: REVERSE. All but NORMAL may be prefixed with `+' (turn on) or `-' (turn off).
316:
317: An SGR0 designates an empty highlight sequence (equivalent to {SGR:NORMAL}).
318: .TP 5
319: \fB-p\fR
320: Ignore padding specifications when comparing strings.
321: .TP 5
322: \fB-v\fR \fIn\fR
323: prints out tracing information on standard error as the program runs.
324: Higher values of n induce greater verbosity.
325: .TP 5
326: \fB-w\fR \fIwidth\fR
327: changes the output to \fIwidth\fR characters.
328: ..
329: .SH FILES
330: .TP 20
331: \*d
332: Compiled terminal description database.
333: ..
334: .SH EXTENSIONS
335: The
1.4 millert 336: \fB-E\fR,
1.1 millert 337: \fB-F\fR,
1.3 millert 338: \fB-G\fR,
1.1 millert 339: \fB-R\fR,
340: \fB-T\fR,
341: \fB-e\fR,
342: \fB-f\fR,
343: \fB-g\fR,
344: \fB-i\fR, and
345: \fB-p\fR
346: options are not supported in SVr4 curses.
347:
348: The \fB-r\fR option's notion of `termcap' capabilities is System V Release 4's.
349: Actual BSD curses versions will have a more restricted set. To see only the
350: 4.4BSD set, use -r -RBSD.
351: .SH SEE ALSO
1.6 ! millert 352: \fBcaptoinfo\fR(1), \fBinfotocap\fR(1), \fBtic\fR(1),
! 353: \fBcurses\fR(3), \fBterminfo\fR(\*n).
1.1 millert 354: .SH AUTHOR
355: Eric S. Raymond <esr@snark.thyrsus.com>
1.3 millert 356: and
357: Thomas E. Dickey <dickey@clark.net>
1.1 millert 358: .\"#
359: .\"# The following sets edit modes for GNU EMACS
360: .\"# Local Variables:
361: .\"# mode:nroff
362: .\"# fill-column:79
363: .\"# End: