README:  Tcl

	Tcl is maintained, enhanced, and distributed freely as a
	service to the Tcl community by Scriptics Corporation.

RCS: @(#) $Id: README,v 1.15 1999/02/26 22:25:04 hershey Exp $

Contents
--------
    1. Introduction
    2. Documentation
    3. Compiling and installing Tcl
    4. Summary of changes in Tcl 8.0
    5. Development tools
    6. Tcl newsgroup
    7. Tcl contributed archive
    8. Tcl Resource Center
    9. Mailing lists
    10. Support and bug fixes
    11. Tcl version numbers

1. Introduction
---------------

Tcl provides a powerful platform for creating integration
applications that tie together diverse applications, protocols,
devices, and frameworks.  When paired with the Tk toolkit, Tcl
provides the fastest and most powerful way to create GUI applications
that run on PCs, Unix, and the Macintosh.  Tcl can also be used for a
variety of web-related tasks and for creating powerful command
languages for applications.

This directory contains the sources and documentation for Tcl.  The
information here corresponds to release 8.0.5, which is the fifth
patch update for Tcl 8.0. This patch provides bug fixes and
incorporates user-contributed patches.  Please check the changes file
for details.

Tcl 8.0 is a major 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.

Tcl 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 Tcl is to read about Tcl 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

    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

Other books are listed at
http://www.scriptics.com/resource/doc/books/

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!

2a. Unix Documentation
----------------------

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 on Unix, 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

2b. Windows Documentation
-------------------------

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 | Tcl | Tcl Help

3. Compiling and installing Tcl
-------------------------------

This release contains everything you should need to compile and run
Tcl under UNIX, PCs (either Windows NT, Windows 95, or Win 3.1 with
Win32s), and Macintoshes.

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 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
	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. 

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 Cadence.
    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 following URL:

	http://www.scriptics.com/doc/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. Development tools
--------------------

A high quality set of commercial development tools is now available to
accelerate your Tcl application development.  Scriptics' TclPro
product provides a debugger, static code checker, packaging utility,
and bytecode compiler.  Visit the Scriptics Web site at:

	http://www.scriptics.com/tclpro

for more information on TclPro and for a free 30-day evaluation
download.

6. 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.

7. 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.

8. 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".

9. Mailing lists
----------------

A couple of  Mailing List have been set up to discuss Macintosh or
Windows related Tcl issues.  To subscribe send a message to:
	
	wintcl-request@tclconsortium.org
	mactcl-request@tclconsortium.org
	
In the body of the message (the subject will be ignored) put:
	
	subscribe mactcl Joe Smith
	
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 put the line:

	information mactcl
	
in the body instead (or wintcl).

10. Support and bug fixes
-------------------------

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 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?

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:

	http://www.scriptics.com/resource/commercial/training

11. Tcl version numbers
-----------------------

You can test the current version of Tcl by examining the
tcl_version and tcl_patchLevel variables.  The tcl_patchLevel
variable follows the naming rules outlined below (e.g., 8.0.5).
The tcl_version just has the major.minor numbers in it (e.g., 8.0)

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.

(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
tcl_patchLevel.  Patch releases normally contain bug fixes only.  A
patch release (e.g Tcl 8.0.5) should be completely compatible with the
base release from which it is derived (e.g. Tcl 8.0), and you should
normally use the highest available patch release.

12. 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.
