Initial revision

FossilOrigin-Name: 8922a99ffbe6bf4c9a879291efacef5ce9caa2aa

1 files changed, 381 insertions, 0 deletions

diff --git a/README b/README
new file mode 100644
index 0000000..255f0a1
--- /dev/null
+++ b/README
@@ -0,0 +1,381 @@
+The Tk Toolkit
+
+SCCS: @(#) README 1.47 97/11/20 12:48:16
+
+1. Introduction
+---------------
+
+This directory and its descendants contain the sources and documentation
+for Tk, an X11 toolkit implemented with the Tcl scripting language.  The
+information here corresponds to Tk 8.0p2, which is the second patch update
+for Tk 8.0.  This release is designed to work with Tcl 8.0p2 and may not
+work with any other version of Tcl.
+
+Tk 8.0 is a major release with significant new features such as native
+look and feel on Macintoshes and PCs, a new font mechanism, application
+embedding, and proper support for Safe-Tcl.  See below for details.
+There should be no backward incompatibilities in Tk 8.0 that affect
+scripts.  This patch release fixes various bugs in Tk 8.0; there are no
+feature changes relative to Tk 8.0.
+
+Note: with Tk 8.0 the Tk version number skipped from 4.2 to 8.0. The
+jump was made in order to synchronize the Tcl and Tk version numbers.
+
+2. Documentation
+----------------
+
+The best way to get started with Tk is to read one of the introductory
+books on Tcl and Tk:
+
+    Practical Programming in Tcl and Tk, 2nd Edition, by Brent Welch,
+    Prentice-Hall, 1997, ISBN 0-13-616830-2
+
+    Tcl and the Tk Toolkit, by John Ousterhout,
+    Addison-Wesley, 1994, ISBN 0-201-63337-X
+
+    Exploring Expect, by Don Libes,
+    O'Reilly and Associates, 1995, ISBN 1-56592-090-2
+
+The "doc" subdirectory in this release contains a complete set of
+reference manual entries for Tk.  Files with extension ".1" are for
+programs such as wish; files with extension ".3" are for C library
+procedures; and files with extension ".n" describe Tcl commands.  To
+print any of the manual entries, cd to the "doc" directory and invoke
+your favorite variant of troff using the normal -man macros, for example
+
+		ditroff -man wish.1
+
+to print wish.1.  If Tk has been installed correctly and your "man"
+program supports it, you should be able to access the Tcl manual entries
+using the normal "man" mechanisms, such as
+
+		man wish
+
+If you are porting Tk 3.6 scripts to Tk 4.0 or later releases, you may
+find the Postscript file doc/tk4.0.ps useful.  It is a porting guide
+that summarizes the new features and discusses how to deal with the
+changes in Tk 4.0 that are not backwards compatible.
+
+There is also an official home for Tcl and Tk on the Web:
+	http://www.smli.com/research/tcl
+These Web pages include release updates, reports on bug fixes and porting
+issues, HTML versions of the manual pages, and pointers to many other
+Tcl/Tk Web pages at other sites.  Check them out!
+
+3. Compiling and installing Tk
+------------------------------
+
+This release contains everything you should need to compile and run
+Tk under UNIX, Macintoshes, and PCs (either Windows NT, Windows 95,
+or Win 3.1 with Win32s).
+
+Before trying to compile Tk you should do the following things:
+
+    (a) Check for a binary release.  Pre-compiled binary releases are
+        available now for PCs and Macintoshes, and several flavors of
+        UNIX.  Binary releases are much easier to install than source
+        releases.  To find out whether a binary release is available for
+        your platform, check the home page for the Sun Tcl/Tk project
+        (http://www.sunlabs.com/research/tcl) and also check in the FTP
+        directory from which you retrieved the base distribution.
+
+    (b) Make sure you have the most recent patch release.  Look in the
+	FTP directory from which you retrieved this distribution to see
+	if it has been updated with patches.  Patch releases fix bugs
+	without changing any features, so you should normally use the
+	latest patch release for the version of Tk that you want. 
+	Patch releases are available in two forms.  A file like
+	tk8.0p1.tar.Z is a complete release for patch level 1 of Tk
+	version 8.0.  If there is a file with a higher patch level than
+	this release, just fetch the file with the highest patch level
+	and use it.
+
+	Patches are also available in the form of patch files that just
+	contain the changes from one patch level to another.  These
+	files have names like tk8.0p1.patch, tk8.0p2.patch, etc.  They
+	may also have .gz or .Z extensions to indicate compression.  To
+	use one of these files, you apply it to an existing release with
+	the "patch" program.  Patches must be applied in order:
+	tk8.0p1.patch must be applied to an unpatched Tk 8.0 release
+	to produce a Tk 8.0p1 release;  tk8.0p2.patch can then be
+	applied to Tk 8.0p1 to produce Tk 8.0p2, and so on. To apply an
+	uncompressed patch file such as tk8.0p1.patch, invoke a shell
+	command like the following from the directory containing this
+	file:
+	    patch -p < tk8.0p1.patch
+	If the patch file has a .gz extension, it was compressed with
+	gzip.  To apply it, invoke a command like the following:
+	    gunzip -c tk8.0p1.patch.gz | patch -p
+	If the patch file has a .Z extension, it was compressed with
+	compress.  To apply it, invoke a command like the following:
+	    zcat tk8.0p1.patch.Z | patch -p
+	If you're applying a patch to a release that has already been
+	compiled, then before applying the patch you should cd to the
+	"unix" subdirectory and type "make distclean" to restore the
+	directory to a pristine state.
+
+Once you've done this, change to the "unix" subdirectory if you're
+compiling under UNIX, "win" if you're compiling under Windows, or
+"mac" if you're compiling on a Macintosh.  Then follow the instructions
+in the README file in that directory for compiling Tk, installing it,
+and running the test suite.
+
+4. Getting started
+------------------
+
+The best way to get started with Tk is by reading one of the introductory
+books.
+
+The subdirectory library/demos contains a number of pre-canned scripts
+that demonstrate various features of Tk.  See the README file in the
+directory for a description of what's available.  The file
+library/demos/widget is a script that you can use to invoke many individual
+demonstrations of Tk's facilities, see the code that produced the demos,
+and modify the code to try out alternatives.
+
+5. Summary of changes in Tk 8.0
+-------------------------------
+
+Here is a list of the most important new features in Tk 8.0.  The
+release also includes several smaller feature changes and bug fixes. 
+See the "changes" file for a complete list of all changes.
+
+    1. Native look and feel.  The widgets have been rewritten to provide
+    (nearly?) native look and feel on the Macintosh and PC.  Many
+    widgets, including scrollbars, menus, and the button family, are
+    implemented with native platform widgets.  Others, such as entries
+    and texts, have been modified to emulate native look and feel. 
+    These changes are backwards compatible except that (a) some
+    configuration options are now ignored on some platforms and (b) you
+    must use the new menu mechanism described below to native look and
+    feel for menus.
+
+    2. There is a new interface for creating menus, where a menubar is
+    implemented as a menu widget instead of a frame containing menubuttons.
+    The -menu option for a toplevel is used to specify the name of the
+    menubar; the menu will be displayed *outside* the toplevel using
+    different mechanisms on each platform (e.g. on the Macintosh the menu
+    will appear at the top of the screen).  See the menu demos in the
+    widget demo for examples.  The old style of menu still works, but
+    does not provide native look and feel.  Menus have several new
+    features:
+        - New "-columnbreak" and "-hideMargin" options make it possible
+	  to create multi-column menus.
+	- It is now possible to manipulate the Apple and Help menus on
+	  the Macintosh, and the system menu on Windows.  It is also
+	  possible to have a right justified Help menu on Unix.
+	- Menus now issue the virtual event <<MenuSelect>> whenever the
+	  current item changes.  Applications can use this to generate
+	  help messages.
+        - There is a new "-direction" option for menubuttons, which
+	  controls where the menu pops up revenues to the button.
+
+    3. The font mechanism in Tk has been completely reworked:
+	- Font names need not be nasty X LFDs: more intuitive names
+	  like {Times 12 Bold} can also be used.  See the manual entry
+	  font.n for details.
+	- Font requests always succeed now.  If the requested font is
+	  not available, Tk finds the closest available font and uses
+	  that one.
+	- Tk now supports named fonts whose precise attributes can be
+	  changed dynamically.  If a named font is changed, any widget
+	  using that font updates itself to reflect the change.
+	- There is a new command "font" for creating named fonts and
+	  querying various information about fonts.
+	- There are now officially supported C APIs for measuring and
+	  displaying text.  If you use these APIs now, your code will
+	  automatically handle international text when internationalization
+	  is added to Tk in a future release.  See the manual entries
+	  MeasureChar.3, TextLayout.3, and FontId.3.
+	- The old C procedures Tk_GetFontStruct, Tk_NameOfFontStruct,
+	  and Tk_FreeFontStruct have been replaced with more portable
+	  procedures Tk_GetFont, Tk_NameOfFont, and Tk_FreeFont.
+
+    4. Application embedding.  It is now possible to embedded one Tcl/Tk
+    application inside another, using the -container option on frame
+    widgets and the -use option for toplevel widgets or on the command
+    line for wish.  Embedding should be fully functional under Unix,
+    but the implementation is incomplete on the Macintosh and PC.
+
+    5. Tk now works correctly with Safe-Tcl: it can be loaded into
+    safe interpreters using safe::loadTk.
+
+    6. Text widgets now allow images to be embedded directly in the
+    text without using embedded windows.  This is more efficient and
+    provides smoother scrolling.
+
+    7. Buttons have a new -default option for drawing default rings in
+    a platform-specific manner.
+
+    8. There is a new "gray75" bitmap, and the "gray25" bitmap is now
+    really 25% on (due to an ancient mistake, it had been only 12% on).
+    The Macintosh now supports native bitmaps, including new builtin
+    bitmaps "stop", "caution", and "note", plus the ability to use
+    bitmaps in the application's resource fork.
+
+    9. The "destroy" command now ignores windows that don't exist
+    instead of generating an error.
+
+Tk 8.0 introduces the following incompatibilities that may affect Tcl/Tk
+scripts that worked under Tk 4.2 and earlier releases:
+
+    1. Font specifications such as "Times 12" now interpret the size
+    as points, whereas it used to be pixels (this was actually a bug,
+    since the behavior was documented as points).  To get pixels now,
+    use a negative size such as "Times -12".
+
+    2. The -transient option for menus is no longer supported.  You can
+    achieve the same effect with the -type field.
+
+    3. In the canvas "coords" command, polygons now return only the
+    points that were explicitly specified when the polygon was created
+    (they used to return an extra point if the polygon wasn't originally
+    closed).  Internally, polygons are still closed automatically for
+    purposes of display and hit detection; the extra point just isn't
+    returned by the "coords" command.
+
+    4. The photo image mechanism now uses Tcl_Channels instead of FILEs,
+    in order to make it portable.  FILEs are no longer used anywhere
+    in Tk.  The procedure Tk_FindPhoto now requires an extra "interp"
+    argument in order to fix a bug where images in different interpreters
+    with the same name could get confused.
+
+    5. The procedures Tk_GetFontStruct, Tk_NameOfFontStruct,
+    and Tk_FreeFontStruct have been removed.
+
+Note: the new compiler in Tcl 8.0 may also affect Tcl/Tk scripts; check
+the Tcl documentation for information on incompatibilities introduced by
+Tcl 8.0.
+
+6. Tcl/Tk newsgroup
+-------------------
+
+There is a network news group "comp.lang.tcl" intended for the exchange
+of information about Tcl, Tk, and related applications.  Feel free to use
+this newsgroup both for general information questions and for bug reports.
+We read the newsgroup and will attempt to fix bugs and problems reported
+to it.
+
+When using comp.lang.tcl, please be sure that your e-mail return address
+is correctly set in your postings.  This allows people to respond directly
+to you, rather than the entire newsgroup, for answers that are not of
+general interest.  A bad e-mail return address may prevent you from
+getting answers to your questions.  You may have to reconfigure your news
+reading software to ensure that it is supplying valid e-mail addresses.
+
+7. Mailing lists
+----------------
+
+A couple of  Mailing List have been set up to discuss Macintosh or
+Windows related Tcl issues.  In order to use these Mailing Lists you
+must have access to the internet.  If you have access to the WWW the
+home pages for these mailing lists are located at the following URLs:
+
+	http://www.sunlabs.com/research/tcl/lists/mactcl-list.html
+
+		-and-
+
+	http://www.sunlabs.com/research/tcl/lists/wintcl-list.html
+
+The home pages contain information about the lists and an HTML archive
+of all the past messages on the list.  To subscribe send a message to:
+	
+	listserv@sunlabs.sun.com
+	
+In the body of the message (the subject will be ignored) put:
+	
+	subscribe mactcl Joe Blow
+	
+Replacing Joe Blow with your real name, of course.  (Use wintcl
+instead of mactcl if your interested in the Windows list.)  If you
+would just like to receive more information about the list without
+subscribing but the line:
+
+	information mactcl
+	
+in the body instead (or wintcl).
+
+8. Tcl/Tk contributed archive
+--------------------------
+
+Many people have created exciting packages and applications based on Tcl
+and/or Tk and made them freely available to the Tcl community.  An archive
+of these contributions is kept on the machine ftp.neosoft.com.  You
+can access the archive using anonymous FTP;  the Tcl contributed archive is
+in the directory "/pub/tcl".  The archive also contains several FAQ
+("frequently asked questions") documents that provide solutions to problems
+that are commonly encountered by TCL newcomers.
+
+9. Support and bug fixes
+------------------------
+
+We're very interested in receiving bug reports and suggestions for
+improvements.  We prefer that you send this information to the
+comp.lang.tcl newsgroup rather than to any of us at Sun.  We'll see
+anything on comp.lang.tcl, and in addition someone else who reads 
+comp.lang.tcl may be able to offer a solution.  The normal turn-around
+time for bugs is 3-6 weeks.  Enhancements may take longer and may not
+happen at all unless there is widespread support for them (we're
+trying to slow the rate at which Tk turns into a kitchen sink).  It's
+very difficult to make incompatible changes to Tcl at this point, due
+to the size of the installed base.
+
+When reporting bugs, please provide a short wish script that we can
+use to reproduce the bug.  Make sure that the script runs with a
+bare-bones wish and doesn't depend on any extensions or other
+programs, particularly those that exist only at your site.  Also,
+please include three additional pieces of information with the
+script:
+    (a) how do we use the script to make the problem happen (e.g.
+	what things do we click on, in what order)?
+    (b) what happens when you do these things (presumably this is
+        undesirable)?
+    (c) what did you expect to happen instead?
+
+The Tcl/Tk community is too large for us to provide much individual
+support for users.  If you need help we suggest that you post questions
+to comp.lang.tcl.  We read the newsgroup and will attempt to answer
+esoteric questions for which no-one else is likely to know the answer.
+In addition, Tcl/Tk support and training are available commercially from
+NeoSoft (info@neosoft.com), Computerized Processes Unlimited
+(gwl@cpu.com), and Data Kinetics (education@dkl.com).
+
+10. Release organization
+------------------------
+
+Each Tk release is identified by two numbers separated by a dot, e.g.
+3.2 or 3.3.  If a new release contains changes that are likely to break
+existing C code or Tcl scripts then the major release number increments
+and the minor number resets to zero: 3.0, 4.0, etc.  If a new release
+contains only bug fixes and compatible changes, then the minor number
+increments without changing the major number, e.g. 3.1, 3.2, etc.  If
+you have C code or Tcl scripts that work with release X.Y, then they
+should also work with any release X.Z as long as Z > Y.
+
+Alpha and beta releases have an additional suffix of the form a2 or b1.
+For example, Tk 3.3b1 is the first beta release of Tk version 3.3,
+Tk 3.3b2 is the second beta release, and so on.  A beta release is an
+initial version of a new release, used to fix bugs and bad features
+before declaring the release stable.  An alpha release is like a beta
+release, except it's likely to need even more work before it's "ready
+for prime time".  New releases are normally preceded by one or more
+alpha and beta releases.  We hope that lots of people will try out
+the alpha and beta releases and report problems.  We'll make new alpha/
+beta releases to fix the problems, until eventually there is a beta
+release that appears to be stable.  Once this occurs we'll make the
+final release.
+
+We can't promise to maintain compatibility among alpha and beta releases.
+For example, release 4.1b2 may not be backward compatible with 4.1b1, even
+though the final 4.1 release will be backward compatible with 4.0.  This
+allows us to change new features as we find problems during beta testing.
+We'll try to minimize incompatibilities between beta releases, but if a
+major problem turns up then we'll fix it even if it introduces an
+incompatibility.  Once the official release is made then there won't
+be any more incompatibilities until the next release with a new major
+version number.
+
+Patch releases have a suffix such as p1 or p2.  These releases contain
+bug fixes only.  A patch release (e.g Tk 4.1p2) should be completely
+compatible with the base release from which it is derived (e.g. Tk
+4.1), and you should normally use the highest available patch release.