14a1a9510SRong-En Fan------------------------------------------------------------------------------- 2*21817992SBaptiste Daroussin-- Copyright 2020-2021,2023 Thomas E. Dickey -- 3e1865124SBaptiste Daroussin-- Copyright 1998-2012,2018 Free Software Foundation, Inc. -- 44a1a9510SRong-En Fan-- -- 54a1a9510SRong-En Fan-- Permission is hereby granted, free of charge, to any person obtaining a -- 64a1a9510SRong-En Fan-- copy of this software and associated documentation files (the -- 74a1a9510SRong-En Fan-- "Software"), to deal in the Software without restriction, including -- 84a1a9510SRong-En Fan-- without limitation the rights to use, copy, modify, merge, publish, -- 94a1a9510SRong-En Fan-- distribute, distribute with modifications, sublicense, and/or sell copies -- 104a1a9510SRong-En Fan-- of the Software, and to permit persons to whom the Software is furnished -- 114a1a9510SRong-En Fan-- to do so, subject to the following conditions: -- 124a1a9510SRong-En Fan-- -- 134a1a9510SRong-En Fan-- The above copyright notice and this permission notice shall be included -- 144a1a9510SRong-En Fan-- in all copies or substantial portions of the Software. -- 154a1a9510SRong-En Fan-- -- 164a1a9510SRong-En Fan-- THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS -- 174a1a9510SRong-En Fan-- OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF -- 184a1a9510SRong-En Fan-- MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN -- 194a1a9510SRong-En Fan-- NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, -- 204a1a9510SRong-En Fan-- DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR -- 214a1a9510SRong-En Fan-- OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE -- 224a1a9510SRong-En Fan-- USE OR OTHER DEALINGS IN THE SOFTWARE. -- 234a1a9510SRong-En Fan-- -- 244a1a9510SRong-En Fan-- Except as contained in this notice, the name(s) of the above copyright -- 254a1a9510SRong-En Fan-- holders shall not be used in advertising or otherwise to promote the -- 264a1a9510SRong-En Fan-- sale, use or other dealings in this Software without prior written -- 274a1a9510SRong-En Fan-- authorization. -- 284a1a9510SRong-En Fan------------------------------------------------------------------------------- 29*21817992SBaptiste Daroussin-- $Id: README,v 1.31 2023/10/28 14:49:04 tom Exp $ 300e3d5408SPeter Wemm------------------------------------------------------------------------------- 310e3d5408SPeter Wemm README file for the ncurses package 320e3d5408SPeter Wemm 330e3d5408SPeter WemmSee the file ANNOUNCE for a summary of ncurses features and ports. 340e3d5408SPeter WemmSee the file INSTALL for instructions on how to build and install ncurses. 350e3d5408SPeter WemmSee the file NEWS for a release history and bug-fix notes. 360e3d5408SPeter WemmSee the file TO-DO for things that still need doing, including known bugs. 370e3d5408SPeter Wemm 38*21817992SBaptiste DaroussinBrowse the file doc/html/ncurses-intro.html for narrative descriptions of how 390e3d5408SPeter Wemmto use ncurses and the panel, menu, and form libraries. 400e3d5408SPeter Wemm 4118259542SPeter WemmBrowse the file doc/html/hackguide.html for a tour of the package internals. 420e3d5408SPeter Wemm 43*21817992SBaptiste DaroussinFind plain text versions of both of these documents in doc/. 44*21817992SBaptiste Daroussin 450e3d5408SPeter WemmROADMAP AND PACKAGE OVERVIEW: 460e3d5408SPeter Wemm 470e3d5408SPeter WemmYou should be reading this file in a directory called: ncurses-d.d, where d.d 480e3d5408SPeter Wemmis the current version number (see the dist.mk file in this directory for 490e3d5408SPeter Wemmthat). There should be a number of subdirectories, including `c++', `form', 50*21817992SBaptiste Daroussin`man', `menu', `misc', `ncurses', `panel', `progs', `test', and `Ada95'. 510e3d5408SPeter Wemm 520e3d5408SPeter WemmA full build/install of this package typically installs several libraries, a 530e3d5408SPeter Wemmhandful of utilities, and a database hierarchy. Here is an inventory of the 540e3d5408SPeter Wemmpieces: 550e3d5408SPeter Wemm 560e3d5408SPeter WemmThe libraries are: 570e3d5408SPeter Wemm 580e3d5408SPeter Wemm libncurses.a (normal) 590e3d5408SPeter Wemm libncurses.so (shared) 600e3d5408SPeter Wemm libncurses_g.a (debug and trace code enabled) 610e3d5408SPeter Wemm libncurses_p.a (profiling enabled) 620e3d5408SPeter Wemm 630e3d5408SPeter Wemm libpanel.a (normal) 640e3d5408SPeter Wemm libpanel.so (shared) 650e3d5408SPeter Wemm libpanel_g.a (debug and trace code enabled) 660e3d5408SPeter Wemm 670e3d5408SPeter Wemm libmenu.a (normal) 680e3d5408SPeter Wemm libmenu.so (shared) 690e3d5408SPeter Wemm libmenu_g.a (debug enabled) 700e3d5408SPeter Wemm 710e3d5408SPeter Wemm libform.a (normal) 720e3d5408SPeter Wemm libform.so (shared) 730e3d5408SPeter Wemm libform_g.a (debug enabled) 740e3d5408SPeter Wemm 754a1a9510SRong-En FanIf you configure using the --enable-widec option, a "w" is appended to the 764a1a9510SRong-En Fanlibrary names (e.g., libncursesw.a), and the resulting libraries support 774a1a9510SRong-En Fanwide-characters, e.g., via a UTF-8 locale. The corresponding header files 784a1a9510SRong-En Fanare compatible with the non-wide-character configuration; wide-character 794a1a9510SRong-En Fanfeatures are provided by ifdef's in the header files. The wide-character 804a1a9510SRong-En Fanlibrary interfaces are not binary-compatible with the non-wide-character 814a1a9510SRong-En Fanversion. 824a1a9510SRong-En Fan 8373f0a83dSXin LIIf you configure using the --enable-reentrant option, a "t" is appended to the 8473f0a83dSXin LIlibrary names (e.g., libncursest.a) and the resulting libraries have a 85*21817992SBaptiste Daroussindifferent binary interface, making the ncurses interface more opaque. 8673f0a83dSXin LI 870e3d5408SPeter WemmThe ncurses libraries implement the curses API. The panel, menu and forms 880e3d5408SPeter Wemmlibraries implement clones of the SVr4 panel, menu and forms APIs. The source 890e3d5408SPeter Wemmcode for these lives in the `ncurses', `panel', `menu', and `form' directories 900e3d5408SPeter Wemmrespectively. 910e3d5408SPeter Wemm 920e3d5408SPeter WemmIn the `c++' directory, you'll find code that defines an interface to the 93*21817992SBaptiste Daroussincurses, forms, menus and panels library packaged as C++ classes, and a demo 94*21817992SBaptiste Daroussinprogram in C++ to test it. These class definition modules are not installed 95*21817992SBaptiste Daroussinby the 'make install.libs' rule as libncurses++. 960e3d5408SPeter Wemm 970e3d5408SPeter WemmIn the `Ada95' directory, you'll find code and documentation for an 980e3d5408SPeter WemmAda95 binding of the curses API, to be used with the GNAT compiler. 990e3d5408SPeter WemmThis binding is built by a normal top-level `make' if configure detects 1004a1a9510SRong-En Fanan usable version of GNAT (3.11 or above). It is not installed automatically. 1010e3d5408SPeter WemmSee the Ada95 directory for more build and installation instructions and 1020e3d5408SPeter Wemmfor documentation of the binding. 1030e3d5408SPeter Wemm 1040e3d5408SPeter WemmTo do its job, the ncurses code needs your terminal type to be set in the 1050e3d5408SPeter Wemmenvironment variable TERM (normally set by your OS; under UNIX, getty(1) 106*21817992SBaptiste Daroussintypically does this, but you can override it in your .profile); and, it needs 107*21817992SBaptiste Daroussina database of terminal descriptions in which to look up your terminal type's 1080e3d5408SPeter Wemmcapabilities. 1090e3d5408SPeter Wemm 1100e3d5408SPeter WemmIn older (V7/BSD) versions of curses, the database was a flat text file, 1110e3d5408SPeter Wemm/etc/termcap; in newer (USG/USL) versions, the database is a hierarchy of 1120e3d5408SPeter Wemmfast-loading binary description blocks under /usr/lib/terminfo. These binary 1130e3d5408SPeter Wemmblocks are compiled from an improved editable text representation called 1140e3d5408SPeter Wemm`terminfo' format (documented in man/terminfo.5). The ncurses library can use 1150e3d5408SPeter Wemmeither /etc/termcap or the compiled binary terminfo blocks, but prefers the 1160e3d5408SPeter Wemmsecond form. 1170e3d5408SPeter Wemm 1180e3d5408SPeter WemmIn the `misc' directory, there is a text file terminfo.src, in editable 1190e3d5408SPeter Wemmterminfo format, which can be used to generate the terminfo binaries (that's 1200e3d5408SPeter Wemmwhat make install.data does). If the package was built with the 121*21817992SBaptiste Daroussin--enable-termcap option enabled, and the ncurses library cannot find a 122*21817992SBaptiste Daroussinterminfo description for your terminal, it will fall back to the termcap file 123*21817992SBaptiste Daroussinsupplied with your system (which the ncurses package installation leaves 124*21817992SBaptiste Daroussinstrictly alone). 1250e3d5408SPeter Wemm 1260e3d5408SPeter WemmThe utilities are as follows: 1270e3d5408SPeter Wemm 1280e3d5408SPeter Wemm tic -- terminfo source to binary compiler 1290e3d5408SPeter Wemm infocmp -- terminfo binary to source decompiler/comparator 1300e3d5408SPeter Wemm clear -- emits clear-screen for current terminal 13173f0a83dSXin LI tabs -- set tabs on a terminal 1320e3d5408SPeter Wemm tput -- shell-script access to terminal capabilities. 1330e3d5408SPeter Wemm toe -- table of entries utility 1340e3d5408SPeter Wemm tset -- terminal-initialization utility 1350e3d5408SPeter Wemm 1360e3d5408SPeter WemmThe first two (tic and infocmp) are used for manipulating terminfo 1370e3d5408SPeter Wemmdescriptions; the next two (clear and tput) are for use in shell scripts. The 1380e3d5408SPeter Wemmlast (tset) is provided for 4.4BSD compatibility. The source code for all of 1390e3d5408SPeter Wemmthese lives in the `progs' directory. 1400e3d5408SPeter Wemm 14118259542SPeter WemmDetailed documentation for all libraries and utilities can be found in the 14218259542SPeter Wemm`man' and `doc' directories. An HTML introduction to ncurses, panels, and 14318259542SPeter Wemmmenus programming lives in the `doc/html' directory. Manpages in HTML format 14418259542SPeter Wemmare under `doc/html/man'. 1450e3d5408SPeter Wemm 1460e3d5408SPeter WemmThe `test' directory contains programs that can be used to verify or 1470e3d5408SPeter Wemmdemonstrate the functions of the ncurses libraries. See test/README for 1480e3d5408SPeter Wemmdescriptions of these programs. Notably, the `ncurses' utility is designed to 1490e3d5408SPeter Wemmhelp you systematically exercise the library functions. 1500e3d5408SPeter Wemm 1510e3d5408SPeter WemmAUTHORS: 1520e3d5408SPeter Wemm 1530e3d5408SPeter WemmPavel Curtis: 1540e3d5408SPeter Wemm wrote the original ncurses 1550e3d5408SPeter Wemm 1560e3d5408SPeter WemmZeyd M. Ben-Halim: 1570e3d5408SPeter Wemm port of original to Linux and many enhancements. 1580e3d5408SPeter Wemm 1591759abf3SPeter WemmThomas Dickey (maintainer for 1.9.9g through 4.1, resuming with FSF's 5.0): 1600e3d5408SPeter Wemm configuration scripts, porting, mods to adhere to XSI Curses in the 1610e3d5408SPeter Wemm areas of background color, terminal modes. Also memory leak testing, 1620e3d5408SPeter Wemm the wresize, default colors and key definition extensions and numerous 16373f0a83dSXin LI bug fixes -- more than half of those enumerated in NEWS beginning with 16473f0a83dSXin LI the internal release 1.8.9, see 16573f0a83dSXin LI 166aae38d10SBaptiste Daroussin https://invisible-island.net/personal/changelogs.html 1670e3d5408SPeter Wemm 1680e3d5408SPeter WemmFlorian La Roche (official maintainer for FSF's ncurses 4.2) 1690e3d5408SPeter Wemm Beginning with release 4.2, ncurses is distributed under an MIT-style 1700e3d5408SPeter Wemm license. 1710e3d5408SPeter Wemm 1720e3d5408SPeter WemmEric S. Raymond: 1730e3d5408SPeter Wemm the man pages, infocmp(1), tput(1), clear(1), captoinfo(1), tset(1), 1740e3d5408SPeter Wemm toe(1), most of tic(1), trace levels, the HTML intro, wgetnstr() and 1750e3d5408SPeter Wemm many other entry points, the cursor-movement optimization, the 1760e3d5408SPeter Wemm scroll-pack optimizer for vertical motions, the mouse interface and 1770e3d5408SPeter Wemm xterm mouse support, and the ncurses test program. 1780e3d5408SPeter Wemm 1790e3d5408SPeter WemmJuergen Pfeifer 180*21817992SBaptiste Daroussin The menu and form libraries, C++ bindings for ncurses, menus, forms 181*21817992SBaptiste Daroussin and panels, as well as the Ada95 binding. Ongoing support for panel. 1820e3d5408SPeter Wemm 1830e3d5408SPeter WemmCONTRIBUTORS: 1840e3d5408SPeter Wemm 1850e3d5408SPeter WemmAlexander V. Lukyanov 1860e3d5408SPeter Wemm for numerous fixes and improvements to the optimization logic. 1870e3d5408SPeter Wemm 1880e3d5408SPeter WemmDavid MacKenzie 1890e3d5408SPeter Wemm for first-class bug-chasing and methodical testing. 1900e3d5408SPeter Wemm 1910e3d5408SPeter WemmRoss Ridge 1920e3d5408SPeter Wemm for the code that hacks termcap parameterized strings into terminfo. 1930e3d5408SPeter Wemm 1940e3d5408SPeter WemmWarren Tucker and Gerhard Fuernkranz, 1950e3d5408SPeter Wemm for writing and sending the panel library. 1960e3d5408SPeter Wemm 1970e3d5408SPeter WemmHellmuth Michaelis, 1980e3d5408SPeter Wemm for many patches and testing the optimization code. 1990e3d5408SPeter Wemm 2000e3d5408SPeter WemmEric Newton, Ulrich Drepper, and Anatoly Ivasyuk: 2010e3d5408SPeter Wemm the C++ code. 2020e3d5408SPeter Wemm 2030e3d5408SPeter WemmJonathan Ross, 2040e3d5408SPeter Wemm for lessons in using sed. 2050e3d5408SPeter Wemm 2060e3d5408SPeter WemmKeith Bostic (maintainer of 4.4BSD curses) 2070e3d5408SPeter Wemm for help, criticism, comments, bug-finding, and being willing to 2080e3d5408SPeter Wemm deep-six BSD curses for this one when it grew up. 2090e3d5408SPeter Wemm 2100e3d5408SPeter WemmRichard Stallman, 2110e3d5408SPeter Wemm for his commitment to making ncurses free software. 2120e3d5408SPeter Wemm 2130e3d5408SPeter WemmCountless other people have contributed by reporting bugs, sending fixes, 2140e3d5408SPeter Wemmsuggesting improvements, and generally whining about ncurses :-) 2150e3d5408SPeter Wemm 2160e3d5408SPeter WemmBUGS: 2170e3d5408SPeter Wemm See the INSTALL file for bug and developer-list addresses. 21818259542SPeter Wemm The Hacker's Guide in the doc directory includes some guidelines 2190e3d5408SPeter Wemm on how to report bugs in ways that will get them fixed most quickly. 220*21817992SBaptiste Daroussin 221*21817992SBaptiste Daroussin-- vile:txtmode fc=78 222