Initial revision

1 files changed, 518 insertions, 0 deletions

diff --git a/win/README.binary b/win/README.binary
new file mode 100644
index 0000000..beb6ff2
--- /dev/null
+++ b/win/README.binary
@@ -0,0 +1,518 @@
+Tcl/Tk 8.0.3 for Windows, Binary Distribution

+

+%Z% $Id: README.binary,v 1.1 1998/08/31 16:31:53 stanton Exp $ 

+

+1. Introduction

+--------------- 

+

+This directory contains the binary distribution of Tcl/Tk 8.0.3 for

+Windows.  It was compiled with Microsoft Visual C++ 5.0 using Win32

+API, so that it will run under Windows NT and Windows 95.  The

+information here corresponds to release 8.0.  This patch provides

+compatibility with [incr Tcl] 3.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, plus it adds a few minor

+features to support the TclPro 1.0 tool set and [incr Tcl] 3.0.

+Please check the changes file in the source release for details.

+

+This release also corresponds to Tk 8.0.3.  This 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.3 that affect scripts.

+

+Note: with this release the Tk version number skips 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 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/

+http://www.tclconsortium.org/resources/books.html

+

+There is also an official home for Tcl and Tk on the Web:

+	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!

+

+3. Installation

+---------------

+

+The binary release is distributed as a self-extracting archive called

+tcl80.exe.  The setup program which will prompt you for an

+installation directory.  It will create the installation heirarchy

+under the specified directory, and install a wish application icon

+under the program manager group of your choice.

+

+With the 8.0.3 patch release, we are no longer supporting use of

+Tcl with 16-bit versions of Windows.  Microsoft has completely dropped

+support of the Win32s subsystem.  If you still need 16-bit support,

+you can get win32s and the 16-bit thunking dll (tcl1680.dll) from the

+Scriptics web site at ftp://ftp.scriptics.com/pub/tcl/misc.

+

+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

+    loadable security policies, including new library procedures such as

+    tcl_safeCreateInterp.

+

+    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.  Please use the

+    Tcl_CreateChannelHandler interface instead.

+

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

+

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

+

+    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. Known Bugs/Missing Features

+------------------------------

+

+- Blocking "after" commands (e.g. "after 3000") don't work on Win32s.

+- Clock command fails to handle daylight savings time boundaries for

+  things like "last week".

+- Background processes aren't properly detached on NT.

+- File events only work on sockets.

+- Pipes/files/console/serial ports don't support nonblocking I/O.

+- The library cannot be used by two processes at the same time under

+  Win32s.

+- There is no support for custom cursors/application icons.  The core

+  set of X cursors is supported, although you cannot change their color.

+- Stippling of arcs isn't implemented yet.

+- Some "wm" functions don't map to Windows and aren't implemented;

+  others should map, but just aren't implemented.  The worst offenders

+  are the icon manipulation routines.

+- Under Win32s, you can only start one instance of Wish at a time.

+- Color management on some displays doesn't work properly resulting in

+  Tk switching to monochrome mode.

+- Tk seems to fail to draw anything on some Matrox Millenium cards.

+- Send and winfo interps are not currently supported

+- Printing does not work for images (e.g. GIF) on a canvas.

+- Tk_dialog appears in the upper left corner.  This is a symptom of a

+  larger problem with "wm geometry" when applied to unmapped or

+  iconified windows.

+- Some keys don't work on international keyboards.

+- Grabs do not affect native menus or the title bar.

+- PPM images are using the wrong translation mode for writing to

+  files, resulting in CR/LF terminated PPM files.

+- Tk crashes if the display depth changes while it is running.  Tk

+  also doesn't consistently track changes in the system colors.

+

+There may be more that we don't know about, so be sure to submit bug

+reports when you run into problems.  If you have comments or bug

+reports for the Windows version of Tcl, please direct them to:

+

+Scott Stanton

+scott.stanton@eng.sun.com

+

+or post them to the newsgroup comp.lang.tcl.

+

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

+

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

+	

+	wintcl-request@tclconsortium.org

+	mactcl-request@tclconsortium.org

+	

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

+

+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 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 2-4 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).

+

+11. 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 b1 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.

+

+As of 8.0.3, the patch releases use a second . instead of 'p'.  So, the

+8.0 release went to 8.0p1, 8.0p2, and 8.0.3.  The alphas and betas will

+still use the 'a' and 'b' letters in their tcl_patchLevel.

+

+12. Linking against the binary release

+--------------------------------------

+

+In order to link your applications against the .dll files shipped with

+this release, you will need to use the appropriate .lib file for your

+compiler.  In the lib directory of the installation directory, there

+are library files for the Microsoft Visual C++ compiler:

+

+	tcl80vc.lib

+	tk80vc.lib

+

+13. Building dynamically loadable extensions

+--------------------------------------------

+

+Please refer to the example dynamically loadable extension provided on

+our ftp site:

+

+	ftp://ftp.scriptics.com/pub/tcl/misc/example.zip

+

+This archive contains a template that you can use for building

+extensions that will be loadable on Unix, Windows, and Macintosh

+systems.