Annotation of src/usr.bin/tic/tic.1, Revision 1.16
1.16 ! nicm 1: .\" $OpenBSD: tic.1,v 1.15 2010/09/02 09:00:01 sobrado Exp $
1.1 millert 2: .\"
3: .\"***************************************************************************
1.14 nicm 4: .\" Copyright (c) 1998-2005,2006 Free Software Foundation, Inc. *
1.1 millert 5: .\" *
6: .\" Permission is hereby granted, free of charge, to any person obtaining a *
7: .\" copy of this software and associated documentation files (the *
8: .\" "Software"), to deal in the Software without restriction, including *
9: .\" without limitation the rights to use, copy, modify, merge, publish, *
10: .\" distribute, distribute with modifications, sublicense, and/or sell *
11: .\" copies of the Software, and to permit persons to whom the Software is *
12: .\" furnished to do so, subject to the following conditions: *
13: .\" *
14: .\" The above copyright notice and this permission notice shall be included *
15: .\" in all copies or substantial portions of the Software. *
16: .\" *
17: .\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS *
18: .\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF *
19: .\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. *
20: .\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, *
21: .\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR *
22: .\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR *
23: .\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. *
24: .\" *
25: .\" Except as contained in this notice, the name(s) of the above copyright *
26: .\" holders shall not be used in advertising or otherwise to promote the *
27: .\" sale, use or other dealings in this Software without prior written *
28: .\" authorization. *
29: .\"***************************************************************************
30: .\"
1.16 ! nicm 31: .\" $Id: tic.1,v 1.15 2010/09/02 09:00:01 sobrado Exp $
1.1 millert 32: .TH tic 1 ""
33: .ds n 5
1.16 ! nicm 34: .ds d /usr/share/terminfo
1.1 millert 35: .SH NAME
36: \fBtic\fR - the \fIterminfo\fR entry-description compiler
37: .SH SYNOPSIS
38: \fBtic\fR
1.14 nicm 39: [\fB-\
1.1 millert 40: 1\
41: C\
1.14 nicm 42: G\
1.1 millert 43: I\
1.14 nicm 44: L\
1.1 millert 45: N\
46: T\
1.14 nicm 47: U\
1.12 millert 48: V\
1.10 millert 49: a\
1.1 millert 50: c\
51: f\
1.14 nicm 52: g\
1.1 millert 53: r\
54: s\
1.14 nicm 55: t\
1.9 millert 56: x\
1.1 millert 57: \fR]
58: [\fB-e\fR \fInames\fR]
59: [\fB-o\fR \fIdir\fR]
1.14 nicm 60: [\fB-R\fR \fIsubset\fR]
1.1 millert 61: [\fB-v\fR[\fIn\fR]]
62: [\fB-w\fR[\fIn\fR]]
63: \fIfile\fR
64: .br
65: .SH DESCRIPTION
66: The command \fBtic\fR translates a \fBterminfo\fR file from source
67: format into compiled format. The compiled format is necessary for use with
1.14 nicm 68: the library routines in \fBncurses\fR(3X).
1.1 millert 69: .PP
70: The results are normally placed in the system terminfo
71: directory \fB\*d\fR. There are two ways to change this behavior.
72: .PP
73: First, you may override the system default by setting the variable
74: \fBTERMINFO\fR in your shell environment to a valid (existing) directory name.
75: .PP
76: Secondly, if \fBtic\fR cannot get access to \fI\*d\fR or your TERMINFO
77: directory, it looks for the directory \fI$HOME/.terminfo\fR; if that directory
78: exists, the entry is placed there.
79: .PP
80: Libraries that read terminfo entries are expected to check for a TERMINFO
81: directory first, look at \fI$HOME/.terminfo\fR if TERMINFO is not set, and
82: finally look in \fI\*d\fR.
83: .TP
1.14 nicm 84: \fB-1\fR
85: restricts the output to a single column
86: .TP
1.10 millert 87: \fB-a\fR
88: tells \fBtic\fP to retain commented-out capabilities rather than discarding
89: them. Capabilities are commented by prefixing them with a period.
90: This sets the \fB-x\fR option, because it treats the commented-out
91: entries as user-defined names.
1.14 nicm 92: If the source is termcap, accept the 2-character names required by version 6.
93: Otherwise these are ignored.
94: .TP
95: \fB-C\fR
96: Force source translation to termcap format. Note: this differs from the \fB-C\fR
97: option of \fBinfocmp\fR(1M) in that it does not merely translate capability
98: names, but also translates terminfo strings to termcap format. Capabilities
99: that are not translatable are left in the entry under their terminfo names
100: but commented out with two preceding dots.
1.10 millert 101: .TP
1.1 millert 102: \fB-c\fR
1.10 millert 103: tells \fBtic\fP to only check \fIfile\fR for errors, including syntax problems and
1.1 millert 104: bad use links. If you specify \fB-C\fR (\fB-I\fR) with this option, the code
105: will print warnings about entries which, after use resolution, are more than
106: 1023 (4096) bytes long. Due to a fixed buffer length in older termcap
107: libraries (and a documented limit in terminfo), these entries may cause core
108: dumps.
109: .TP
1.14 nicm 110: \fB-e \fR\fInames\fR
111: Limit writes and translations to the following comma-separated list of
112: terminals.
113: If any name or alias of a terminal matches one of the names in
114: the list, the entry will be written or translated as normal.
115: Otherwise no output will be generated for it.
116: The option value is interpreted as a file containing the list if it
117: contains a '/'.
118: (Note: depending on how tic was compiled, this option may require \fB-I\fR or \fB-C\fR.)
1.1 millert 119: .TP
1.14 nicm 120: \fB-f\fR
121: Display complex terminfo strings which contain if/then/else/endif expressions
122: indented for readability.
1.1 millert 123: .TP
1.6 millert 124: \fB-G\fR
125: Display constant literals in decimal form
126: rather than their character equivalents.
127: .TP
1.14 nicm 128: \fB-g\fR
129: Display constant character literals in quoted form
130: rather than their decimal equivalents.
131: .TP
1.1 millert 132: \fB-I\fR
133: Force source translation to terminfo format.
134: .TP
135: \fB-L\fR
136: Force source translation to terminfo format
137: using the long C variable names listed in <\fBterm.h\fR>
138: .TP
139: \fB-N\fR
1.15 sobrado 140: Disable smart defaults.
1.7 aaron 141: Normally, when translating from termcap to terminfo, the compiler makes
1.1 millert 142: a number of assumptions about the defaults of string capabilities
1.7 aaron 143: \fBreset1_string\fR, \fBcarriage_return\fR, \fBcursor_left\fR,
1.1 millert 144: \fBcursor_down\fR, \fBscroll_forward\fR, \fBtab\fR, \fBnewline\fR,
145: \fBkey_backspace\fR, \fBkey_left\fR, and \fBkey_down\fR, then attempts
146: to use obsolete termcap capabilities to deduce correct values. It also
147: normally suppresses output of obsolete termcap capabilities such as \fBbs\fR.
148: This option forces a more literal translation that also preserves the
149: obsolete capabilities.
150: .TP
1.14 nicm 151: \fB-o\fR\fIdir\fR
152: Write compiled entries to given directory. Overrides the TERMINFO environment
153: variable.
154: .TP
1.1 millert 155: \fB-R\fR\fIsubset\fR
156: Restrict output to a given subset. This option is for use with archaic
1.14 nicm 157: versions of terminfo like those on SVr1, Ultrix, or HP-UX that do not support
1.1 millert 158: the full set of SVR4/XSI Curses terminfo; and outright broken ports like AIX 3.x
159: that have their own extensions incompatible with SVr4/XSI. Available subsets
160: are "SVr1", "Ultrix", "HP", "BSD" and "AIX"; see \fBterminfo\fR(\*n) for details.
161: .TP
1.14 nicm 162: \fB-r\fR
163: Force entry resolution (so there are no remaining tc capabilities) even
164: when doing translation to termcap format. This may be needed if you are
165: preparing a termcap file for a termcap library (such as GNU termcap through
166: version 1.3 or BSD termcap through 4.3BSD) that does not handle multiple
167: tc capabilities per entry.
168: .TP
169: \fB-s\fR
170: Summarize the compile by showing the directory into which entries
171: are written, and the number of entries which are compiled.
172: .TP
1.1 millert 173: \fB-T\fR
174: eliminates size-restrictions on the generated text.
175: This is mainly useful for testing and analysis, since the compiled
176: descriptions are limited (e.g., 1023 for termcap, 4096 for terminfo).
177: .TP
1.14 nicm 178: \fB-t\fR
179: tells \fBtic\fP to discard commented-out capabilities.
180: Normally when translating from terminfo to termcap,
181: untranslatable capabilities are commented-out.
182: .TP 5
183: \fB-U\fR
184: tells \fBtic\fP to not post-process the data after parsing the source file.
185: Normally, it infers data which is commonly missing in older terminfo data,
186: or in termcaps.
187: .TP
1.12 millert 188: \fB-V\fR
189: reports the version of ncurses which was used in this program, and exits.
190: .TP
1.14 nicm 191: \fB-v\fR\fIn\fR
192: specifies that (verbose) output be written to standard error trace
193: information showing \fBtic\fR's progress.
194: The optional parameter \fIn\fR is a number from 1 to 10, inclusive,
195: indicating the desired level of detail of information.
196: If \fIn\fR is omitted, the default level is 1.
197: If \fIn\fR is specified and greater than 1, the level of
198: detail is increased.
1.1 millert 199: .TP
1.14 nicm 200: \fB-w\fR\fIn\fR
201: specifies the width of the output.
202: The parameter is optional.
203: If it is omitted, it defaults to 60.
1.1 millert 204: .TP
1.9 millert 205: \fB-x\fR
206: Treat unknown capabilities as user-defined.
1.10 millert 207: That is, if you supply a capability name which \fBtic\fP does not recognize,
208: it will infer its type (boolean, number or string) from the syntax and
209: make an extended table entry for that.
1.14 nicm 210: User-defined capability strings
211: whose name begins with ``k'' are treated as function keys.
1.9 millert 212: .TP
1.1 millert 213: \fIfile\fR
214: contains one or more \fBterminfo\fR terminal descriptions in source
215: format [see \fBterminfo\fR(\*n)]. Each description in the file
216: describes the capabilities of a particular terminal.
217: .PP
218: The debug flag levels are as follows:
219: .TP
220: 1
221: Names of files created and linked
222: .TP
223: 2
224: Information related to the ``use'' facility
225: .TP
226: 3
227: Statistics from the hashing algorithm
228: .TP
229: 5
230: String-table memory allocations
231: .TP
232: 7
233: Entries into the string-table
234: .TP
235: 8
236: List of tokens encountered by scanner
237: .TP
238: 9
239: All values computed in construction of the hash table
240: .LP
1.14 nicm 241: If the debug level \fIn\fR is not given, it is taken to be one.
1.1 millert 242: .PP
243: All but one of the capabilities recognized by \fBtic\fR are documented
244: in \fBterminfo\fR(\*n). The exception is the \fBuse\fR capability.
1.14 nicm 245: .PP
1.1 millert 246: When a \fBuse\fR=\fIentry\fR-\fIname\fR field is discovered in a
247: terminal entry currently being compiled, \fBtic\fR reads in the binary
248: from \fB\*d\fR to complete the entry. (Entries created from
249: \fIfile\fR will be used first. If the environment variable
250: \fBTERMINFO\fR is set, that directory is searched instead of
251: \fB\*d\fR.) \fBtic\fR duplicates the capabilities in
252: \fIentry\fR-\fIname\fR for the current entry, with the exception of
253: those capabilities that explicitly are defined in the current entry.
1.14 nicm 254: .PP
1.1 millert 255: When an entry, e.g., \fBentry_name_1\fR, contains a
256: \fBuse=\fR\fIentry\fR_\fIname\fR_\fI2\fR field, any canceled
257: capabilities in \fIentry\fR_\fIname\fR_\fI2\fR must also appear in
258: \fBentry_name_1\fR before \fBuse=\fR for these capabilities to be
259: canceled in \fBentry_name_1\fR.
1.14 nicm 260: .PP
1.1 millert 261: If the environment variable \fBTERMINFO\fR is set, the compiled
262: results are placed there instead of \fB\*d\fR.
1.14 nicm 263: .PP
1.1 millert 264: Total compiled entries cannot exceed 4096 bytes. The name field cannot
265: exceed 512 bytes. Terminal names exceeding the maximum alias length
266: (32 characters on systems with long filenames, 14 characters otherwise)
267: will be truncated to the maximum alias length and a warning message will be printed.
268: .SH COMPATIBILITY
269: There is some evidence that historic \fBtic\fR implementations treated
270: description fields with no whitespace in them as additional aliases or
271: short names. This \fBtic\fR does not do that, but it does warn when
272: description fields may be treated that way and check them for dangerous
273: characters.
274: .SH EXTENSIONS
275: Unlike the stock SVr4 \fBtic\fR command, this implementation can actually
276: compile termcap sources. In fact, entries in terminfo and termcap syntax can
277: be mixed in a single source file. See \fBterminfo\fR(\*n) for the list of
278: termcap names taken to be equivalent to terminfo names.
1.14 nicm 279: .PP
1.1 millert 280: The SVr4 manual pages are not clear on the resolution rules for \fBuse\fR
281: capabilities.
282: This implementation of \fBtic\fR will find \fBuse\fR targets anywhere
283: in the source file, or anywhere in the file tree rooted at \fBTERMINFO\fR (if
284: \fBTERMINFO\fR is defined), or in the user's \fI$HOME/.terminfo\fR directory
285: (if it exists), or (finally) anywhere in the system's file tree of
286: compiled entries.
1.14 nicm 287: .PP
1.1 millert 288: The error messages from this \fBtic\fR have the same format as GNU C
289: error messages, and can be parsed by GNU Emacs's compile facility.
1.14 nicm 290: .PP
1.3 millert 291: The
1.10 millert 292: \fB-C\fR,
1.6 millert 293: \fB-G\fR,
1.3 millert 294: \fB-I\fR,
295: \fB-N\fR,
296: \fB-R\fR,
1.10 millert 297: \fB-T\fR,
1.12 millert 298: \fB-V\fR,
1.10 millert 299: \fB-a\fR,
1.3 millert 300: \fB-e\fR,
301: \fB-f\fR,
302: \fB-g\fR,
1.10 millert 303: \fB-o\fR,
1.9 millert 304: \fB-r\fR,
1.14 nicm 305: \fB-s\fR,
306: \fB-t\fR and
1.9 millert 307: \fB-x\fR
1.3 millert 308: options
1.1 millert 309: are not supported under SVr4.
1.14 nicm 310: The SVr4 \fB-c\fR mode does not report bad use links.
311: .PP
1.1 millert 312: System V does not compile entries to or read entries from your
313: \fI$HOME/.terminfo\fR directory unless TERMINFO is explicitly set to it.
314: .SH FILES
315: .TP 5
316: \fB\*d/?/*\fR
317: Compiled terminal description database.
318: .SH SEE ALSO
1.14 nicm 319: \fBinfocmp\fR(1),
320: \fBcaptoinfo\fR(1),
321: \fBinfotocap\fR(1),
322: \fBcurses\fR(3),
323: \fBterminfo\fR(\*n).
324: .PP
325: This describes \fBncurses\fR
326: version 5.7.
1.1 millert 327: .\"#
328: .\"# The following sets edit modes for GNU EMACS
329: .\"# Local Variables:
330: .\"# mode:nroff
331: .\"# fill-column:79
332: .\"# End:
![[BACK]](/icons/back.gif){kind=icon}
Return to tic.1 CVS log ![[TXT]](/icons/text.gif){kind=icon}
![[DIR]](/icons/dir.gif){kind=icon}
Up to [local] / src / usr.bin / tic