X-Git-Url: https://ncurses.scripts.mit.edu/?p=ncurses.git;a=blobdiff_plain;f=man%2Ftic.1m;h=5295b39049ecb13d92a0bcfbe5871dd8396c7564;hp=e3a095453d3ca422ecadcd69acb02fb033bcf580;hb=51a395aaa20e4aa687310bb8cb1616ccf8e8fd0d;hpb=c633e5103a29a38532cf1925257b91cea33fd090;ds=inline diff --git a/man/tic.1m b/man/tic.1m index e3a09545..5295b390 100644 --- a/man/tic.1m +++ b/man/tic.1m @@ -1,5 +1,5 @@ .\"*************************************************************************** -.\" Copyright (c) 1998,1999,2000 Free Software Foundation, Inc. * +.\" Copyright (c) 1998-2018,2019 Free Software Foundation, Inc. * .\" * .\" Permission is hereby granted, free of charge, to any person obtaining a * .\" copy of this software and associated documentation files (the * @@ -26,170 +26,298 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: tic.1m,v 1.29 2000/08/19 18:51:05 tom Exp $ -.TH tic 1M "" +.\" $Id: tic.1m,v 1.69 2019/05/18 22:48:40 tom Exp $ +.TH @TIC@ 1M "" +.ie \n(.g .ds `` \(lq +.el .ds `` `` +.ie \n(.g .ds '' \(rq +.el .ds '' '' .ds n 5 .ds d @TERMINFO@ +.de bP +.ie n .IP \(bu 4 +.el .IP \(bu 2 +.. .SH NAME -\fBtic\fR - the \fIterminfo\fR entry-description compiler +\fB@TIC@\fR \- the \fIterminfo\fR entry-description compiler .SH SYNOPSIS -\fBtic\fR +\fB@TIC@\fR [\fB\-\ +0\ 1\ C\ +D\ +G\ I\ +K\ +L\ N\ -R\ T\ +U\ V\ +W\ a\ c\ f\ +g\ +q\ r\ s\ +t\ x\ \fR] -[\fB-e\fR \fInames\fR] -[\fB-o\fR \fIdir\fR] -[\fB-v\fR[\fIn\fR]] -[\fB-w\fR[\fIn\fR]] +[\fB\-e\fR \fInames\fR] +[\fB\-o\fR \fIdir\fR] +[\fB\-Q\fR[\fIn\fR]] +[\fB\-R\fR \fIsubset\fR] +[\fB\-v\fR[\fIn\fR]] +[\fB\-w\fR[\fIn\fR]] \fIfile\fR .br .SH DESCRIPTION -The command \fBtic\fR translates a \fBterminfo\fR file from source -format into compiled format. The compiled format is necessary for use with +The \fB@TIC@\fR command translates a \fBterminfo\fR file from source +format into compiled format. +The compiled format is necessary for use with the library routines in \fBncurses\fR(3X). .PP -The results are normally placed in the system terminfo -directory \fB\*d\fR. There are two ways to change this behavior. +As described in \fBterm\fR(\*n), the database may be either a directory +tree (one file per terminal entry) or a hashed database (one record per entry). +The \fB@TIC@\fR command writes only one type of entry, +depending on how it was built: +.bP +For directory trees, the top-level directory, e.g., /usr/share/terminfo, +specifies the location of the database. +.bP +For hashed databases, a filename is needed. +If the given file is not found by that name, +but can be found by adding the suffix ".db", +then that is used. +.IP +The default name for the hashed database is the same as the +default directory name (only adding a ".db" suffix). .PP -First, you may override the system default by setting the variable -\fBTERMINFO\fR in your shell environment to a valid (existing) directory name. +In either case (directory or hashed database), +\fB@TIC@\fP will create the container if it does not exist. +For a directory, this would be the "terminfo" leaf, +versus a "terminfo.db" file. .PP -Secondly, if \fBtic\fR cannot get access to \fI\*d\fR or your TERMINFO -directory, it looks for the directory \fI$HOME/.terminfo\fR; if that directory -exists, the entry is placed there. +The results are normally placed in the system terminfo database \fB\*d\fR. +The compiled terminal description can be placed +in a different terminfo database. +There are two ways to achieve this: +.bP +First, you may override the system default either by +using the \fB\-o\fP option, +or by setting the variable \fBTERMINFO\fR +in your shell environment to a valid database location. +.bP +Secondly, if \fB@TIC@\fR cannot write in \fI\*d\fR +or the location specified using your TERMINFO variable, +it looks for the directory \fI$HOME/.terminfo\fR +(or hashed database \fI$HOME/.terminfo.db)\fR; +if that location exists, the entry is placed there. .PP -Libraries that read terminfo entries are expected to check for a TERMINFO -directory first, look at \fI$HOME/.terminfo\fR if TERMINFO is not set, and -finally look in \fI\*d\fR. -.TP -\fB-a\fR -tells \fBtic\fP to retain commented-out capabilities rather than discarding -them. Capabilities are commented by prefixing them with a period. -This sets the \fB-x\fR option, because it treats the commented-out -entries as user-defined names. -.TP -\fB-c\fR -tells \fBtic\fP to only check \fIfile\fR for errors, including syntax problems and -bad use links. If you specify \fB-C\fR (\fB-I\fR) with this option, the code -will print warnings about entries which, after use resolution, are more than -1023 (4096) bytes long. Due to a fixed buffer length in older termcap -libraries (and a documented limit in terminfo), these entries may cause core -dumps. -.TP -\fB-v\fR\fIn\fR -specifies that (verbose) output be written to standard error trace -information showing \fBtic\fR's progress. The optional integer -\fIn\fR is a number from 1 to 10, inclusive, indicating the desired -level of detail of information. If \fIn\fR is omitted, the default -level is 1. If \fIn\fR is specified and greater than 1, the level of -detail is increased. +Libraries that read terminfo entries are expected to check in succession +.bP +a location specified with the TERMINFO environment variable, +.bP +\fI$HOME/.terminfo\fR, +.bP +directories listed in the TERMINFO_DIRS environment variable, +.bP +a compiled-in list of directories (@TERMINFO_DIRS@), and +.bP +the system terminfo database (\fI\*d\fR). +.SS OPTIONS .TP -\fB-o\fR\fIdir\fR -Write compiled entries to given directory. Overrides the TERMINFO environment -variable. +\fB\-0\fR +restricts the output to a single line .TP -\fB-w\fR\fIn\fR -specifies the width of the output. -.TP -\fB-1\fR +\fB\-1\fR restricts the output to a single column .TP -\fB-C\fR -Force source translation to termcap format. Note: this differs from the -C -option of \fIinfocmp\fR(1M) in that it does not merely translate capability -names, but also translates terminfo strings to termcap format. Capabilities +\fB\-a\fR +tells \fB@TIC@\fP to retain commented-out capabilities rather than discarding +them. +Capabilities are commented by prefixing them with a period. +This sets the \fB\-x\fR option, because it treats the commented-out +entries as user-defined names. +If the source is termcap, accept the 2-character names required by version 6. +Otherwise these are ignored. +.TP +\fB\-C\fR +Force source translation to termcap format. +Note: this differs from the \fB\-C\fR +option of \fB@INFOCMP@\fR(1M) in that it does not merely translate capability +names, but also translates terminfo strings to termcap format. +Capabilities that are not translatable are left in the entry under their terminfo names but commented out with two preceding dots. +The actual format used incorporates some improvements for escaped characters +from terminfo format. +For a stricter BSD-compatible translation, add the \fB\-K\fR option. +.IP +If this is combined with \fB\-c\fR, \fB@TIC@\fR makes additional checks +to report cases where the terminfo values do not have an exact equivalent +in termcap form. +For example: +.RS +.bP +\fBsgr\fP usually will not convert, because termcap lacks the ability to +work with more than two parameters, and because termcap lacks many of +the arithmetic/logical operators used in terminfo. +.bP +capabilities with more than one delay or with delays before the end of +the string will not convert completely. +.RE +.TP +\fB\-c\fR +tells \fB@TIC@\fP to only check \fIfile\fR for errors, +including syntax problems and bad use-links. +If you specify \fB\-C\fR (\fB\-I\fR) with this option, the code +will print warnings about entries which, after use resolution, are more than +1023 (4096) bytes long. +Due to a fixed buffer length in older termcap libraries, +as well as buggy checking for the buffer length +(and a documented limit in terminfo), +these entries may cause core +dumps with other implementations. +.IP +\fB@TIC@\fP checks string capabilities to ensure that those with parameters +will be valid expressions. +It does this check only for the predefined string capabilities; +those which are defined with the \fB\-x\fP option are ignored. +.TP +\fB\-D\fR +tells \fB@TIC@\fP to print the database locations that it knows about, and exit. +The first location shown is the one to which it would write compiled +terminal descriptions. +If \fB@TIC@\fP is not able to find a writable database location +according to the rules summarized above, +it will print a diagnostic and exit with an error rather than +printing a list of database locations. +.TP +\fB\-e \fR\fInames\fR +Limit writes and translations to the following comma-separated list of +terminals. +If any name or alias of a terminal matches one of the names in +the list, the entry will be written or translated as normal. +Otherwise no output will be generated for it. +The option value is interpreted as a file containing the list if it +contains a '/'. +(Note: depending on how @TIC@ was compiled, +this option may require \fB\-I\fR or \fB\-C\fR.) .TP -\fB-G\fR +\fB\-f\fR +Display complex terminfo strings which contain if/then/else/endif expressions +indented for readability. +.TP +\fB\-G\fR Display constant literals in decimal form rather than their character equivalents. .TP -\fB-I\fR +\fB\-g\fR +Display constant character literals in quoted form +rather than their decimal equivalents. +.TP +\fB\-I\fR Force source translation to terminfo format. .TP -\fB-L\fR +\fB\-K\fR +Suppress some longstanding ncurses extensions to termcap format, +e.g., "\\s" for space. +.TP +\fB\-L\fR Force source translation to terminfo format using the long C variable names listed in <\fBterm.h\fR> .TP -\fB-N\fR -Disable smart defaults. -Normally, when translating from termcap to terminfo, the compiler makes +\fB\-N\fR +Disable smart defaults. +Normally, when translating from termcap to terminfo, the compiler makes a number of assumptions about the defaults of string capabilities -\fBreset1_string\fR, \fBcarriage_return\fR, \fBcursor_left\fR, +\fBreset1_string\fR, \fBcarriage_return\fR, \fBcursor_left\fR, \fBcursor_down\fR, \fBscroll_forward\fR, \fBtab\fR, \fBnewline\fR, \fBkey_backspace\fR, \fBkey_left\fR, and \fBkey_down\fR, then attempts -to use obsolete termcap capabilities to deduce correct values. It also +to use obsolete termcap capabilities to deduce correct values. +It also normally suppresses output of obsolete termcap capabilities such as \fBbs\fR. This option forces a more literal translation that also preserves the obsolete capabilities. .TP -\fB-R\fR\fIsubset\fR -Restrict output to a given subset. This option is for use with archaic -versions of terminfo like those on SVr1, Ultrix, or HP/UX that don't support -the full set of SVR4/XSI Curses terminfo; and outright broken ports like AIX 3.x -that have their own extensions incompatible with SVr4/XSI. Available subsets -are "SVr1", "Ultrix", "HP", "BSD" and "AIX"; see \fBterminfo\fR(\*n) for details. +\fB\-o\fR\fIdir\fR +Write compiled entries to given database location. +Overrides the TERMINFO environment variable. .TP -\fB-T\fR -eliminates size-restrictions on the generated text. -This is mainly useful for testing and analysis, since the compiled -descriptions are limited (e.g., 1023 for termcap, 4096 for terminfo). +\fB\-Q\fR\fIn\fR +Rather than show source in terminfo (text) format, +print the compiled (binary) format in hexadecimal or base64 form, +depending on the option's value: +.RS 8 +.TP 3 +1 +hexadecimal +.TP 3 +2 +base64 +.TP 3 +3 +hexadecimal and base64 +.RE .TP -\fB-V\fR -reports the version of ncurses which was used in this program, and exits. +\fB\-q\fR +Suppress comments and blank lines when showing translated source. +.TP +\fB\-R\fR\fIsubset\fR +Restrict output to a given subset. +This option is for use with archaic +versions of terminfo like those on SVr1, Ultrix, or HP/UX that do not support +the full set of SVR4/XSI Curses terminfo; and outright broken ports like AIX 3.x +that have their own extensions incompatible with SVr4/XSI. +Available subsets +are "SVr1", "Ultrix", "HP", "BSD" and "AIX"; +see \fBterminfo\fR(\*n) for details. .TP -\fB-r\fR +\fB\-r\fR Force entry resolution (so there are no remaining tc capabilities) even -when doing translation to termcap format. This may be needed if you are -preparing a termcap file for a termcap library (such as GNU termcap up -to version 1.3 or BSD termcap up to 4.3BSD) that doesn't handle multiple +when doing translation to termcap format. +This may be needed if you are +preparing a termcap file for a termcap library (such as GNU termcap through +version 1.3 or BSD termcap through 4.3BSD) that does not handle multiple tc capabilities per entry. .TP -\fB-e\fR -Limit writes and translations to the following comma-separated list of -terminals. -If any name or alias of a terminal matches one of the names in -the list, the entry will be written or translated as normal. -Otherwise no output will be generated for it. -The option value is interpreted as a file containing the list if it -contains a '/'. -(Note: depending on how tic was compiled, this option may require -I or -C.) -.TP -\fB-f\fR -Display complex terminfo strings which contain if/then/else/endif expressions -indented for readability. +\fB\-s\fR +Summarize the compile by showing the database location into which entries +are written, and the number of entries which are compiled. .TP -\fB-g\fR -Display constant character literals in quoted form -rather than their decimal equivalents. +\fB\-T\fR +eliminates size-restrictions on the generated text. +This is mainly useful for testing and analysis, since the compiled +descriptions are limited (e.g., 1023 for termcap, 4096 for terminfo). .TP -\fB-s\fR -Summarize the compile by showing the directory into which entries -are written, and the number of entries which are compiled. +\fB\-t\fR +tells \fB@TIC@\fP to discard commented-out capabilities. +Normally when translating from terminfo to termcap, +untranslatable capabilities are commented-out. +.TP 5 +\fB\-U\fR +tells \fB@TIC@\fP to not post-process the data after parsing the source file. +Normally, it infers data which is commonly missing in older terminfo data, +or in termcaps. .TP -\fB-x\fR -Treat unknown capabilities as user-defined. -That is, if you supply a capability name which \fBtic\fP does not recognize, -it will infer its type (boolean, number or string) from the syntax and -make an extended table entry for that. +\fB\-V\fR +reports the version of ncurses which was used in this program, and exits. .TP -\fIfile\fR -contains one or more \fBterminfo\fR terminal descriptions in source -format [see \fBterminfo\fR(\*n)]. Each description in the file -describes the capabilities of a particular terminal. +\fB\-v\fR\fIn\fR +specifies that (verbose) output be written to standard error trace +information showing \fB@TIC@\fR's progress. +.IP +The optional parameter \fIn\fR is a number from 1 to 10, inclusive, +indicating the desired level of detail of information. +If ncurses is built without tracing support, the optional parameter is ignored. +If \fIn\fR is omitted, the default level is 1. +If \fIn\fR is specified and greater than 1, the level of +detail is increased. +.RS .PP The debug flag levels are as follows: .TP @@ -197,7 +325,7 @@ The debug flag levels are as follows: Names of files created and linked .TP 2 -Information related to the ``use'' facility +Information related to the \*(``use\*('' facility .TP 3 Statistics from the hashing algorithm @@ -214,88 +342,137 @@ List of tokens encountered by scanner 9 All values computed in construction of the hash table .LP -If n is not given, it is taken to be one. +If the debug level \fIn\fR is not given, it is taken to be one. +.RE +.TP +\fB\-W\fR +By itself, the \fB\-w\fP option will not force long strings to be wrapped. +Use the \fB\-W\fP option to do this. +.IP +If you specify both \fB\-f\fP and \fB\-W\fP options, +the latter is ignored when \fB\-f\fP has already split the line. +.TP +\fB\-w\fR\fIn\fR +specifies the width of the output. +The parameter is optional. +If it is omitted, it defaults to 60. +.TP +\fB\-x\fR +Treat unknown capabilities as user-defined (see \fBuser_caps(\*n)\fP). +That is, if you supply a capability name which \fB@TIC@\fP does not recognize, +it will infer its type (boolean, number or string) from the syntax and +make an extended table entry for that. +User-defined capability strings +whose name begins with \*(``k\*('' are treated as function keys. +.SS PARAMETERS +.TP +\fIfile\fR +contains one or more \fBterminfo\fR terminal descriptions in source +format [see \fBterminfo\fR(\*n)]. +Each description in the file +describes the capabilities of a particular terminal. +.IP +If \fIfile\fR is \*(``-\*('', then the data is read from the standard input. +The \fIfile\fR parameter may also be the path of a character-device. +.SS PROCESSING +.PP +All but one of the capabilities recognized by \fB@TIC@\fR are documented +in \fBterminfo\fR(\*n). +The exception is the \fBuse\fR capability. .PP -All but one of the capabilities recognized by \fBtic\fR are documented -in \fBterminfo\fR(\*n). The exception is the \fBuse\fR capability. - -When a \fBuse\fR=\fIentry\fR-\fIname\fR field is discovered in a -terminal entry currently being compiled, \fBtic\fR reads in the binary -from \fB\*d\fR to complete the entry. (Entries created from -\fIfile\fR will be used first. If the environment variable -\fBTERMINFO\fR is set, that directory is searched instead of -\fB\*d\fR.) \fBtic\fR duplicates the capabilities in -\fIentry\fR-\fIname\fR for the current entry, with the exception of +When a \fBuse\fR=\fIentry\fR\-\fIname\fR field is discovered in a +terminal entry currently being compiled, \fB@TIC@\fR reads in the binary +from \fB\*d\fR to complete the entry. +(Entries created from +\fIfile\fR will be used first. +\fB@TIC@\fR duplicates the capabilities in +\fIentry\fR\-\fIname\fR for the current entry, with the exception of those capabilities that explicitly are defined in the current entry. - +.PP When an entry, e.g., \fBentry_name_1\fR, contains a \fBuse=\fR\fIentry\fR_\fIname\fR_\fI2\fR field, any canceled capabilities in \fIentry\fR_\fIname\fR_\fI2\fR must also appear in \fBentry_name_1\fR before \fBuse=\fR for these capabilities to be canceled in \fBentry_name_1\fR. - -If the environment variable \fBTERMINFO\fR is set, the compiled -results are placed there instead of \fB\*d\fR. - -Total compiled entries cannot exceed 4096 bytes. The name field cannot -exceed 512 bytes. Terminal names exceeding the maximum alias length +.PP +Total compiled entries cannot exceed 4096 bytes. +The name field cannot +exceed 512 bytes. +Terminal names exceeding the maximum alias length (32 characters on systems with long filenames, 14 characters otherwise) -will be truncated to the maximum alias length and a warning message will be printed. +will be truncated to the maximum alias length +and a warning message will be printed. .SH COMPATIBILITY -There is some evidence that historic \fBtic\fR implementations treated +There is some evidence that historic \fB@TIC@\fR implementations treated description fields with no whitespace in them as additional aliases or -short names. This \fBtic\fR does not do that, but it does warn when +short names. +This \fB@TIC@\fR does not do that, but it does warn when description fields may be treated that way and check them for dangerous characters. .SH EXTENSIONS -Unlike the stock SVr4 \fBtic\fR command, this implementation can actually -compile termcap sources. In fact, entries in terminfo and termcap syntax can -be mixed in a single source file. See \fBterminfo\fR(\*n) for the list of +Unlike the SVr4 \fB@TIC@\fR command, this implementation can actually +compile termcap sources. +In fact, entries in terminfo and termcap syntax can +be mixed in a single source file. +See \fBterminfo\fR(\*n) for the list of termcap names taken to be equivalent to terminfo names. - +.PP The SVr4 manual pages are not clear on the resolution rules for \fBuse\fR capabilities. -This implementation of \fBtic\fR will find \fBuse\fR targets anywhere +This implementation of \fB@TIC@\fR will find \fBuse\fR targets anywhere in the source file, or anywhere in the file tree rooted at \fBTERMINFO\fR (if -\fBTERMINFO\fR is defined), or in the user's \fI$HOME/.terminfo\fR directory -(if it exists), or (finally) anywhere in the system's file tree of +\fBTERMINFO\fR is defined), +or in the user's \fI$HOME/.terminfo\fR database +(if it exists), +or (finally) anywhere in the system's file tree of compiled entries. - -The error messages from this \fBtic\fR have the same format as GNU C +.PP +The error messages from this \fB@TIC@\fR have the same format as GNU C error messages, and can be parsed by GNU Emacs's compile facility. - +.PP The -\fB-C\fR, -\fB-G\fR, -\fB-I\fR, -\fB-N\fR, -\fB-R\fR, -\fB-T\fR, -\fB-V\fR, -\fB-a\fR, -\fB-e\fR, -\fB-f\fR, -\fB-g\fR, -\fB-o\fR, -\fB-r\fR, -\fB-s\fR and -\fB-x\fR +\fB\-0\fR, +\fB\-1\fR, +\fB\-C\fR, +\fB\-G\fR, +\fB\-I\fR, +\fB\-N\fR, +\fB\-R\fR, +\fB\-T\fR, +\fB\-V\fR, +\fB\-a\fR, +\fB\-e\fR, +\fB\-f\fR, +\fB\-g\fR, +\fB\-o\fR, +\fB\-r\fR, +\fB\-s\fR, +\fB\-t\fR and +\fB\-x\fR options are not supported under SVr4. -The SVr4 -c mode does not report bad use links. - +The SVr4 \fB\-c\fR mode does not report bad use links. +.PP System V does not compile entries to or read entries from your -\fI$HOME/.terminfo\fR directory unless TERMINFO is explicitly set to it. +\fI$HOME/.terminfo\fR database unless TERMINFO is explicitly set to it. .SH FILES .TP 5 \fB\*d/?/*\fR Compiled terminal description database. .SH SEE ALSO -\fB@INFOCMP@\fR(1M), \fB@CAPTOINFO@\fR(1M), \fB@INFOTOCAP@\fR(1M), -\fB@TOE@\fR(1M), \fBcurses\fR(3X), \fBterminfo\fR(\*n). -.\"# -.\"# The following sets edit modes for GNU EMACS -.\"# Local Variables: -.\"# mode:nroff -.\"# fill-column:79 -.\"# End: +\fB@INFOCMP@\fR(1M), +\fB@CAPTOINFO@\fR(1M), +\fB@INFOTOCAP@\fR(1M), +\fB@TOE@\fR(1M), +\fBcurses\fR(3X), +\fBterm\fR(\*n). +\fBterminfo\fR(\*n). +\fBuser_caps\fR(\*n). +.PP +This describes \fBncurses\fR +version @NCURSES_MAJOR@.@NCURSES_MINOR@ (patch @NCURSES_PATCH@). +.SH AUTHOR +Eric S. Raymond +and +.br +Thomas E. Dickey