updated for 8.0.5 with John O's changes.

FossilOrigin-Name: 1b24f15bfac517cfb622c1e07f6afc56650aeb00

1 files changed, 206 insertions, 122 deletions

diff --git a/README b/README
index 56ef91c..970e9e7 100644
--- a/README
+++ b/README
@@ -1,6 +1,24 @@
-The Tk Toolkit
-
-RCS: @(#) $Id: README,v 1.11 1999/02/09 03:46:27 stanton Exp $
+README:  Tk
+
+	Tk is maintained, enhanced, and distributed freely as a
+	service to the Tcl community by Scriptics Corporation.
+
+RCS: @(#) $Id: README,v 1.12 1999/02/17 02:05:30 hershey Exp $
+
+Contents
+--------
+    1. Introduction
+    2. Documentation
+    3. Compiling and installing Tk
+    4. Getting started
+    5. Summary of changes in Tcl 8.0
+    6. Development tools
+    7. Tcl newsgroup
+    8. Tcl contributed archive
+    9. Tcl Resource Center
+    10. Mailing lists
+    11. Support and bug fixes
+    12. Tk version numbers
 
 1. Introduction
 ---------------
@@ -21,11 +39,21 @@ 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.
 
+Tk is a freely available open source package.  You can do virtually
+anything you like with it, such as modifying it, redistributing it ,
+and selling it either in whole or in part.  See the file
+"license.terms" for complete information.
+
 2. Documentation
 ----------------
 
-The best way to get started with Tk is to read one of the introductory
-books on Tcl and Tk:
+The best way to get started with Tk is to read about Tk on the
+Scriptics Web site at:
+
+	http://www.scriptics.com/scripting
+
+Another good way to get started with Tcl is to read one of the
+introductory books on Tcl:
 
     Practical Programming in Tcl and Tk, 2nd Edition, by Brent Welch,
     Prentice-Hall, 1997, ISBN 0-13-616830-2
@@ -38,7 +66,23 @@ books on Tcl and Tk:
 
 Other books are listed at
 http://www.scriptics.com/resource/doc/books/
-http://www.tclconsortium.org/resources/books.html
+
+There is also an official home for Tcl and Tk on the Scriptics Web site:
+
+	http://www.scriptics.com
+
+These Web pages include information about the latest releases, products
+related to Tcl and Tk, 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!
+
+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.
+
+2a. Unix Documentation
+----------------------
 
 The "doc" subdirectory in this release contains a complete set of
 reference manual entries for Tk.  Files with extension ".1" are for
@@ -55,33 +99,33 @@ 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.
+2b. Windows Documentation
+-------------------------
 
-There is also an official home for Tcl and Tk on the Web:
-	http://www.scriptics.com/
-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!
+The "doc/help" subdirectory in this release contains a complete set of
+Windows help files for TclPro.  Once you install this Tcl release, a
+shortcut to the Windows help Tcl documentation will appear in the
+"Start" menu:
+
+	Start | Programs | Tk | Tk Help
 
 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 Windows 98.)
+Tk under UNIX, PCs (either Windows NT, Windows 95, or Win 3.1 with
+Win32s), and Macintoshes.
 
 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 Tcl/Tk
-        (http://www.scriptics.com/) and also check in the FTP
-        directory from which you retrieved the base distribution.
+        available now for PCs, 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 Scriptics Tcl Resource Center
+        (http://www.scriptics.com/resource).  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
@@ -98,15 +142,16 @@ 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 best way to get started with Tk is by reading one of the
+introductory books.  See the documentation section above for more
+details.
 
 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.
+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
 -------------------------------
@@ -222,142 +267,181 @@ 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
--------------------
+6. Development tools
+--------------------
+
+A high quality set of commercial development tools is now available to
+accelerate your Tk application development.  Scriptics' TclPro
+product provides a debugger, static code checker, packaging utility,
+and bytecode compiler.  Visit the Scriptics Web site at:
 
-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.
+	http://www.scriptics.com/tclpro
 
-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.
+for more information on TclPro and for a free 30-day evaluation
+download.
 
-7. Mailing lists
+7. Tcl newsgroup
 ----------------
 
+There is a network news group "comp.lang.tcl" intended for the
+exchange of information about Tcl, Tk, and related applications.  The
+newsgroup is a greata place to ask general information questions.  For
+bug reports, please see the "Support and bug fixes" section below.
+
+8. Tcl 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. Tcl Resource Center
+----------------------
+
+Visit http://www.scriptics.com/resource/ to see an annotated index of
+many Tcl resources available on the World Wide Web.  This includes
+papers, books, and FAQs, as well as development tools, extensions,
+applications, binary releases, and patches.  You can also recommend
+additional URLs for the resource center using the forms labeled "Add a
+Resource".
+
+10. 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. To subscribe send a message to:
+Windows related Tcl issues.  To subscribe send a message to:
 	
-	wintcl-request@tclconsorium.org
-	or
-	mactcl-request@tclconsorium.org
+	wintcl-request@tclconsortium.org
+	mactcl-request@tclconsortium.org
 	
 In the body of the message (the subject will be ignored) put:
 	
-	subscribe mactcl Joe Blow
+	subscribe mactcl Joe Smith
 	
-Replacing Joe Blow with your real name, of course.  (Use wintcl
+Replacing Joe Smith 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:
+subscribing put the line:
 
 	information mactcl
 	
 in the body instead (or wintcl).
 
-8. Tcl/Tk contributed archive
---------------------------
+11. Support and bug fixes
+-------------------------
 
-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.
+Scriptics is very interested in receiving bug reports, patches, and
+suggestions for improvements.  We prefer that you send this
+information to us via the bug form on the Scriptics Web site, rather
+than emailing us directly.  The bug form is at:
+
+	http://www.scriptics.com/support/bugForm.html
+
+The bug form was designed to give uniform structure to bug reports as
+well as to solicit enough information to minimize followup questions.
+The bug form also includes an option to automatically post your report
+on comp.lang.tcl.  We strongly recommend that you select this option
+because someone else who reads comp.lang.tcl may be able to offer a
+solution.
+
+When reporting bugs, please provide full information about the Tcl/Tk
+version and the platform on which you are running Tcl/Tk.  Also,
+please include 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:
 
-9. Tcl Resource Center
-----------------------
-Visit http://www.scritics.com/resource/ to see an annotated index of
-many Tcl resources available on the World Wide Web.  This includes
-papers, books, and FAQs, as well as extensions, applications, binary
-releases, and patches.  You can contribute patches by sending them
-to <patches@scriptics.com>.  You can also recommend more URLs for the
-resource center using the forms labeled "Add a Resource".
- 
-10. 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 Scriptics.  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
-Scriptics (info@scriptics.com), NeoSoft (info@neosoft.com),
-Computerized Processes Unlimited (gwl@cpu.com),
-and Data Kinetics (education@dkl.com).
+We will log and follow-up on each bug, although we cannot promise a
+specific turn-around time.  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 Tcl/Tk turns into a kitchen sink).
+It's very difficult to make incompatible changes to Tcl/Tk at this
+point, due to the size of the installed base.
+
+The Tcl 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 Scriptics at:
+
+	http://www.scriptics.com/training
+
+Also see the following Web site for links to other organizations that
+offer Tcl/Tk training:
 
-11. Release organization
-------------------------
+	http://www.scriptics.com/resource/commercial/training
 
-The version numbers described below are available to Tcl scripts
-as the tk_version and tk_patchLevel Tcl variables.
+12. Tk version numbers
+----------------------
+
+You can test the current version of Tk by examining the
+tk_version and tk_patchLevel variables.  The tk_patchLevel
+variable follows the naming rules outlined below (e.g., 8.0.5).
+The tk_version just has the major.minor numbers in it (e.g., 8.0)
 
 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
+3.6 or 4.0.  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
+increments without changing the major number, e.g. 4.1, 4.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.
+Alpha and beta releases have an additional suffix of the form a2 or
+b1.  For example, Tk 4.0b1 is the first beta release of Tk version
+4.0, Tk 4.0b2 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
+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 used to have a suffix such as p1 or p2.  Now we use
-a 3-part version number: major.minor.patchlevel. (e.g., 8.0.3)
-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.
+(Note: This compatibility is true for Tcl scripts, but historically
+the Tcl C APIs have changed enough between releases that you may need
+to work a bit to upgrade extensions.)
+
+Patch releases now have a suffix such as ".4" or ".5".  Prior to
+version 8.0.3, patch releases had the suffix "p1" or "p2".  So, the
+8.0 release went to 8.0p1, 8.0p2, 8.0.3, 8.0.4, and 8.0.5.  The alphas
+and betas continue to use the 'a' and 'b' letters in their
+tk_patchLevel.  Patch releases normally contain bug fixes only.  A
+patch release (e.g Tk 8.0.5) should be completely compatible with the
+base release from which it is derived (e.g. Tk 8.0), and you should
+normally use the highest available patch release.
+
+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.
+
+13. Thank You
+-------------
+
+We'd like to express our thanks to the Tcl community for all the
+helpful suggestions, bug reports, and patches we have received.
+Tcl/Tk has improved vastly and will continue to do so with your help.