Initial revision

1 files changed, 381 insertions, 0 deletions

diff --git a/README b/README
new file mode 100644
index 0000000..13eed9c
--- /dev/null
+++ b/README
@@ -0,0 +1,381 @@
+Tcl
+
+SCCS: @(#) README 1.52 97/11/20 12:43:16
+
+1. Introduction
+---------------
+
+This directory and its descendants contain the sources and documentation
+for Tcl, an embeddable scripting language.  The information here
+corresponds to release 8.0p2, which is the second patch update for Tcl
+8.0. Tcl 8.0 is a major new release that replaces the core of the
+interpreter with an on-the-fly bytecode compiler to improve execution
+speed.  It also includes several other new features such as namespaces
+and binary I/O, plus many bug fixes.  The compiler introduces a few
+incompatibilities that may affect existing Tcl scripts; the
+incompatibilities are relatively obscure but may require modifications
+to some old scripts before they can run with this version. The compiler
+introduces many new C-level APIs, but the old APIs are still supported.
+See below for more details.  This patch release fixes various bugs in
+Tcl 8.0; there are no feature changes relative to Tcl 8.0.
+
+2. Documentation
+----------------
+
+The best 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
+
+    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 Tcl.  Files with extension ".1" are for programs (for
+example, tclsh.1); files with extension ".3" are for C library procedures;
+and files with extension ".n" describe Tcl commands.  The file "doc/Tcl.n"
+gives a quick summary of the Tcl language syntax.  To print any of the man
+pages, cd to the "doc" directory and invoke your favorite variant of
+troff using the normal -man macros, for example
+
+		ditroff -man Tcl.n
+
+to print Tcl.n.  If Tcl 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 Tcl
+
+There is also an official home for Tcl and Tk on the Web:
+	http://sunscript.sun.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!
+
+3. Compiling and installing Tcl
+-------------------------------
+
+This release contains everything you should need to compile and run
+Tcl under UNIX, Macintoshes, and PCs (either Windows NT, Windows 95,
+or Win 3.1 with Win32s).
+
+Before trying to compile Tcl you should do the following things:
+
+    (a) Check for a binary release.  Pre-compiled binary releases are
+        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 home page for SunScript
+        (http://sunscript.sun.com) under "Tech Corner".  Also, check in
+        the FTP directory from which you retrieved the base
+        distribution.  Some of the binary releases are available freely,
+        while others are for sale.
+
+    (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 Tcl that you want. 
+	Patch releases are available in two forms.  A file like
+	tcl8.0p2.tar.Z is a complete release for patch level 2 of Tcl
+	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 will have names like tcl8.0p1.patch, tcl8.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:
+	tcl8.0p1.patch must be applied to an unpatched Tcl 8.0 release
+	to produce a Tcl 8.0p1 release;  tcl8.0p2.patch can then be
+	applied to Tcl8.0p1 to produce Tcl 8.0p2, and so on. To apply an
+	uncompressed patch file such as tcl8.0p1.patch, invoke a shell
+	command like the following from the directory containing this
+	file:
+	    patch -p < tcl8.0p1.patch
+	If the patch file has a .gz extension, invoke a command like the
+	following:
+	    gunzip -c tcl8.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 tcl8.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 Tcl, installing it,
+and running the test suite.
+
+4. Summary of changes in Tcl 8.0
+--------------------------------
+
+Here are the most significant changes in Tcl 8.0.  In addition to these
+changes, there are several smaller changes and bug fixes.  See the file
+"changes" for a complete list of all changes.
+
+    1. Bytecode compiler.  The core of the Tcl interpreter has been
+    replaced with an on-the-fly compiler that translates Tcl scripts to
+    byte codes; a new interpreter then executes the byte codes. In
+    earlier versions of Tcl, strings were used as a universal
+    representation;  in Tcl 8.0 strings are replaced with Tcl_Obj
+    structures ("objects") that can hold both a string value and an
+    internal form such as a binary integer or compiled bytecodes.  The
+    new objects make it possible to store information in efficient
+    internal forms and avoid the constant translations to and from
+    strings that occurred with the old interpreter.  We have not yet
+    converted all of Tcl to take full advantage of the compiler and
+    objects and have not converted any of Tk yet, but even so you
+    should see speedups of 2-3x on many programs and you may see
+    speedups as much as 10-20x in some cases (such as code that
+    manipulates long lists).  Future releases should achieve even
+    greater speedups.  The compiler introduces only a few minor changes
+    at the level of Tcl scripts, but it introduces many new C APIs for
+    managing objects.  See, for example, the manual entries doc/*Obj*.3.
+
+    2. Namespaces.  There is a new namespace mechanism based on the
+    namespace implementation by Michael McLennan of Lucent Technologies.
+    This includes new "namespace" and "variable" commands.  There are
+    many new C APIs associated with namespaces, but they will not be
+    exported until Tcl 8.1.  Note: the syntax of the namespace command
+    has been changed slightly since the b1 release.  See the changes
+    file for details.
+
+    3. Binary I/O.  The new object system in Tcl 8.0 supports binary
+    strings (internally, strings are counted in addition to being null
+    terminated).  There is a new "binary" command for inserting and
+    extracting data to/from binary strings.  Commands such as "puts",
+    "gets", and "read" commands now operate correctly on binary data. 
+    There is a new variable tcl_platform(byteOrder) to identify the
+    native byte order for the current host.
+
+    4. Random numbers.  The "expr" command now contains a random number
+    generator, which can be accessed via the "rand()" and "srand()" math
+    functions.
+
+    5. Safe-Tcl enhancements.  There is a new "hidden command"
+    mechanism, implemented with the Tcl commands "interp hide", "interp
+    expose", "interp invokehidden", and "interp hidden" and the C APIs
+    Tcl_HideCommand and Tcl_ExposeCommand.  There is now support for
+    safe packages and extension loading, including new library
+    procedures such as safe::interpCreate (see the manual entry safe.n
+    for details).
+
+    6. There is a new package "registry" available under Windows for
+    accessing the Windows registry.
+
+    7. There is a new command "file attributes" for getting and setting
+    things like permissions and owner.  There is also a new command
+    "file nativename" for getting back the platform-specific name for a
+    particular file.
+
+    8. There is a new "fcopy" command to copy data between channels. 
+    This replaces and improves upon the not-so-secret unsupported old
+    command "unsupported0".
+
+    9. There is a new package "http" for doing GET, POST, and HEAD
+    requests via the HTTP/1.0 protocol.  See the manual entry http.n
+    for details.
+
+    10. There are new library procedures for finding word breaks in
+    strings.  See the manual entry library.n for details.
+
+    11. There are new C APIs Tcl_Finalize (for cleaning up before
+    unloading the Tcl DLL) and Tcl_Ungets for pushing bytes back into a
+    channel's input buffer.
+
+    12. Tcl now supports serial I/O devices on Windows and Unix, with a
+    new fconfigure -mode option.  The Windows driver does not yet
+    support event-driven I/O.
+
+    13. The lsort command has new options -dictionary and -index.  The
+    -index option allows for very rapid sorting based on an element
+    of a list.
+
+    14. The event notifier has been completely rewritten (again).  It
+    should now allow Tcl to use an external event loop (like Motif's)
+    when it is embedded in other applications.  No script-level
+    interfaces have changed, but many of the C APIs have.
+
+Tcl 8.0 introduces the following incompatibilities that may affect Tcl
+scripts that worked under Tcl 7.6 and earlier releases:
+
+    1. Variable and command names may not include the character sequence
+    "::" anymore: this sequence is now used as a namespace separator.
+
+    2. The semantics of some Tcl commands have been changed slightly to
+    maximize performance under the compiler.  These incompatibilities
+    are documented on the Web so that we can keep the list up-to-date.
+    See the URL http://www.sunlabs.com/research/tcl/compiler.html.
+
+    3. 2-digit years are now parsed differently by the "clock" command
+    to handle year 2000 issues better (years 00-38 are treated as
+    2000-2038 instead of 1900-1938).
+
+    4. The old Macintosh commands "cp", "mkdir", "mv", "rm", and "rmdir"
+    are no longer supported; all of these features are now available on
+    all platforms via the "file" command.
+
+    5. The variable tcl_precision is now shared between interpreters
+    and defaults to 12 digits instead of 6; safe interpreters cannot
+    modify tcl_precision.  The new object system in Tcl 8.0 causes
+    floating-to-string conversions (and the associated rounding) to
+    occur much less often than in Tcl 7.6, which can sometimes cause
+    behavioral changes.
+
+    6. The C APIs associated with the notifier have changed substantially.
+
+    7. The procedures Tcl_CreateModalTimeout and Tcl_DeleteModalTimeout
+    have been removed.
+
+    8. Tcl_CreateFileHandler and Tcl_DeleteFileHandler now take Unix
+    fd's and are only supported on the Unix platform
+
+    9. The C APIs for creating channel drivers have changed as part of
+    the new notifier implementation.  The Tcl_File interfaces have been
+    removed.  Tcl_GetChannelFile has been replaced with
+    Tcl_GetChannelHandle.  Tcl_MakeFileChannel now takes a platform-
+    specific file handle.  Tcl_DriverGetOptionProc procedures now take
+    an additional interp argument.
+
+5. Tcl 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
+the 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.
+
+6. 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.
+
+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 put the line:
+
+	information mactcl
+	
+in the body instead (or wintcl).
+
+8. 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 Tcl 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 tclsh script that we can
+use to reproduce the bug.  Make sure that the script runs with a
+bare-bones tclsh 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 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 support and training are available commercially from
+NeoSoft (info@neosoft.com), Computerized Processes Unlimited
+(gwl@cpu.com), and Data Kinetics (education@dkl.com).
+
+9. Tcl version numbers
+----------------------
+
+Each Tcl release is identified by two numbers separated by a dot, e.g.
+6.7 or 7.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: 6.0, 7.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. 7.1, 7.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, Tcl 7.0b1 is the first beta release of Tcl version 7.0,
+Tcl 7.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 7.1b2 may not be backward compatible with 7.1b1, even
+though the final 7.1 release will be backward compatible with 7.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 Tcl 7.6p2) should be completely
+compatible with the base release from which it is derived (e.g. Tcl
+7.6), and you should normally use the highest available patch release.