Annotation of src/usr.bin/infocmp/infocmp.1tbl, Revision 1.7
1.1 millert 1: '\" t
1.7 ! millert 2: .\" $OpenBSD: infocmp.1tbl,v 1.6 2000/01/08 06:26:24 millert Exp $
1.1 millert 3: .\"
4: .\"***************************************************************************
1.7 ! millert 5: .\" Copyright (c) 1998,2000 Free Software Foundation, Inc. *
1.1 millert 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.7 ! millert 32: .\" $From: infocmp.1m,v 1.23 2000/03/12 02:52:56 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.7 ! millert 39: \fBinfocmp\fR [\fB-dceEGgnpqrILCuV1\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
1.7 ! millert 218: with exactly one match it includes a difference report. Normally,
! 219: to reduce the volume of the report, use references are
! 220: not resolved before looking for differences, but resolution can be forced
! 221: by also specifying \fB-r\fR.
1.3 millert 222: .TP
223: \fB-G\fR
224: Display constant literals in decimal form
225: rather than their character equivalents.
1.1 millert 226: .TP 5
1.7 ! millert 227: \fB-q\fR
! 228: Make the comparison listing shorter by omitting subheadings, and using
! 229: "-" for absent capabilities, "@" for cancelled rather than "NULL".
! 230: .TP 5
1.1 millert 231: \fB-R\fR\fIsubset\fR
232: Restrict output to a given subset. This option is for use with archaic
233: versions of terminfo like those on SVr1, Ultrix, or HP/UX that don't support
234: the full set of SVR4/XSI Curses terminfo; and outright broken ports like AIX
235: that have their own extensions incompatible with SVr4/XSI. Available terminfo
236: subsets are "SVr1", "Ultrix", "HP", and "AIX"; see \fBterminfo\fR(\*n) for
237: details. You can also choose the subset "BSD" which selects only capabilities
238: with termcap equivalents recognized by 4.4BSD.
239: .TP 5
240: \fB-T\fR
241: eliminates size-restrictions on the generated text.
242: This is mainly useful for testing and analysis, since the compiled
243: descriptions are limited (e.g., 1023 for termcap, 4096 for terminfo).
244: .TP 5
245: \fB-V\fR
246: prints out the version of the program in use on standard error and exits.
247: .TP 5
248: \fB-e\fR
249: Dump the capabilities of the given terminal as a 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.
1.4 millert 253: .TP 5
254: \fB-E\fR
255: Dump the capabilities of the given terminal as tables, needed in
256: the C initializer for a
257: TERMTYPE structure (the terminal capability structure in the \fB<term.h>\fR).
258: This option is useful for preparing versions of the curses library hardwired
259: for a given terminal type.
260: The tables are all declared static, and are named according to the type
261: and the name of the corresponding terminal entry.
262: .sp
263: Before ncurses 5.0, the split between the \fB\-e\fP and \fB\-E\fP
264: options was not needed; but support for extended names required making
265: the arrays of terminal capabilities separate from the TERMTYPE structure.
1.1 millert 266: .TP
267: \fB-f\fR
268: Display complex terminfo strings which contain if/then/else/endif expressions
269: indented for readability.
270: .TP
271: \fB-g\fR
272: Display constant character literals in quoted form
273: rather than their decimal equivalents.
274: .TP 5
275: \fB-i\fR
276: Analyze the initialization (\fBis1\fR, \fBis2\fR, \fBis3\fR), and reset
277: (\fBrs1\fR, \fBrs2\fR, \fBrs3\fR), strings in the entry. For each string, the
278: code tries to analyze it into actions in terms of the other capabilities in the
279: entry, certain X3.64/ISO 6429/ECMA-48 capabilities, and certain DEC VT-series
280: private modes (the set of recognized special sequences has been selected for
281: completeness over the existing terminfo database). Each report line consists
282: of the capability name, followed by a colon and space, followed by a printable
283: expansion of the capability string with sections matching recognized actions
284: translated into {}-bracketed descriptions. Here is a list of the DEC/ANSI
285: special sequences recognized:
286:
287: .TS
288: center tab(/) ;
289: l l
290: l l.
291: Action/Meaning
292: =
293: RIS/full reset
294: SC/save cursor
295: RC/restore cursor
296: LL/home-down
297: RSR/reset scroll region
298:
299: ISO DEC G0/enable DEC graphics for G0
300: ISO UK G0/enable UK chars for G0
301: ISO US G0/enable US chars for G0
302: ISO DEC G1/enable DEC graphics for G1
303: ISO UK G1/enable UK chars for G1
304: ISO US G1/enable US chars for G1
305:
306: DECPAM/application keypad mode
307: DECPNM/normal keypad mode
308: DECANSI/enter ANSI mode
309:
310: DEC[+-]CKM/application cursor keys
311: DEC[+-]ANM/set VT52 mode
312: DEC[+-]COLM/132-column mode
313: DEC[+-]SCLM/smooth scroll
314: DEC[+-]SCNM/reverse video mode
315: DEC[+-]OM/origin mode
316: DEC[+-]AWM/wraparound mode
317: DEC[+-]ARM/auto-repeat mode
318: .TE
319: .sp
320: It also recognizes a SGR action corresponding to ANSI/ISO 6429/ECMA Set
321: Graphics Rendition, with the values NORMAL, BOLD, UNDERLINE, BLINK, and
322: REVERSE. All but NORMAL may be prefixed with `+' (turn on) or `-' (turn off).
323:
324: An SGR0 designates an empty highlight sequence (equivalent to {SGR:NORMAL}).
325: .TP 5
326: \fB-p\fR
327: Ignore padding specifications when comparing strings.
328: .TP 5
329: \fB-v\fR \fIn\fR
330: prints out tracing information on standard error as the program runs.
331: Higher values of n induce greater verbosity.
332: .TP 5
333: \fB-w\fR \fIwidth\fR
334: changes the output to \fIwidth\fR characters.
335: ..
336: .SH FILES
337: .TP 20
338: \*d
339: Compiled terminal description database.
340: ..
341: .SH EXTENSIONS
342: The
1.4 millert 343: \fB-E\fR,
1.1 millert 344: \fB-F\fR,
1.3 millert 345: \fB-G\fR,
1.1 millert 346: \fB-R\fR,
347: \fB-T\fR,
348: \fB-e\fR,
349: \fB-f\fR,
350: \fB-g\fR,
1.7 ! millert 351: \fB-i\fR,
! 352: \fB-p\fR, and
! 353: \fB-q\fR
1.1 millert 354: options are not supported in SVr4 curses.
355:
356: The \fB-r\fR option's notion of `termcap' capabilities is System V Release 4's.
357: Actual BSD curses versions will have a more restricted set. To see only the
358: 4.4BSD set, use -r -RBSD.
359: .SH SEE ALSO
1.6 millert 360: \fBcaptoinfo\fR(1), \fBinfotocap\fR(1), \fBtic\fR(1),
361: \fBcurses\fR(3), \fBterminfo\fR(\*n).
1.1 millert 362: .SH AUTHOR
363: Eric S. Raymond <esr@snark.thyrsus.com>
1.3 millert 364: and
365: Thomas E. Dickey <dickey@clark.net>
1.1 millert 366: .\"#
367: .\"# The following sets edit modes for GNU EMACS
368: .\"# Local Variables:
369: .\"# mode:nroff
370: .\"# fill-column:79
371: .\"# End: