Annotation of src/usr.bin/tic/tic.1, Revision 1.1
1.1 ! millert 1: .\" $OpenBSD$
! 2: .\"
! 3: .\"***************************************************************************
! 4: .\" Copyright (c) 1998 Free Software Foundation, Inc. *
! 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: .\"
! 31: .\" $From: tic.1m,v 1.21 1998/05/17 00:23:46 tom Exp $
! 32: .TH tic 1 ""
! 33: .ds n 5
! 34: .ds d /usr/share/terminfo
! 35: .SH NAME
! 36: \fBtic\fR - the \fIterminfo\fR entry-description compiler
! 37: .SH SYNOPSIS
! 38: \fBtic\fR
! 39: [\fB-\
! 40: 1\
! 41: C\
! 42: I\
! 43: N\
! 44: R\
! 45: T\
! 46: c\
! 47: f\
! 48: r\
! 49: s\
! 50: \fR]
! 51: [\fB-e\fR \fInames\fR]
! 52: [\fB-o\fR \fIdir\fR]
! 53: [\fB-v\fR[\fIn\fR]]
! 54: [\fB-w\fR[\fIn\fR]]
! 55: \fIfile\fR
! 56: .br
! 57: .SH DESCRIPTION
! 58: The command \fBtic\fR translates a \fBterminfo\fR file from source
! 59: format into compiled format. The compiled format is necessary for use with
! 60: the library routines in \fBcurses\fR(3).
! 61: .PP
! 62: The results are normally placed in the system terminfo
! 63: directory \fB\*d\fR. There are two ways to change this behavior.
! 64: .PP
! 65: First, you may override the system default by setting the variable
! 66: \fBTERMINFO\fR in your shell environment to a valid (existing) directory name.
! 67: .PP
! 68: Secondly, if \fBtic\fR cannot get access to \fI\*d\fR or your TERMINFO
! 69: directory, it looks for the directory \fI$HOME/.terminfo\fR; if that directory
! 70: exists, the entry is placed there.
! 71: .PP
! 72: Libraries that read terminfo entries are expected to check for a TERMINFO
! 73: directory first, look at \fI$HOME/.terminfo\fR if TERMINFO is not set, and
! 74: finally look in \fI\*d\fR.
! 75: .TP
! 76: \fB-c\fR
! 77: specifies to only check \fIfile\fR for errors, including syntax problems and
! 78: bad use links. If you specify \fB-C\fR (\fB-I\fR) with this option, the code
! 79: will print warnings about entries which, after use resolution, are more than
! 80: 1023 (4096) bytes long. Due to a fixed buffer length in older termcap
! 81: libraries (and a documented limit in terminfo), these entries may cause core
! 82: dumps.
! 83: .TP
! 84: \fB-v\fR\fIn\fR
! 85: specifies that (verbose) output be written to standard error trace
! 86: information showing \fBtic\fR's progress. The optional integer
! 87: \fIn\fR is a number from 1 to 10, inclusive, indicating the desired
! 88: level of detail of information. If \fIn\fR is omitted, the default
! 89: level is 1. If \fIn\fR is specified and greater than 1, the level of
! 90: detail is increased.
! 91: .TP
! 92: \fB-o\fR\fIdir\fR
! 93: Write compiled entries to given directory. Overrides the TERMINFO environment
! 94: variable.
! 95: .TP
! 96: \fB-w\fR\fIn\fR
! 97: specifies the width of the output.
! 98: .TP
! 99: \fB-1\fR
! 100: restricts the output to a single column
! 101: .TP
! 102: \fB-C\fR
! 103: Force source translation to termcap format. Note: this differs from the -C
! 104: option of \fIinfocmp\fR(1) in that it does not merely translate capability
! 105: names, but also translates terminfo strings to termcap format. Capabilities
! 106: that are not translatable are left in the entry under their terminfo names
! 107: but commented out with two preceding dots.
! 108: .TP
! 109: \fB-I\fR
! 110: Force source translation to terminfo format.
! 111: .TP
! 112: \fB-L\fR
! 113: Force source translation to terminfo format
! 114: using the long C variable names listed in <\fBterm.h\fR>
! 115: .TP
! 116: \fB-N\fR
! 117: Disable smart defaults.
! 118: Normally, when translating from termcap to terminfo, the compiler makes
! 119: a number of assumptions about the defaults of string capabilities
! 120: \fBreset1_string\fR, \fBcarriage_return\fR, \fBcursor_left\fR,
! 121: \fBcursor_down\fR, \fBscroll_forward\fR, \fBtab\fR, \fBnewline\fR,
! 122: \fBkey_backspace\fR, \fBkey_left\fR, and \fBkey_down\fR, then attempts
! 123: to use obsolete termcap capabilities to deduce correct values. It also
! 124: normally suppresses output of obsolete termcap capabilities such as \fBbs\fR.
! 125: This option forces a more literal translation that also preserves the
! 126: obsolete capabilities.
! 127: .TP
! 128: \fB-R\fR\fIsubset\fR
! 129: Restrict output to a given subset. This option is for use with archaic
! 130: versions of terminfo like those on SVr1, Ultrix, or HP/UX that don't support
! 131: the full set of SVR4/XSI Curses terminfo; and outright broken ports like AIX 3.x
! 132: that have their own extensions incompatible with SVr4/XSI. Available subsets
! 133: are "SVr1", "Ultrix", "HP", "BSD" and "AIX"; see \fBterminfo\fR(\*n) for details.
! 134: .TP
! 135: \fB-T\fR
! 136: eliminates size-restrictions on the generated text.
! 137: This is mainly useful for testing and analysis, since the compiled
! 138: descriptions are limited (e.g., 1023 for termcap, 4096 for terminfo).
! 139: .TP
! 140: \fB-r\fR
! 141: Force entry resolution (so there are no remaining tc capabilities) even
! 142: when doing translation to termcap format. This may be needed if you are
! 143: preparing a termcap file for a termcap library (such as GNU termcap up
! 144: to version 1.3 or BSD termcap up to 4.3BSD) that doesn't handle multiple
! 145: tc capabilities per entry.
! 146: .TP
! 147: \fB-e\fR
! 148: Limit writes and translations to the following comma-separated list of
! 149: terminals.
! 150: If any name or alias of a terminal matches one of the names in
! 151: the list, the entry will be written or translated as normal.
! 152: Otherwise no output will be generated for it.
! 153: The option value is interpreted as a file containing the list if it
! 154: contains a '/'.
! 155: (Note: depending on how tic was compiled, this option may require -I or -C.)
! 156: .TP
! 157: \fB-f\fR
! 158: Display complex terminfo strings which contain if/then/else/endif expressions
! 159: indented for readability.
! 160: .TP
! 161: \fB-s\fR
! 162: Summarize the compile by showing the directory into which entries
! 163: are written, and the number of entries which are compiled.
! 164: .TP
! 165: \fIfile\fR
! 166: contains one or more \fBterminfo\fR terminal descriptions in source
! 167: format [see \fBterminfo\fR(\*n)]. Each description in the file
! 168: describes the capabilities of a particular terminal.
! 169: .PP
! 170: The debug flag levels are as follows:
! 171: .TP
! 172: 1
! 173: Names of files created and linked
! 174: .TP
! 175: 2
! 176: Information related to the ``use'' facility
! 177: .TP
! 178: 3
! 179: Statistics from the hashing algorithm
! 180: .TP
! 181: 5
! 182: String-table memory allocations
! 183: .TP
! 184: 7
! 185: Entries into the string-table
! 186: .TP
! 187: 8
! 188: List of tokens encountered by scanner
! 189: .TP
! 190: 9
! 191: All values computed in construction of the hash table
! 192: .LP
! 193: If n is not given, it is taken to be one.
! 194: .PP
! 195: All but one of the capabilities recognized by \fBtic\fR are documented
! 196: in \fBterminfo\fR(\*n). The exception is the \fBuse\fR capability.
! 197:
! 198: When a \fBuse\fR=\fIentry\fR-\fIname\fR field is discovered in a
! 199: terminal entry currently being compiled, \fBtic\fR reads in the binary
! 200: from \fB\*d\fR to complete the entry. (Entries created from
! 201: \fIfile\fR will be used first. If the environment variable
! 202: \fBTERMINFO\fR is set, that directory is searched instead of
! 203: \fB\*d\fR.) \fBtic\fR duplicates the capabilities in
! 204: \fIentry\fR-\fIname\fR for the current entry, with the exception of
! 205: those capabilities that explicitly are defined in the current entry.
! 206:
! 207: When an entry, e.g., \fBentry_name_1\fR, contains a
! 208: \fBuse=\fR\fIentry\fR_\fIname\fR_\fI2\fR field, any canceled
! 209: capabilities in \fIentry\fR_\fIname\fR_\fI2\fR must also appear in
! 210: \fBentry_name_1\fR before \fBuse=\fR for these capabilities to be
! 211: canceled in \fBentry_name_1\fR.
! 212:
! 213: If the environment variable \fBTERMINFO\fR is set, the compiled
! 214: results are placed there instead of \fB\*d\fR.
! 215:
! 216: Total compiled entries cannot exceed 4096 bytes. The name field cannot
! 217: exceed 512 bytes. Terminal names exceeding the maximum alias length
! 218: (32 characters on systems with long filenames, 14 characters otherwise)
! 219: will be truncated to the maximum alias length and a warning message will be printed.
! 220: .SH COMPATIBILITY
! 221: There is some evidence that historic \fBtic\fR implementations treated
! 222: description fields with no whitespace in them as additional aliases or
! 223: short names. This \fBtic\fR does not do that, but it does warn when
! 224: description fields may be treated that way and check them for dangerous
! 225: characters.
! 226: .SH EXTENSIONS
! 227: Unlike the stock SVr4 \fBtic\fR command, this implementation can actually
! 228: compile termcap sources. In fact, entries in terminfo and termcap syntax can
! 229: be mixed in a single source file. See \fBterminfo\fR(\*n) for the list of
! 230: termcap names taken to be equivalent to terminfo names.
! 231:
! 232: The SVr4 manual pages are not clear on the resolution rules for \fBuse\fR
! 233: capabilities.
! 234: This implementation of \fBtic\fR will find \fBuse\fR targets anywhere
! 235: in the source file, or anywhere in the file tree rooted at \fBTERMINFO\fR (if
! 236: \fBTERMINFO\fR is defined), or in the user's \fI$HOME/.terminfo\fR directory
! 237: (if it exists), or (finally) anywhere in the system's file tree of
! 238: compiled entries.
! 239:
! 240: The error messages from this \fBtic\fR have the same format as GNU C
! 241: error messages, and can be parsed by GNU Emacs's compile facility.
! 242:
! 243: The -o, -I, -C, -N, -R, -e, -f, -T, -r and -s options
! 244: are not supported under SVr4.
! 245: The SVr4 -c mode does not report bad use links.
! 246:
! 247: System V does not compile entries to or read entries from your
! 248: \fI$HOME/.terminfo\fR directory unless TERMINFO is explicitly set to it.
! 249: .SH FILES
! 250: .TP 5
! 251: \fB\*d/?/*\fR
! 252: Compiled terminal description database.
! 253: .SH SEE ALSO
! 254: \fBinfocmp\fR(1), \fBcaptoinfo\fR(1), \fBtoe\fR(1),
! 255: \fBcurses\fR(3), \fBterminfo\fR(\*n).
! 256: .\"#
! 257: .\"# The following sets edit modes for GNU EMACS
! 258: .\"# Local Variables:
! 259: .\"# mode:nroff
! 260: .\"# fill-column:79
! 261: .\"# End: