150276Speter------------------------------------------------------------------------------- 2166124Srafan-- Copyright (c) 1998-2004,2006 Free Software Foundation, Inc. -- 3166124Srafan-- -- 4166124Srafan-- Permission is hereby granted, free of charge, to any person obtaining a -- 5166124Srafan-- copy of this software and associated documentation files (the -- 6166124Srafan-- "Software"), to deal in the Software without restriction, including -- 7166124Srafan-- without limitation the rights to use, copy, modify, merge, publish, -- 8166124Srafan-- distribute, distribute with modifications, sublicense, and/or sell copies -- 9166124Srafan-- of the Software, and to permit persons to whom the Software is furnished -- 10166124Srafan-- to do so, subject to the following conditions: -- 11166124Srafan-- -- 12166124Srafan-- The above copyright notice and this permission notice shall be included -- 13166124Srafan-- in all copies or substantial portions of the Software. -- 14166124Srafan-- -- 15166124Srafan-- THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS -- 16166124Srafan-- OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF -- 17166124Srafan-- MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN -- 18166124Srafan-- NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, -- 19166124Srafan-- DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR -- 20166124Srafan-- OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE -- 21166124Srafan-- USE OR OTHER DEALINGS IN THE SOFTWARE. -- 22166124Srafan-- -- 23166124Srafan-- Except as contained in this notice, the name(s) of the above copyright -- 24166124Srafan-- holders shall not be used in advertising or otherwise to promote the -- 25166124Srafan-- sale, use or other dealings in this Software without prior written -- 26166124Srafan-- authorization. -- 27166124Srafan------------------------------------------------------------------------------- 28166124Srafan-- $Id: README,v 1.23 2006/04/22 22:19:37 tom Exp $ 29166124Srafan------------------------------------------------------------------------------- 3050276Speter README file for the ncurses package 3150276Speter 3250276SpeterSee the file ANNOUNCE for a summary of ncurses features and ports. 3350276SpeterSee the file INSTALL for instructions on how to build and install ncurses. 3450276SpeterSee the file NEWS for a release history and bug-fix notes. 3550276SpeterSee the file TO-DO for things that still need doing, including known bugs. 3650276Speter 3750276SpeterBrowse the file misc/ncurses-intro.html for narrative descriptions of how 3850276Speterto use ncurses and the panel, menu, and form libraries. 3950276Speter 4066963SpeterBrowse the file doc/html/hackguide.html for a tour of the package internals. 4150276Speter 4250276SpeterROADMAP AND PACKAGE OVERVIEW: 4350276Speter 4450276SpeterYou should be reading this file in a directory called: ncurses-d.d, where d.d 4550276Speteris the current version number (see the dist.mk file in this directory for 4650276Speterthat). There should be a number of subdirectories, including `c++', `form', 4750276Speter`man', `menu', `misc', `ncurses', `panel', `progs', `test', 'tack' and `Ada95'. 4856639Speter(The 'tack' program may be distributed separately). 4950276Speter 5050276SpeterA full build/install of this package typically installs several libraries, a 5150276Speterhandful of utilities, and a database hierarchy. Here is an inventory of the 5250276Speterpieces: 5350276Speter 5450276SpeterThe libraries are: 5550276Speter 5650276Speter libncurses.a (normal) 5750276Speter libncurses.so (shared) 5850276Speter libncurses_g.a (debug and trace code enabled) 5950276Speter libncurses_p.a (profiling enabled) 6050276Speter 6150276Speter libpanel.a (normal) 6250276Speter libpanel.so (shared) 6350276Speter libpanel_g.a (debug and trace code enabled) 6450276Speter 6550276Speter libmenu.a (normal) 6650276Speter libmenu.so (shared) 6750276Speter libmenu_g.a (debug enabled) 6850276Speter 6950276Speter libform.a (normal) 7050276Speter libform.so (shared) 7150276Speter libform_g.a (debug enabled) 7250276Speter 73166124SrafanIf you configure using the --enable-widec option, a "w" is appended to the 74166124Srafanlibrary names (e.g., libncursesw.a), and the resulting libraries support 75166124Srafanwide-characters, e.g., via a UTF-8 locale. The corresponding header files 76166124Srafanare compatible with the non-wide-character configuration; wide-character 77166124Srafanfeatures are provided by ifdef's in the header files. The wide-character 78166124Srafanlibrary interfaces are not binary-compatible with the non-wide-character 79166124Srafanversion. 80166124Srafan 8150276SpeterThe ncurses libraries implement the curses API. The panel, menu and forms 8250276Speterlibraries implement clones of the SVr4 panel, menu and forms APIs. The source 8350276Spetercode for these lives in the `ncurses', `panel', `menu', and `form' directories 8450276Speterrespectively. 8550276Speter 8650276SpeterIn the `c++' directory, you'll find code that defines an interface to the 8750276Spetercurses, forms, menus and panels library packaged as C++ classes, and a demo program in C++ 8850276Speterto test it. These class definition modules are not installed by the 'make 8950276Speterinstall.libs' rule as libncurses++. 9050276Speter 9150276SpeterIn the `Ada95' directory, you'll find code and documentation for an 9250276SpeterAda95 binding of the curses API, to be used with the GNAT compiler. 9350276SpeterThis binding is built by a normal top-level `make' if configure detects 94166124Srafanan usable version of GNAT (3.11 or above). It is not installed automatically. 9550276SpeterSee the Ada95 directory for more build and installation instructions and 9650276Speterfor documentation of the binding. 9750276Speter 9850276SpeterTo do its job, the ncurses code needs your terminal type to be set in the 9950276Speterenvironment variable TERM (normally set by your OS; under UNIX, getty(1) 10050276Spetertypically does this, but you can override it in your .profile); and, it needs a 10150276Speterdatabase of terminal descriptions in which to look up your terminal type's 10250276Spetercapabilities. 10350276Speter 10450276SpeterIn older (V7/BSD) versions of curses, the database was a flat text file, 10550276Speter/etc/termcap; in newer (USG/USL) versions, the database is a hierarchy of 10650276Speterfast-loading binary description blocks under /usr/lib/terminfo. These binary 10750276Speterblocks are compiled from an improved editable text representation called 10850276Speter`terminfo' format (documented in man/terminfo.5). The ncurses library can use 10950276Spetereither /etc/termcap or the compiled binary terminfo blocks, but prefers the 11050276Spetersecond form. 11150276Speter 11250276SpeterIn the `misc' directory, there is a text file terminfo.src, in editable 11350276Speterterminfo format, which can be used to generate the terminfo binaries (that's 11450276Speterwhat make install.data does). If the package was built with the 11550276Speter--enable-termcap option enabled, and the ncurses library cannot find a terminfo 11650276Speterdescription for your terminal, it will fall back to the termcap file supplied 11750276Speterwith your system (which the ncurses package installation leaves strictly 11850276Speteralone). 11950276Speter 12050276SpeterThe utilities are as follows: 12150276Speter 12250276Speter tic -- terminfo source to binary compiler 12350276Speter infocmp -- terminfo binary to source decompiler/comparator 12450276Speter clear -- emits clear-screen for current terminal 12550276Speter tput -- shell-script access to terminal capabilities. 12650276Speter toe -- table of entries utility 12750276Speter tset -- terminal-initialization utility 12850276Speter 12950276SpeterThe first two (tic and infocmp) are used for manipulating terminfo 13050276Speterdescriptions; the next two (clear and tput) are for use in shell scripts. The 13150276Speterlast (tset) is provided for 4.4BSD compatibility. The source code for all of 13250276Speterthese lives in the `progs' directory. 13350276Speter 13466963SpeterDetailed documentation for all libraries and utilities can be found in the 13566963Speter`man' and `doc' directories. An HTML introduction to ncurses, panels, and 13666963Spetermenus programming lives in the `doc/html' directory. Manpages in HTML format 13766963Speterare under `doc/html/man'. 13850276Speter 13950276SpeterThe `test' directory contains programs that can be used to verify or 14050276Speterdemonstrate the functions of the ncurses libraries. See test/README for 14150276Speterdescriptions of these programs. Notably, the `ncurses' utility is designed to 14250276Speterhelp you systematically exercise the library functions. 14350276Speter 14450276SpeterAUTHORS: 14550276Speter 14650276SpeterPavel Curtis: 14750276Speter wrote the original ncurses 14850276Speter 14950276SpeterZeyd M. Ben-Halim: 15050276Speter port of original to Linux and many enhancements. 15150276Speter 15256639SpeterThomas Dickey (maintainer for 1.9.9g through 4.1, resuming with FSF's 5.0): 15350276Speter configuration scripts, porting, mods to adhere to XSI Curses in the 15450276Speter areas of background color, terminal modes. Also memory leak testing, 15550276Speter the wresize, default colors and key definition extensions and numerous 15650276Speter bug fixes (more than half of those enumerated in NEWS beginning with 15750276Speter the internal release 1.8.9). 15850276Speter 15950276SpeterFlorian La Roche (official maintainer for FSF's ncurses 4.2) 16050276Speter Beginning with release 4.2, ncurses is distributed under an MIT-style 16150276Speter license. 16250276Speter 16350276SpeterEric S. Raymond: 16450276Speter the man pages, infocmp(1), tput(1), clear(1), captoinfo(1), tset(1), 16550276Speter toe(1), most of tic(1), trace levels, the HTML intro, wgetnstr() and 16650276Speter many other entry points, the cursor-movement optimization, the 16750276Speter scroll-pack optimizer for vertical motions, the mouse interface and 16850276Speter xterm mouse support, and the ncurses test program. 16950276Speter 17050276SpeterJuergen Pfeifer 17150276Speter The menu and form libraries, C++ bindings for ncurses, menus, forms and 17250276Speter panels, as well as the Ada95 binding. Ongoing support for panel. 17350276Speter 17450276SpeterCONTRIBUTORS: 17550276Speter 17650276SpeterAlexander V. Lukyanov 17750276Speter for numerous fixes and improvements to the optimization logic. 17850276Speter 17950276SpeterDavid MacKenzie 18050276Speter for first-class bug-chasing and methodical testing. 18150276Speter 18250276SpeterRoss Ridge 18350276Speter for the code that hacks termcap parameterized strings into terminfo. 18450276Speter 18550276SpeterWarren Tucker and Gerhard Fuernkranz, 18650276Speter for writing and sending the panel library. 18750276Speter 18850276SpeterHellmuth Michaelis, 18950276Speter for many patches and testing the optimization code. 19050276Speter 19150276SpeterEric Newton, Ulrich Drepper, and Anatoly Ivasyuk: 19250276Speter the C++ code. 19350276Speter 19450276SpeterJonathan Ross, 19550276Speter for lessons in using sed. 19650276Speter 19750276SpeterKeith Bostic (maintainer of 4.4BSD curses) 19850276Speter for help, criticism, comments, bug-finding, and being willing to 19950276Speter deep-six BSD curses for this one when it grew up. 20050276Speter 20150276SpeterRichard Stallman, 20250276Speter for his commitment to making ncurses free software. 20350276Speter 20450276SpeterCountless other people have contributed by reporting bugs, sending fixes, 20550276Spetersuggesting improvements, and generally whining about ncurses :-) 20650276Speter 20750276SpeterBUGS: 20850276Speter See the INSTALL file for bug and developer-list addresses. 20966963Speter The Hacker's Guide in the doc directory includes some guidelines 21050276Speter on how to report bugs in ways that will get them fixed most quickly. 211