Check-in Differences

# The "checkoutlist" file is used to support additional version controlled
# administrative files in $CVSROOT/CVSROOT, such as template files.
#
# The first entry on a line is a filename which will be checked out from
# the corresponding RCS file in the $CVSROOT/CVSROOT directory.
# The remainder of the line is an error message to use if the file cannot
# be checked out.
#
# File format:
#
#	[<whitespace>]<filename><whitespace><error message><end-of-line>
#
# comment lines begin with '#'

# The "commitinfo" file is used to control pre-commit checks.
# The filter on the right is invoked with the repository and a list 
# of files to check.  A non-zero exit of the filter program will 
# cause the commit to be aborted.
#
# The first entry on a line is a regular expression which is tested
# against the directory that the change is being committed to, relative
# to the $CVSROOT.  For the first match that is found, then the remainder
# of the line is the name of the filter to run.
#
# If the repository name does not match any of the regular expressions in this
# file, the "DEFAULT" line is used, if it is specified.
#
# If the name "ALL" appears as a regular expression it is always used
# in addition to the first matching regex or "DEFAULT".

# Set this to "no" if pserver shouldn't check system users/passwords
SystemAuth=no

# Set `PreservePermissions' to `yes' to save file status information
# in the repository.
#PreservePermissions=no

# Set `TopLevelAdmin' to `yes' to create a CVS directory at the top
# level of the new working directory when using the `cvs checkout'
# command.
#TopLevelAdmin=no

# This file affects handling of files based on their names.
#
# The -t/-f options allow one to treat directories of files
# as a single file, or to transform a file in other ways on
# its way in and out of CVS.
#
# The -m option specifies whether CVS attempts to merge files.
#
# The -k option specifies keyword expansion (e.g. -kb for binary).
#
# Format of wrapper file ($CVSROOT/CVSROOT/cvswrappers or .cvswrappers)
#
#  wildcard	[option value][option value]...
#
#  where option is one of
#  -f		from cvs filter		value: path to filter
#  -t		to cvs filter		value: path to filter
#  -m		update methodology	value: MERGE or COPY
#  -k		expansion mode		value: b, o, kkv, &c
#
#  and value is a single-quote delimited value.
# For example:
#*.gif -k 'b'

# The "editinfo" file is used to allow verification of logging
# information.  It works best when a template (as specified in the
# rcsinfo file) is provided for the logging procedure.  Given a
# template with locations for, a bug-id number, a list of people who
# reviewed the code before it can be checked in, and an external
# process to catalog the differences that were code reviewed, the
# following test can be applied to the code:
#
#   Making sure that the entered bug-id number is correct.
#   Validating that the code that was reviewed is indeed the code being
#       checked in (using the bug-id number or a seperate review
#       number to identify this particular code set.).
#
# If any of the above test failed, then the commit would be aborted.
#
# Actions such as mailing a copy of the report to each reviewer are
# better handled by an entry in the loginfo file.
#
# One thing that should be noted is the the ALL keyword is not
# supported.  There can be only one entry that matches a given
# repository.

# The "loginfo" file controls where "cvs commit" log information
# is sent.  The first entry on a line is a regular expression which must match
# the directory that the change is being made to, relative to the
# $CVSROOT.  If a match is found, then the remainder of the line is a filter
# program that should expect log information on its standard input.
#
# If the repository name does not match any of the regular expressions in this
# file, the "DEFAULT" line is used, if it is specified.
#
# If the name ALL appears as a regular expression it is always used
# in addition to the first matching regex or DEFAULT.
#
# You may specify a format string as part of the
# filter.  The string is composed of a `%' followed
# by a single format character, or followed by a set of format
# characters surrounded by `{' and `}' as separators.  The format
# characters are:
#
#   s = file name
#   V = old version number (pre-checkin)
#   v = new version number (post-checkin)
#
# For example:
#DEFAULT (echo ""; id; echo %s; date; cat) >> $CVSROOT/CVSROOT/commitlog
# or
#DEFAULT (echo ""; id; echo %{sVv}; date; cat) >> $CVSROOT/CVSROOT/commitlog
^tip (date; cat; (sleep 2; cd /usr/local/web/tip; /usr/bin/cvs -q update -d) &) >> $CVSROOT/CVSROOT/updatelog 2>&1

modules      CVSROOT modules
admin        web/admin
doc.site     web/doc.site
devxchg.site web/devxchg.site
dxc_res.site web/dxc_res.site
site_look    web/site_look
tip          tip

# The "notify" file controls where notifications from watches set by
# "cvs watch add" or "cvs edit" are sent.  The first entry on a line is
# a regular expression which is tested against the directory that the
# change is being made to, relative to the $CVSROOT.  If it matches,
# then the remainder of the line is a filter program that should contain
# one occurrence of %s for the user to notify, and information on its
# standard input.
#
# "ALL" or "DEFAULT" can be used in place of the regular expression.
#
# For example:
#ALL mail %s -s "CVS notification"

# The "rcsinfo" file is used to control templates with which the editor
# is invoked on commit and import.
#
# The first entry on a line is a regular expression which is tested
# against the directory that the change is being made to, relative to the
# $CVSROOT.  For the first match that is found, then the remainder of the
# line is the name of the file that contains the template.
#
# If the repository name does not match any of the regular expressions in this
# file, the "DEFAULT" line is used, if it is specified.
#
# If the name "ALL" appears as a regular expression it is always used
# in addition to the first matching regex or "DEFAULT".

# The "taginfo" file is used to control pre-tag checks.
# The filter on the right is invoked with the following arguments:
#
# $1 -- tagname
# $2 -- operation "add" for tag, "mov" for tag -F, and "del" for tag -d
# $3 -- repository
# $4->  file revision [file revision ...]
#
# A non-zero exit of the filter program will cause the tag to be aborted.
#
# The first entry on a line is a regular expression which is tested
# against the directory that the change is being committed to, relative
# to the $CVSROOT.  For the first match that is found, then the remainder
# of the line is the name of the filter to run.
#
# If the repository name does not match any of the regular expressions in this
# file, the "DEFAULT" line is used, if it is specified.
#
# If the name "ALL" appears as a regular expression it is always used
# in addition to the first matching regex or "DEFAULT".

# The "verifymsg" file is used to allow verification of logging
# information.  It works best when a template (as specified in the
# rcsinfo file) is provided for the logging procedure.  Given a
# template with locations for, a bug-id number, a list of people who
# reviewed the code before it can be checked in, and an external
# process to catalog the differences that were code reviewed, the
# following test can be applied to the code:
#
#   Making sure that the entered bug-id number is correct.
#   Validating that the code that was reviewed is indeed the code being
#       checked in (using the bug-id number or a seperate review
#       number to identify this particular code set.).
#
# If any of the above test failed, then the commit would be aborted.
#
# Actions such as mailing a copy of the report to each reviewer are
# better handled by an entry in the loginfo file.
#
# One thing that should be noted is the the ALL keyword is not
# supported.  There can be only one entry that matches a given
# repository.

TIP:            1
Title:          TIP Index
Version:        $Revision: 1.4 $
Version:        $Revision: 1.3 $
Author:         TIP Editor <[email protected]>
State:          Active
Type:           Informational
Vote:           No voting
Created:        14-Sep-2000
Post-History:

~ Abstract

This TIP contains the index of all TIPs published over the lifetime of
the TCT. It will be continually and automatically updated.

~ Index

#index:

White backgrounds indicate that the TIP is still a draft, yellow
backgrounds highlight TIPs being voted on, and where a TIP has been
rejected, withdrawn or obsoleted its index entry has a dark grey
background.

~ Explanations and How To Submit New TIPs

See [2] for a description of the editorial process a TIP has to go
through and [3] for a description of their structure and the commands
used to write them. You submit a TIP to this archive by emailing it
(preferably in source form) to the TIP editor <[email protected]>
who will check it for following of the guidelines, style and general
relevance to Tcl/Tk before checking it into the CVS archive and notifying
the author, the rest of the Tcl Core Team, and the relevant newsgroups.

~ Copyright

This document has been placed in the public domain.

? tests/http.test__
? tests/httpold.test__
Index: doc/CrtChannel.3
===================================================================
RCS file: /cvsroot/tcl/tcl/doc/CrtChannel.3,v
retrieving revision 1.8
diff -u -r1.8 CrtChannel.3
--- doc/CrtChannel.3	2000/10/06 21:06:08	1.8
+++ doc/CrtChannel.3	2001/02/28 21:20:07
@@ -11,7 +11,7 @@
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
-Tcl_CreateChannel, Tcl_GetChannelInstanceData, Tcl_GetChannelType, Tcl_GetChannelName, Tcl_GetChannelHandle, Tcl_GetChannelMode, Tcl_GetChannelBufferSize, Tcl_SetChannelBufferSize, Tcl_NotifyChannel, Tcl_BadChannelOption, Tcl_ChannelName, Tcl_ChannelVersion, Tcl_ChannelBlockModeProc, Tcl_ChannelCloseProc, Tcl_ChannelClose2Proc, Tcl_ChannelInputProc, Tcl_ChannelOutputProc, Tcl_ChannelSeekProc, Tcl_ChannelSetOptionProc, Tcl_ChannelGetOptionProc, Tcl_ChannelWatchProc, Tcl_ChannelGetHandleProc, Tcl_ChannelFlushProc, Tcl_ChannelHandlerProc, Tcl_IsChannelShared, Tcl_IsChannelRegistered, Tcl_CutChannel, Tcl_SpliceChannel, Tcl_IsChannelExisting, Tcl_ClearChannelHandlers \- procedures for creating and manipulating channels
+Tcl_CreateChannel, Tcl_GetChannelInstanceData, Tcl_GetChannelType, Tcl_GetChannelName, Tcl_GetChannelHandle, Tcl_GetChannelMode, Tcl_GetChannelBufferSize, Tcl_SetChannelBufferSize, Tcl_NotifyChannel, Tcl_BadChannelOption, Tcl_ChannelName, Tcl_ChannelVersion, Tcl_ChannelBlockModeProc, Tcl_ChannelCloseProc, Tcl_ChannelClose2Proc, Tcl_ChannelInputProc, Tcl_ChannelOutputProc, Tcl_ChannelSeekProc, Tcl_ChannelSetOptionProc, Tcl_ChannelGetOptionProc, Tcl_ChannelWatchProc, Tcl_ChannelGetHandleProc, Tcl_ChannelFlushProc, Tcl_ChannelHandlerProc, Tcl_IsChannelShared, Tcl_IsChannelRegistered, Tcl_CutChannel, Tcl_SpliceChannel, Tcl_IsChannelExisting, Tcl_ClearChannelHandlers, Tcl_GetChannelThread \- procedures for creating and manipulating channels
 .SH SYNOPSIS
 .nf
 \fB#include <tcl.h>\fR
@@ -31,6 +31,11 @@
 int
 \fBTcl_GetChannelHandle\fR(\fIchannel, direction, handlePtr\fR)
 .sp
+.VS 8.4
+Tcl_ThreadId
+\fBTcl_GetChannelThread\fR(\fIchannel\fR)
+.VE
+.sp
 int
 \fBTcl_GetChannelBufferSize\fR(\fIchannel\fR)
 .sp
@@ -215,6 +220,12 @@
 then \fBTCL_ERROR\fR is returned instead.  Different channel drivers
 will return different types of handle.  Refer to the manual entries
 for each driver to determine what type of handle is returned.
+.VS 8.4
+.PP
+\fBTcl_GetChannelThread\fR returns the id of the thread currently managing
+the specified \fIchannel\fR. This allows channel drivers to send their file
+events to the correct event queue even for a multi-threaded core.
+.VE
 .PP
 \fBTcl_GetChannelMode\fR returns an OR-ed combination of \fBTCL_READABLE\fR
 and \fBTCL_WRITABLE\fR, indicating whether the channel is open for input
Index: generic/tcl.decls
===================================================================
RCS file: /cvsroot/tcl/tcl/generic/tcl.decls,v
retrieving revision 1.43
diff -u -r1.43 tcl.decls
--- generic/tcl.decls	2001/01/18 19:09:55	1.43
+++ generic/tcl.decls	2001/02/28 21:20:10
@@ -1501,6 +1501,9 @@
 declare 432 generic {
     int Tcl_AttemptSetObjLength(Tcl_Obj *objPtr, int length)
 }
+declare 433 generic {
+    Tcl_ThreadId Tcl_GetChannelThread(Tcl_Channel channel)
+}
 
 ##############################################################################
 
Index: generic/tclDecls.h
===================================================================
RCS file: /cvsroot/tcl/tcl/generic/tclDecls.h,v
retrieving revision 1.44
diff -u -r1.44 tclDecls.h
--- generic/tclDecls.h	2001/01/18 19:09:55	1.44
+++ generic/tclDecls.h	2001/02/28 21:20:17
@@ -1350,6 +1350,9 @@
 /* 432 */
 EXTERN int		Tcl_AttemptSetObjLength _ANSI_ARGS_((
 				Tcl_Obj * objPtr, int length));
+/* 433 */
+EXTERN Tcl_ThreadId	Tcl_GetChannelThread _ANSI_ARGS_((
+				Tcl_Channel channel));
 
 typedef struct TclStubHooks {
     struct TclPlatStubs *tclPlatStubs;
@@ -1850,6 +1853,7 @@
     char * (*tcl_AttemptRealloc) _ANSI_ARGS_((char * ptr, unsigned int size)); /* 430 */
     char * (*tcl_AttemptDbCkrealloc) _ANSI_ARGS_((char * ptr, unsigned int size, char * file, int line)); /* 431 */
     int (*tcl_AttemptSetObjLength) _ANSI_ARGS_((Tcl_Obj * objPtr, int length)); /* 432 */
+    Tcl_ThreadId (*tcl_GetChannelThread) _ANSI_ARGS_((Tcl_Channel channel)); /* 433 */
 } TclStubs;
 
 #ifdef __cplusplus
@@ -3629,6 +3633,10 @@
 #ifndef Tcl_AttemptSetObjLength
 #define Tcl_AttemptSetObjLength \
 	(tclStubsPtr->tcl_AttemptSetObjLength) /* 432 */
+#endif
+#ifndef Tcl_GetChannelThread
+#define Tcl_GetChannelThread \
+	(tclStubsPtr->tcl_GetChannelThread) /* 433 */
 #endif
 
 #endif /* defined(USE_TCL_STUBS) && !defined(USE_TCL_STUB_PROCS) */
Index: generic/tclIO.c
===================================================================
RCS file: /cvsroot/tcl/tcl/generic/tclIO.c,v
retrieving revision 1.28
diff -u -r1.28 tclIO.c
--- generic/tclIO.c	2001/01/30 17:32:06	1.28
+++ generic/tclIO.c	2001/02/28 21:20:34
@@ -1056,6 +1056,14 @@
     tsdPtr->firstCSPtr	= statePtr;
 
     /*
+     * TIP #10. Mark the current thread as the one managing the new
+     *          channel. Note: 'Tcl_GetCurrentThread' returns sensible
+     *          values even for a non-threaded core.
+     */
+
+    statePtr->managingThread = Tcl_GetCurrentThread ();
+
+    /*
      * Install this channel in the first empty standard channel slot, if
      * the channel was previously closed explicitly.
      */
@@ -1471,6 +1479,32 @@
 /*
  *----------------------------------------------------------------------
  *
+ * Tcl_GetChannelThread --
+ *
+ *	Given a channel structure, returns the thread managing it.
+ *	TIP #10
+ *
+ * Results:
+ *	Returns the id of the thread managing the channel.
+ *
+ * Side effects:
+ *	None.
+ *
+ *----------------------------------------------------------------------
+ */
+
+Tcl_ThreadId
+Tcl_GetChannelThread(chan)
+    Tcl_Channel chan;		/* The channel to return managing thread for. */
+{
+    Channel *chanPtr = (Channel *) chan;	/* The actual channel. */
+
+    return chanPtr->state->managingThread;
+}
+
+/*
+ *----------------------------------------------------------------------
+ *
  * Tcl_GetChannelType --
  *
  *	Given a channel structure, returns the channel type structure.
@@ -2254,6 +2288,14 @@
 
     statePtr->nextCSPtr	= tsdPtr->firstCSPtr;
     tsdPtr->firstCSPtr	= statePtr;
+
+    /*
+     * TIP #10. Mark the current thread as the new one managing this
+     *          channel. Note: 'Tcl_GetCurrentThread' returns sensible
+     *          values even for a non-threaded core.
+     */
+
+    statePtr->managingThread = Tcl_GetCurrentThread ();
 }
 
 /*
Index: generic/tclIO.h
===================================================================
RCS file: /cvsroot/tcl/tcl/generic/tclIO.h,v
retrieving revision 1.2
diff -u -r1.2 tclIO.h
--- generic/tclIO.h	2000/09/28 06:38:21	1.2
+++ generic/tclIO.h	2001/02/28 21:20:37
@@ -233,6 +233,8 @@
 				 * long as the channel state. Never NULL. */
     struct ChannelState *nextCSPtr;
 				/* Next in list of channels currently open. */
+    Tcl_ThreadId managingThread; /* TIP #10: Id of the thread managing
+				  * this stack of channels. */
 } ChannelState;
     
 /*
Index: generic/tclStubInit.c
===================================================================
RCS file: /cvsroot/tcl/tcl/generic/tclStubInit.c,v
retrieving revision 1.47
diff -u -r1.47 tclStubInit.c
--- generic/tclStubInit.c	2001/01/18 19:09:55	1.47
+++ generic/tclStubInit.c	2001/02/28 21:20:39
@@ -836,6 +836,7 @@
     Tcl_AttemptRealloc, /* 430 */
     Tcl_AttemptDbCkrealloc, /* 431 */
     Tcl_AttemptSetObjLength, /* 432 */
+    Tcl_GetChannelThread, /* 433 */
 };
 
 /* !END!: Do not edit above this line. */
Index: generic/tclTest.c
===================================================================
RCS file: /cvsroot/tcl/tcl/generic/tclTest.c,v
retrieving revision 1.22
diff -u -r1.22 tclTest.c
--- generic/tclTest.c	2000/11/24 11:27:37	1.22
+++ generic/tclTest.c	2001/02/28 21:20:47
@@ -4517,6 +4517,18 @@
         return TCL_OK;
     }
     
+    if ((cmdName[0] == 'm') && (strncmp(cmdName, "mthread", len) == 0)) {
+        if (argc != 3) {
+            Tcl_AppendResult(interp, "channel name required",
+                    (char *) NULL);
+            return TCL_ERROR;
+        }
+
+        TclFormatInt(buf, Tcl_GetChannelThread (chan));
+        Tcl_AppendResult(interp, buf, (char *) NULL);
+        return TCL_OK;
+    }
+
     if ((cmdName[0] == 'n') && (strncmp(cmdName, "name", len) == 0)) {
         if (argc != 3) {
             Tcl_AppendResult(interp, "channel name required",
Index: tests/io.test
===================================================================
RCS file: /cvsroot/tcl/tcl/tests/io.test,v
retrieving revision 1.14
diff -u -r1.14 io.test
--- tests/io.test	2000/04/10 17:19:00	1.14
+++ tests/io.test	2001/02/28 21:20:55
@@ -6722,6 +6722,29 @@
     list $x $result
 } {1 {gets {normal message from pipe} gets {} catch {error message from pipe}}}
 
+
+
+if {[info commands testthread] != {}} {
+    set mainthread [testthread id]
+} else {
+    set mainthread 0
+}
+
+test io-59.1 {Thread reference of channels} {
+    # TIP #10
+    # More complicated tests (like that the reference changes as a
+    # channel is moved from thread to thread) can be done only in the
+    # extension which fully implements the moving of channels between
+    # threads, i.e. 'Threads'. Or we have to extend [testthread] as well.
+
+    set f [open longfile r]
+    set result [testchannel mthread $f]
+    close $f
+    set result
+} $mainthread
+
+
+
 # cleanup
 foreach file [list fooBar longfile script output test1 pipe my_script foo \
 	bar test2 test3 cat stdout] {
@@ -6730,16 +6753,3 @@
 ::tcltest::restoreState
 ::tcltest::cleanupTests
 return
-
-
-
-
-
-
-
-
-
-
-
-
-
Index: unix/mkLinks
===================================================================
RCS file: /cvsroot/tcl/tcl/unix/mkLinks,v
retrieving revision 1.18
diff -u -r1.18 mkLinks
--- unix/mkLinks	2001/01/18 19:09:56	1.18
+++ unix/mkLinks	2001/02/28 21:20:57
@@ -165,6 +165,7 @@
     rm -f Tcl_SpliceChannel.3
     rm -f Tcl_IsChannelExisting.3
     rm -f Tcl_ClearChannelHandlers.3
+    rm -f Tcl_GetChannelThread.3
     ln CrtChannel.3 Tcl_CreateChannel.3
     ln CrtChannel.3 Tcl_GetChannelInstanceData.3
     ln CrtChannel.3 Tcl_GetChannelType.3
@@ -195,6 +196,7 @@
     ln CrtChannel.3 Tcl_SpliceChannel.3
     ln CrtChannel.3 Tcl_IsChannelExisting.3
     ln CrtChannel.3 Tcl_ClearChannelHandlers.3
+    ln CrtChannel.3 Tcl_GetChannelThread.3
 fi
 if test -r CrtChnlHdlr.3; then
     rm -f Tcl_CreateChannelHandler.3

TIP:            10
Title:          Tcl I/O Enhancement: Thread-Aware Channels
Version:        $Revision: 1.6 $
Version:        $Revision: 1.3 $
Author:         Andreas Kupries <[email protected]>
State:          Final
State:          Draft
Type:           Project
Vote:           Done
Vote:           Pending
Created:        08-Nov-2000
Post-History:   
Tcl-Version:    8.4

~ Abstract

This TIP describes how to change the generic I/O layer in the Tcl core

   1. Declare a new API function to retrieve the Id of the managing
      thread from a channel. Add this declaration to generic/tcl.decls
      and implement the function in the file generic/tclIO.c.  I
      propose ''Tcl_GetChannelThread'' as the name of this new API
      function.

A patch implementing all of the changes described above and
additionally extending the documentation and the test-suite
is available here:
http://www.cs.man.ac.uk/fellowsd-bin/TIP/10.patch
additionally extending the documentation and the testsuite
was registered at SourceForge. The Id is 103538. A direct
reference is available:
http://sourceforge.net/patch/?func=detailpatch&patch_id=103538&group_id=10894

~ Copyright

This document has been placed in the public domain.

TIP:            10000
Title:          Dummy Proposal for Testing Editing Interfaces
Version:        $Revision: 1.85 $
Version:        $Revision: 1.49 $
Author:         Don Porter <[email protected]>
Author:         <[email protected]>
Author:         Andreas Kupries <[email protected]>
Author:         Donal K. Fellows <[email protected]>
Author:         Andreas Kupries <[email protected]>
Author:         <[email protected]>
Author:         Richard Suchenwirth <[email protected]>
Author:         Kevin B KENNY <[email protected]>
Author:         Jeff Hobbs <[email protected]>
Author:         Test User <[email protected]>
Author:         New User <[email protected]>
State:          Draft
Type:           Informative
Vote:           Pending
Created:        03-Dec-2000
Post-History:   

~ Abstract

This document serves a purpose similar to the Graffiti page
(http://purl.org/thecliff/tcl/wiki/34.html) at the Tcl'ers
Wiki (http://purl.org/thecliff/tcl/wiki/).

It will also be useful for testing the web editing interface
proposed in [13].

~ ActiveState Server Test

Testing after Tcl upgrade... Do I see these changes?

How about these changes?

Quick check after TIP software update.

Things still working after the move?  Looking good.

Checking cron update at scriptics.com.

~ New Features Test

Gotta try the log message...
...and the cookies...
Hmmm... no cookies!
Donal says it's better now...
...but I still don't see any fields filled in for me...
...but now I do!

''still trying to get the cookies working - DKF''

~ Submission Test

Some browsers are spinning their wheels after submission...
Looks like this is fixed now.

~ Author Add Test

Checking fix for missing Abstract after adding a new Author...
Fixed.

~ Reload/caching Test

See if additional HTTP headers help... Yes.  More from Jeff.
See if additional HTTP headers help... Yes.

~ Test

Attempt to add a new section via the web interface (in a frame).

Are anonymous changes possible?

~ Testing the interface

<Andreas Kupries>
Just my first try at the new web editing interface for TIPs.

Hm ... Maybe we could add a direct reference to [3] to the

That's it for now. ... I'll add the same comments to [13], they belong
there more than here.
</Andreas Kupries>

<note by="Richard Suchenwirth" date="2001-01-30">Whitespace in XML element names won't work.. or is 
"Kupries" an attribute without value?</note>

~ ChangeLog
~ Dummy <Section> 'To' "Test" XML Generation


| $Log: not supported by cvs2svn $
| Revision 1.48  2001/01/30 09:40:49  tclhttpd
| Revision through web from Richard GH Suchenwirth <[email protected]> (15856)
|
Move along now; nothing to see here...

| Revision 1.47  2001/01/26 22:36:21  tclhttpd
| Revision through web from  <[email protected]> (6062)
|
~ TIPs as PostScript and Adobe PDF

| Revision 1.46  2001/01/26 22:35:19  tclhttpd
| Revision through web from  <[email protected]> (6043)
| 
http://www.cs.man.ac.uk/~fellowsd/tcl/bitsandpieces/tips_on_20010622.pdf
| Revision 1.45  2001/01/26 22:34:27  tclhttpd
| Revision through web from  <[email protected]> (6023)

~ Copyright

This document has been placed in the public domain.

TIP:            11
Title:          Tk Menubutton Enhancement: -compound option for menubutton
Version:        $Revision: 1.5 $
Version:        $Revision: 1.4 $
Author:         Todd Helfter <[email protected]>
State:          Final
State:          Accepted
Type:           Project
Tcl-Version:    8.4
Vote:           Done
Created:        16-Nov-2000
Post-History:

~ Abstract

TIP:            12
Title:          The "Batteries Included" Distribution
Version:        $Revision: 1.3 $
Version:        $Revision: 1.2 $
Author:         George A. Howlett <[email protected]>
Author:         Larry W. Virden <[email protected]>
State:          Draft
Type:           Informative
Type:           Informational
Vote:           Pending
Created:        15-Sep-2000
Post-History:   
Discussions-To: news:comp.lang.tcl
Post-History: 

~ Abstract

This document describes a comprehensive Tcl/Tk distribution.  Its
primary purpose is to create a standard source tree that includes Tcl,
Tk, and extensions so that they can be built and installed in an
simple and easy manner.

relationship between Tcl and its parts.  After all, application
writers first care about whether a feature or capability is available,
not how it's structured under the hood.

~ The "Batteries Included" Distribution.

Let's start with a very modest example.  Let's imagine that the
"Batteries Included" distribution is nothing more than an archive file of
the source code for Tcl/Tk and several extensions.
"Batteries Included" distribution is nothing more than a tar file of
Tcl/Tk and several extensions.

|            Unix    Windows  Mac
|             ----    -------  ---
|  Tcl 8.3       x       x      x
|  Tk 8.3        x       x      x
|  [incr Tcl]    x       x      x
|  expect        x       ?
|  TclX          x
|  BLT           x       x
|  Trf           
|  Html widget
|  XML
|  ...lots more...

  
Tcl, Tk, and the packages are configured such that they can be built
and installed just from a top level directory (not individually).
Someone can download and try out all sorts of new features without
repeating the same "configure", "make", "make install" sequences.

With this simple tar file, the following benefits are automatically
generated:

  
  * It provides a simple way for users to try out extensions.  Users
    only have to run download, configure, compile and install, at
    most, once.

  * It describes a clear framework for extensions.  We will have
    established a directory structure for both source code and
    installed binaries.  It will be much more clear how to
    inter-operate.  This is TEA in action.

  * It's better for Tcl/Tk application writers.  You can count on
    features being universally available.  Your program can again be
    just a Tcl script, not an array of packages that everyone needs to
    download and install.

     
  * It's better for extension writers.  Configuration is simpler,
    since you know where all the sources and the compiler-specific
    information will reside.  You don't need to search for
    ''tclConfig.sh'' or ''tkConfig.sh'' files.

     
  * It's better for Tcl/Tk distribution builders.  This includes both
    the Linux distributors and company sysadmins that build Tcl/Tk.
    They don't have to fear installing extensions because of version
    dependencies.

  > Let's give Redhat and SuSE a good reason to move off of version
    8.0. One the big advantages of Linux over (let's say) Solaris is

 * Identify extensions.  

 > What extensions should be included in the near term?  We need
   extension authors that are willing to work with us to build a
   directory framework, change configuration files, etc.  Extensions
   do not need to work on all platforms.  For example, there is a
   wealth of Windows-based extensions that should be included in 
   wealth of Windows-based extensions that should be included.
   a Windows specific build.

 > What are the minimum requirements for extensions in the short term?
   Manual pages, html, tests, demos all would be nice.  We need to
   temper this with what's practical.  This is a learning process. We
   can adjust requirements in future phases.

 * Determine build and install directory structures.  

 > We need to make this work with more that one release installed.
   Don't suppose that there only one version will ever be used.

   
 * Setup CVS archives.

 * Create configuration files.  

 > This will require negotiation with extension writers.  We want
   their buy-in so they will maintain the changes.

The last phases are sketchy.  Feel free to add to this list, further
breaking down goals into subtasks.

~ Open Issues

 * Windows and MacIntosh sources.

 
 > Given the dearth of configuration tools for these platforms, it's
   likely that only binary installations will be available for the
   near term.

 * Documentation

 > Overlap in command and widget names can be neatly handled by
   namespaces.  Need to consider how to handle manual pages.

 
~ More Information

If anyone has interest to participate or would like to add comments to
the "Batteries Included" proposal, please send mail to George Howlett
<[email protected]>.

~ Copyright

This document has been placed in the public domain.

~ See Also

[4] by Brent Welch <[email protected]>.

TIP:            13
Title:          Web Service for Drafting and Archiving TIPs
Version:        $Revision: 1.25 $
Version:        $Revision: 1.22 $
Author:         Don Porter <[email protected]>
Author:         Donal K. Fellows <[email protected]>
State:          Accepted
Type:           Process
Vote:           Done
Created:        21-Nov-2000
Post-History:   

The modifications to the Fellows TIP rendering engine that add the
capabilities proposed above are now merged in.  The TIP rendering
engine is maintained at
http://sourceforge.net/projects/tiprender/ .  To enable the
web-editing features, set the Tcl variable FEATURE(EDIT) to 1 in
the file config.tcl.  A working version of the proposed web service
is available at http://purl.org/tcl/home/cgi-bin/tct/tip/ .
is available at http://www.scriptics.com:8080/cgi-bin/tct/tip/ .

For what it's worth, this TIP was created primarily within a web
browser, making revisions through the web interface provided by the
reference implementation.

One remaining shortcoming of the reference implementation is that it
provides no mechanism for uploading images to the TIP repository.

 * ''I had the server time out on me''

 > That's troubling.  Can anyone seeing this problem provide any more
   information.  What were the circumstances, in detail?

 * ''Add links to an interface showing revision history''

 > Check out the [History] links at the bottom of the HTML rendered pages.
   Thanks to Donal Fellows for coding that up.  (OK, so we *did* reinvent
   CVSWeb.)
 > Once we have CVSweb installed and operating on the same server, that
   will be done.  With the TIPs already in CVS, that should not be
   difficult.  We should not re-invent CVSweb.

 * ''A separate <TEXTAREA> for the Abstract''

 > This is now implemented.  Please give it a try.

~ Copyright

This document has been placed in the public domain.

TIP:            14
Title:          Access (via tkInt) to Tk Photo Image Transparency
Version:        $Revision: 1.3 $
Version:        $Revision: 1.2 $
Author:         Donal K. Fellows <[email protected]>
State:          Draft
Type:           Project
Tcl-Version:	8.4.0
Vote:           Pending
Vote:           In progress
Created:        22-Nov-2000
Keywords:	Tk, photo, transparency, internal, access
Post-History:   

~ Abstract

It is useful for some extensions to have access to the transparency

TIP:            15
Title:          Functions to List and Detail Math Functions
Version:        $Revision: 1.8 $
Version:        $Revision: 1.1 $
Author:         Donal K. Fellows <[email protected]>
State:          Final
State:          Draft
Type:           Project
Tcl-Version:	8.4.0
Vote:           Done
Vote:           Pending
Created:        22-Nov-2000
Keywords:	Tcl, expr, function, introspection
Post-History:   
Keywords:       Tcl,expr,function,introspection
Tcl-Version:    8.4.0

~ Abstract

Provides a way for the list of all math functions defined in the
current interpreter to be discovered, and for discovering what
arguments might be passed to an existing math function.  This may be
useful in tests as well as more general use.

~ Rationale

Although it is quite easy to define a new function for use in
expressions, there is no public way of performing introspection on
this information.  Having a way to extract the arguments from an
existing math function was requested by
http://sourceforge.net/bugs/?func=detailbug&bug_id=119304&group_id=10894
and once you have one, it becomes trivial to also ask for a second
function to list what functions are defined.

I propose the creation of two functions that fulfil this r�le;
''Tcl_GetMathFuncInfo'' and ''Tcl_ListMathFuncs''.  These functions
will be documented on the same manual page as ''Tcl_CreateMathFunc''
will be documented on the same manual page as ''Tcl_CreateMathFunc''.
and implemented in the same file.

Furthermore, I also propose that the ''info'' command in the Tcl
interpreter be extended to include a new subcommand, ''functions'',
which will allow Tcl scripts to discover the list of installed
functions (by acting as a thin veneer over ''Tcl_ListMathFuncs''.)
Note that this is an extension of the ''info'' command because it
allows for introspection of a system that affects the behaviour of
several commands that form the core part of the command-set: ''expr'',
''for'', ''if'' and ''while''.

~ Tcl_GetMathFuncInfo

This function will take an interpreter reference, a function name (as
a string) and pointers to variables capable of taking each of the last
four arguments to ''Tcl_CreateMathFunc'', and will return a standard
Tcl result (either ''TCL_OK'' or ''TCL_ERROR'', depending on whether a
function with the given name exists within the given interpreter, with
an error message being left in the interpreter's result in the
''TCL_ERROR'' case.)  The array of argument types whose reference is
placed into the variable pointed to by ''argTypesPtr'' will be
allocated by Tcl, and should be freed with ''Tcl_Free''.

|int Tcl_GetMathFuncInfo(Tcl_Interp *interp, CONST char *name,
|int Tcl_GetMathFuncInfo(Tcl_Interp *interp, char *name,
|                        int *numArgsPtr, Tcl_ValueType **argTypesPtr,
|                        Tcl_MathProc **procPtr,
|                        Tcl_MathProc *procPtr,
|                        ClientData *clientDataPtr);

The parameter names are chosen by analogy with ''Tcl_CreateMathFunc''.

In the case where a math function is defined internally by the bytecode
engine and has no standard implementation (all the builtin functions in
8.4a2 are like this) the value placed in the variable indicated by the
''procPtr'' argument will be NULL.

~ Tcl_ListMathFuncs

This function will take an interpreter reference and an optional
string that describes a glob-like pattern that restricts the set of
math functions that the caller is interested in receiving (with a
''NULL'' indicating that no filtering is desired.)  The function will
return a pointer to a newly-allocated ''Tcl_Obj'' list of the names of
all the math functions defined within that interpreter, or ''NULL'' in
the case of an error (in which case a suitable message will be left in
the interpreter.)  The list will not be required to be sorted.

|Tcl_Obj *Tcl_ListMathFuncs(Tcl_Interp *interp, CONST char *pattern);
|Tcl_Obj *Tcl_ListMathFuncs(Tcl_Interp *interp, char *pattern);

The alternative is to pass in the addresses of variables that will be
updated to contain the number of functions and an array of function
names.  But I prefer the ''Tcl_Obj'' approach as it is expressing the
fact that the list of function names is really a single thing being
returned (albeit one that is not a simple value.)  It is not
anticipated that the performance of this function will need to be
crucial to too many applications.

~ info functions

Maybe this should be mapped to an ''info'' subcommand.
This new subcommand will provide access from Tcl scripts to the
functionality of ''Tcl_ListMathFuncs''.  It will take a single optional
argument consisting of a pattern to pass on as the ''pattern'' argument
(with the absence of the argument indicating that NULL is to be passed
instead.)

~ Copyright

This document is placed in the public domain.

TIP:            16
Title:          Tcl Functional Areas for Maintainer Assignments
Version:        $Revision: 1.10 $
Version:        $Revision: 1.7 $
Author:         Don Porter <[email protected]>
State:          Accepted
Type:           Process
Vote:           Done
Created:        21-Nov-2000
Post-History:   

     generic/tclVar.c,
     tests/append.test,
     tests/set.test,
     tests/set-old.test,
     tests/upvar.test,
     tests/var.test

   >   1. ''Environment Variables'' - doc/Environment.3,
   >   1. ''Environment Variables'' - generic/tclEnv.c,
     generic/tclEnv.c,
     mac/tclMacEnv.c,
     tests/env.test

   >   1. ''Linked C Variables'' - doc/LinkVar.3,
     generic/tclLink.c,
     tests/link.test

   Objects: 

   >   1. ''Object System and Fundamental Object Types'' - doc/Backslash.3,
   >   1. ''Object System and Fundamental Object Types'' - doc/Access.3,
     doc/Backslash.3,
     doc/BoolObj.3,
     doc/Concat.3,
     doc/DoubleObj.3,
     doc/DString.3,
     doc/Encoding.3,
     doc/FindExec.3,
     doc/GetCwd.3,
     doc/Hash.3,
     doc/IntObj.3,
     doc/Object.3,
     doc/ObjectType.3,
     doc/PrintDbl.3,
     doc/SplitList.3,
     doc/StringObj.3,
     doc/StrMatch.3,
     generic/tclEncoding.c,
     generic/tclHash.c,
     generic/tclObj.c,
     generic/tclStringObj.c,
     generic/tclUtil.c,
     library/encoding/*.enc,
     library/encoding/*.enc
     tools/encoding/*,
     tests/dstring.test,
     tests/encoding.test,
     tests/stringObj.test,
     tests/obj.test,
     tests/util.test

   >   1. ''Conversions From String'' - doc/GetInt.3,

     doc/ChnlStack.3,
     doc/CrtChnlHdlr.3,
     doc/CrtCloseHdlr.3,
     doc/CrtChannel.3,
     doc/DetachPids.3,
     doc/GetStdChan.3,
     doc/OpenFileChnl.3,
     doc/SetErrno.3,
     generic/tclIO.c,
     generic/tclIO.h,
     generic/tclIOUtil.c,
     generic/tclPipe.c,
     generic/tclPosixStr.c,
     tests/io.test
     tests/io.test,
     tests/ioUtil.test,
     win/tclWinError.c

   >   1. ''Channel Transformations'' - generic/tclIOGT.c,
     tests/iogt.test

   >   1. ''Built-in Channel Types'' - compat/waitpid.c,
     doc/GetHostName.3,
     doc/GetOpnFl.3,

     library/tcltest/pkgIndex.tcl,
     tests/tcltest.test

   File System: 

   >   1. ''Pathname Management'' - doc/filename.n,
     doc/glob.n,
     doc/FileSystem.3,
     doc/SplitPath.3,
     doc/Translate.3,
     mac/tclMacFile.c,
     generic/tclFileName.c,
     tests/fileName.test,
     tests/unixFile.test,
     tests/winFile.test,
     unix/tclUnixFile.c,
     win/tclWinFile.c

   >   1. ''File System Access'' - doc/Access.3,
   >   1. ''File System Access'' - generic/tclFCmd.c,
     doc/GetCwd.3,
     doc/SetErrno.3,
     doc/Signal.3,
     generic/tclFCmd.c,
     generic/tclIOUtil.c,
     generic/tclPosixStr.c,
     mac/tclMacFCmd.c,
     tests/fCmd.test,
     tests/ioUtil.test,
     tests/macFCmd.test,
     tests/unixFCmd.test,
     tests/winFCmd.test,
     unix/tclUnixFCmd.c,
     win/tclWinError.c,
     win/tclWinFCmd.c

   Initialization, Script Library, and Autoloader: 

   >   1. doc/library.n,
     doc/tclvars.n,
     doc/unknown.n,

     tests/reg.test,
     tests/regexp.test,
     tools/uniClass.tcl

   UTF-8 String Management: 

   >   1. doc/ToUpper.3,
     doc/UniCharIsAlpha.3,
     doc/Utf.3,
     generic/tclUtf.c,
     tools/uniParse.tcl,
     tests/utf.test,
     win/tclWin32Dll.c

   Fundamental Parsing and Evaluation: 

   >   1. compat/float.h,
     generic/tclCompCmds.c,
     generic/tclCompExpr.c,
     generic/tclCompile.c,
     generic/tclCompile.h,
     generic/tclExecute.c,
     generic/tclLiteral.c
     tests/appendComp.test,
     tests/compExpr-old.test,
     tests/compExpr.test,
     tests/compile.test,
     tests/execute.test,
     tests/expr.test,
     tests/for.test,
     tests/if.test,
     tests/incr.test,
     tests/stringComp.test,
     tests/while.test

   Threads: 

   >   1. doc/Thread.3,
     generic/tclThread.c,
     generic/tclThreadJoin.c,
     mac/tclMacThrd.c,
     mac/tclMacThrd.h,
     tests/thread.test,
     unix/tclUnixThrd.c,
     unix/tclUnixThrd.h,
     win/tclWinThrd.c,
     win/tclWinThrd.h

   Embedding Support: 

   >   1. doc/AppInit.3,
     doc/Tcl_Main.3,
     doc/Panic.3,
     doc/tclsh.1,
     generic/tclMain.c,
     generic/tclPanic.c,
     mac/tclMacAppInit.c,
     mac/tclMacPanic.c,
     unix/tclAppInit.c,
     win/tclAppInit.c

     tools/white.bmp,
     unix/Makefile.in,
     unix/aclocal.m4,
     unix/configure.in,
     unix/install-sh,
     unix/ldAix,
     unix/mkLinks,
     unix/mkLinks.tcl,
     unix/tcl.m4,
     unix/tcl.spec,
     unix/tclConfig.sh.in,
     win/Makefile.in,
     win/aclocal.m4,
     win/configure.in,
     win/makefile.vc,

   >   1. ''[[resource]]'' - doc/resource.n,
     doc/source.n,
     mac/tclMacResource.c,
     mac/tclMacResource.r,
     tests/resource.test,
     tests/source.test

   >   1. ''Mac-Specific Files'' - doc/Macintosh.3,
   >   1. ''Mac-Specific Files'' - mac/AppleScript.html
     mac/AppleScript.html
     mac/Background.doc
     mac/libmoto.doc
     mac/morefiles.doc
     mac/MW_TclAppleScriptHeader.h
     mac/MW_TclAppleScriptHeader.pch
     mac/MW_TclHeader.h
     mac/MW_TclHeader.pch

     mac/tclMacOSA.exp
     mac/tclMacOSA.r
     mac/tclMacProjects.sea.hqx
     mac/tclMacShLib.exp
     mac/tclMacTclCode.r
     mac/tclMacUnix.c
     mac/tclMacUtil.c
     mac/tcltkMacBuildSupport.sea.hqx
     tests/osa.test

~ Shared Files

The following files are shared by all of Tcl.  Any maintainer may
modify them as necessary to complete changes they are making to
their portion of Tcl.  Some of the following files define Tcl's

TIP:            17
Title:          Redo Tcl's filesystem
Version:        $Revision: 1.18 $
Version:        $Revision: 1.15 $
Author:         Vince Darley <[email protected]>
State:          Final
State:          Draft
Type:           Project
Vote:           Done
Vote:           Pending
Created:        17-Nov-2000
Post-History:   
Tcl-Version:    8.4.0

~ Abstract

Many of the most exciting recent developments in Tcl have involved

TIP:            18
Title:          Add Labels to Frames
Version:        $Revision: 2.2 $
Version:        $Revision: 2.0 $
Author:         Peter Spjuth <[email protected]>
State:          Accepted
State:          Draft
Type:           Project
Vote:           Done
Vote:           Pending
Created:        12-Dec-2000
Post-History:   
Tcl-Version:    8.4

~ Abstract

This TIP proposes to add a labelled frame widget to Tk.

TIP:		19
Title:		Add a Text Changed Flag to Tk's Text Widget
Version:	$Revision: 1.5 $
Version:	$Revision: 1.4 $
Author:		Neil McKay <[email protected]>
State:		Accepted
Type:		Project
Vote:		Done
Created:	03-Jan-2001
Tcl-Version:	8.4a2
Obsoleted-By:	26
Post-History:

~Abstract

This TIP adds a ''text changed'' flag to the Tk text widget.  The flag
would initially be reset, but would be set whenever the contents of
the text widget changes.

TIP:            2
Title:          TIP Guidelines
Version:        $Revision: 1.17 $
Version:        $Revision: 1.10 $
Author:         Andreas Kupries <[email protected]>
Author:         Donal K. Fellows <[email protected]>
Author:         Don Porter <[email protected]>
Author:         Mo DeJong <[email protected]>
Author:         Larry W. Virden <[email protected]>
State:          Draft
Type:           Process
Vote:           Pending
Created:        12-Sep-2000
Post-History:   

~ Abstract

documenting dissenting opinions.

Because the TIPs are maintained as text files under revision control,
their history is the historical record of the feature proposal.  This
historical record is available by the normal (CVS?) commands for
retrieving older revisions.  For those without direct access to the
CVS tree, you can browse the current and past TIP revisions via
http://www.cs.man.ac.uk/fellowsd-bin/TIP/ .
http://tip.web.site/

Further details on the arguments behind the evolution of the TIP
concept and formatting can be found in the archive of the ''tclcore''
mailing list at
mailing list at http://dev.scriptics.com/lists/tclcore/
http://www.geocrawler.com/redir-sf.php3?list=tcl-core .

~ Kinds of TIPs

There are three kinds of TIPs.  A project TIP describes a new (or
significantly updated) feature or implementation for Tcl.  An
informative TIP describes a Tcl design issue, or provides general
guidelines or information to the Tcl community, but does not propose a

If the TIP editor approves, he will assign the TIP a number, label it
as either project, process or informational, give it status ''Draft'',
and create and check-in the initial draft of the TIP.  The TIP editor
will not unreasonably deny a TIP.  Reasons for denying TIP status
include gross malformatting, inappropriate copyright, duplication of
effort, being technically unsound, or not in keeping with the Tcl
philosophy; the TCT and after that John Ousterhout
<ouster@pacbell.net> is the final arbitrator of the
<john.ousterhout@ajubasolutions.com> is the final arbitrator of the
latter, as defined in the charter ([0]).

Discussion concerning a TIP should initially be kept out of the
tclcore and tct mailing lists.  Instead, comments should be sent to,
and collected by, the TIP author, who has the responsibility to
incorporate these comments into the document.

(With thanks to William H. Duquette <[email protected]>
for suggesting this.)  Note that the TIP Editor is responsible for
allocating TIP numbers, so you can leave that unfilled.

|TIP:           ???
|Title:         The TIP Title as Plain Text
|Version:       $Revision: 1.17 $
|Version:       $Revision: 1.10 $
|Author:        Author Name <[email protected]>
|State:         Draft
|Type:          Project
|Tcl-Version:   8.4
|Vote:          Pending
|Created:       31-Feb-1999
|Post-History:

patches to be posted on that newsgroup.  If you want a patch to be
incorporated into the archive, please contact the TIP Editor.

----

~ Comments

 > From Don Porter  < [email protected] > :
 > From Don Porter  < [email protected] > : 

 > 1. It is confusing that "project" TIPs defined here do not
      correspond to "projects" defined in [0].

 > 2. The TIP Workflow section should mention the web-based
      drafting service [13] as another way for members of the
      community to add their comments to a draft TIP.

      incompatible with posting to comp.lang.tcl.announce, so
      earlier sections of this TIP should not indicate that including
      patches in the TIP is an acceptable practice.

 > 7. Should process TIPs be reserved for those proposals that
      revise [0] and require 2/3 support of the entire TCT?

From Mo DeJong:

It seems like we have a documentation problem with
respect to how a TIP becomes "un-rejected".

The text says:

 > ... may accept or reject a TIP or send it back to the author(s)
   for revision"

But the state transition diagram shows no way to go from
''Rejected'' to ''Draft''. What becomes of a TIP after it
is put up for a vote? If it is rejected, should the
author create a new TIP number or can they rewrite
the original TIP?

----

''Larry W. Virden writes:''  I would really find it useful
if upon submission of a TIP, a web page, perhaps on
the Tcl'ers Wiki or elsewhere, would be referenced in
the TIP itself.  This web page would contain a summary
of the discussion to date, perhaps containing urls
to relevant postings within the tct archives, etc.
This page could be used by those looking at the
archive to quickly determine the state of the discussion,
as well as the reasons for the final disposition of the
TIP.

----

~ Copyright

This document has been placed in the public domain.

TIP:            21
Title:          Asymmetric Padding in the Pack and Grid Geometry Managers
Version:        $Revision: 1.6 $
Version:        $Revision: 1.5 $
Author:         D. Richard Hipp <[email protected]>
State:          Final
State:          Accepted
Type:           Project
Vote:           Done
Created:        14-Jan-2001
Post-History:   
Tcl-Version:    8.4

~ Abstract

TIP:            22
Title:          Multiple Index Arguments to lindex
Version:        $Revision: 1.21 $
Version:        $Revision: 1.8 $
Author:         David Cuthbert <[email protected]>
Author:         Kevin Kenny <[email protected]>
Author:         Don Porter <[email protected]>
Author:         Donal K. Fellows <[email protected]>
State:          Accepted
State:          Draft
Type:           Project
Vote:           Done
Vote:           Pending
Created:        19-Jan-2001
Post-History:   
Discussions-To: news:comp.lang.tcl,mailto:[email protected]
Keywords:       lindex,multiple arguments,sublists
Discussions-To: news:comp.lang.tcl
Keywords:       {{{lindex {multiple arguments} sublists}}}
Tcl-Version:    8.4a2

~ Abstract

Obtaining access to elements of sublists in Tcl often requires nested
calls to the ''lindex'' command.  The indices are syntactically listed
in most-nested to least-nested order, which is the reverse from other

|result = range(temp, 0, length(temp) - 1);

Allowing the ''lindex'' command to accept multiple arguments would
allow this more-natural style of coding to be written in Tcl.

~ Specification

 1. Under this proposal, the syntax for the ''lindex'' command is to be
    modified to accept one of two forms:
 1. Allow ''lindex'' to accept an arbitrary number of arguments.

|     lindex list indexList

  > 1. The first argument (the ''list argument'') must be a proper Tcl
    or

       list.  No change is required from current behaviour.
|     lindex list index1 index2...

    > In either form of the command, the ''list'' parameter is
      expected to be a well-formed Tcl list.

  > 2. The remaining arguments (the ''index arguments'') must be
    > In the first form of the command, the ''indexList'' argument is
      expected to be a Tcl list comprising one or more list indices,
       proper list indices (either ''integer'', end, or
      each of which must be an integer, the literal string ''end'', or
      the literal string ''end-'' followed by an integer with no
      intervening whitespace.  The existing ''lindex'' command is a
      degenerate form of this first form, where the list comprises a
      single index.

       end-''integer'').
    > In the second form of the command, each of the ''index''
      arguments is expected to be a list index, which again may be an
      integer, the literal string ''end'', or the literal string
      ''end-'' followed by an integer with no intervening whitespace.

 2. In either form of the command, once the ''indexList'' parameter
    is expanded, there is a single ''list'' parameter and one or
    more ''index'' parameters.  If there is a single ''index''
    parameter ''N'', the behavior is identical to today's ''lindex''
    command, and the command returns the ''N''th element of
    ''list''; if ''N'' is less than zero or at least the length of
    the list, a null string is returned.

 2. When only one index argument is given, the behaviour is unchanged
 3. If more than one ''index'' parameter is given, then the behavior is
    defined recursively; the result of

    from the current ''lindex'' command.
|   lindex $list $index0 $index1 ...

  > or

 3. When multiple index arguments are given, the behaviour is defined
|   lindex $list [list $index0 $index1 ...]

    recursively as:
  > is indentical to that of

|   lindex [lindex $list $index0] $index1...

|lindex alist i0 i1 i2 ... === lindex [lindex alist i0] i1 i2 ...
  > or, equivalently,

|   lindex [lindex $list $index0] [list $index1...]

  > (This specification does not constrain the implementation, which
  > Note that this does not define any restrictions on the
    implementation, which may be recursive or iterative.
    may be iterative, recursive, or even expanded inline.)

 4. When an invalid index is given, an error of the form, ''bad index
    "invalid_index": must be integer or end?-integer?'', where
    ''invalid_index'' is the first invalid index encountered, must be
    returned.

 5. If the list argument is malformed, the error resulting from an
    attempt to convert the list argument to a list must be returned.
    This behaviour is unchanged from the current implementation.

~ Side Effects

 1. Whether the result of the ''lindex'' operation is successful, the
    underlying Tcl_Obj that represents the list argument may have its
    internal representation invalidated or changed to that of a list.

~ Discussion

Some attention must be paid to giving the ''lindex'' command adequate
performance.  In particular, the implementation should address the
common case of

|    lindex $list $i

where ''$i'' is a "pure" integer (that is, one whose string
representation has not yet been formed).  If the above specification
is followed naively, the flow will be as follows.

Since ''objc'' is three, ''objv[[2]]'' is expected to be a list.
Since it is not, it must be converted from its string representation.
It does not have one yet, so the string representation must be formed.
Now the string representation is parsed as a list.  An array (of
length one) of Tcl_Obj pointers is allocated to hold the list in
question, and a Tcl_Obj is allocated to hold the single element.
Memory is allocated to hold the element's string representation.
Now the ''lindex'' command converts the first element of the list to
an index (in this case an integer).

This elaborate ballet of type shimmering requires converting the
integer to a string and back again.  It also requires four calls to
''ckalloc:''

 1. Allocate a buffer for the string representation.

 2. Allocate the array of Tcl_Obj pointers for the list
    representation.

 3. Allocate the Tcl_Obj that represents the first (and only) element
    of the list.

 4. Allocate a buffer for the string representation of that element.

And at the end, the result is the same integer that was passed as a
parameter originally.

To avoid all this overhead in the common case, the proposed
implementation shall (in the case where ''objc==3'')

 1. Test whether ''objv[[2]]'' designates an object whose internal
    representation holds an integer.  If so, simply use it as an
    index.

 2. Test whether ''objv[[2]]'' designates an object whose internal
    representation holds a list.  If so, perform the recursive
    extraction of indexed elements from sublists described above.

 3. Form the string representation of ''objv[[2]]'' and test whether
    it is ''end'' or ''end-'' followed by an integer.  If so, use it
    as an index.

 4. Attempt to coerce ''objv[[2]]'' to an integer; if successful, use
    the result as an integer.

 5. Attempt to coerce ''objv[[2]]'' to a list; if successful, use the
    result as an index list.

 6. Report a malformed ''index'' argument; the ''indexList'' parameter
    is not a well-formed list.

This logic handles all the cases of singleton lists transparently; it
is effectively a simple-minded type inference that optimizes away
needless conversions.

Assuming that the related [33] is approved, this logic will most
likely be combined with the identical logic required in that proposal
for parsing ''index'' arguments to the ''lset'' command.

----

~ Comments

''Don Porter <[email protected]>''

 > I agree that it would be helpful to many programmers to
   provide a multi-dimensional array data structure that can
   be accessed in the manner described in this TIP.  In the
   ''struct'' module of ''tcllib'', several other data structures
   are being developed: graph, tree, queue, stack.  I would support
   adding another data structure to that module that provides an
   interface like the one described in this TIP, with the intent that

   packages to combine the primitives into more useful, more
   complex resources.

 > This TIP should also consider how any changes to [[lindex]] mesh
   with the whole [[listx]] overhaul of Tcl's [[list]] command that
   has been discussed.

''Dave Cuthbert <[email protected]> responds''

 > Don makes a good point -- with a good set of data structures in
   tcllib, the need for this TIP is lessened or even eliminated.
   Nonetheless, I see this as a way of implementing the structures he
   describes.  In other words, a more powerful primitive (which, in
   reality, adds fairly little complexity when measured in number of
   lines of code changed) would benefit these structures.

 > As for the [[listx]] overhaul, there are many competing proposals
   for the specification it is difficult to come up with a metric.  In
   writing this TIP, I assumed a vacuum -- that is, a listx command
   would not be added to the core in the near future.

''Donal K. Fellows <[email protected]> points out''

 > Although there is tcllib and [[listx]] to think about, they are
   certainly not reasons for rejecting this TIP out of hand.  The
   availability of tcllib is not currently anything like universal
   (not stating whether this is a good, bad or ugly thing) and all the
   [[listx]] work will need its own TIP to make it into the core (you
   tend to have availability problems if it is an extension.)  It is
   not as if the core is short of syntactic sugar right now (the
   [[foreach]] command is ample demonstration of this.)

''Don Porter <[email protected]> follows up''
 > ''Don Porter <[email protected]>''

 > I'll leave the discussion above in place so the history
   of this TIP is preserved, but I have withdrawn my
   objection.

----

There was quite a discussion on news:comp.lang.tcl about using lindex
to return multiple arguments.  For example:

| % set list {a {b1 b2} c d e}
| % lindex $list 1
| b1 b2
| % lindex $list 1 0
| {b1 b2} a
| % lindex $list {1 0}
| b1

In other words, the list index arguments can, themselves, be lists.
Only when the argument is a list would the "recursive selection"
procedure of the TIP be used.  For multiple arguments, the behaviour
is akin to

| lindex $list a b c  ->
|      list [lindex $list a] [lindex $list b] [lindex $list c]

''Summarised by Dave Cuthbert <[email protected]>''

''Donal K. Fellows <[email protected]> points out''

 > The problems with the above version of multiple indexing are that
   it loses the property that [[lindex]] always returns a single
   element (making writing robust code harder) and that it forces use
   of the [[list]] constructor a lot or inefficient type handling when
   some of the indices must be computed.  Then there is the whole
   question of what happens when you have indexes that are lists of
   lists, which is a major can of worms.

 > Luckily, we could always put this sort of behaviour into a separate
   command (e.g. called [[lselect]]) which addresses at least the
   majority of my concerns, and which (in my opinion) need not even
   form part of this TIP.

''Dave Cuthbert <[email protected]> adds''

 > I intentionally left [[lselect]] out of the original TIP (and it
   is still not present in the 02-April-2001 version).  As Donal points
   out, it is a major can of worms and, though there was general
   agreement on c.l.t that such a command would be useful, people had
   differing opinions on what form it should take.

 > Perhaps my view on TIPs is incorrect, but I try to include only
   sure-fire "yeah, we ought to have done that a few versions ago"
   items.

----

~ Notes on History of this TIP

''This TIP was originally written by Dave Cuthbert <[email protected]>,
but ownership has passed (beginning of April) to Kevin Kenny
<[email protected]>.''

This TIP underwent substantial revision in May of 2001, to add the
syntax where all the ''index'' parameters could be grouped as a list
rather than placed inline on the command line.

~ See Also

[33].

~ Copyright

This document has been placed in the public domain.

TIP:            23
Title:          Tk Toolkit Functional Areas for Maintainer Assignments
Version:        $Revision: 1.19 $
Version:        $Revision: 1.5 $
Author:         Kevin Kenny <[email protected]>
Author:         Jim Ingham <[email protected]>
Author:         Don Porter <[email protected]>
State:          Accepted
State:          Draft
Type:           Process
Vote:           Done
Vote:           Pending
Created:        22-Jan-2001
Post-History:   

~ Abstract

This document proposes a division of the Tk toolkit's source code into
functional areas so that each area may be assigned to one or more

from source files to maintainers.  It also breaks out maintainers'
functional areas for the Tcl core.  This document attempts to develop
a similar mapping for the Tk toolkit.

Just as with [16], this document attempts to divide the Tk toolkit
into a set of the smallest sensible functional units.

One other factor, which was not addressed in [16], is that there is
considerably more platform dependent code in Tk than in Tcl, and it is
unreasonable to expect people to take ownership for pieces of code
that run on platforms they don't have access to.  However, we want to
make sure that the maintainer structure supports the cross-platform
nature of Tk.

To that end, in any area where there is both generic code, and
platform specific code, we propose that maintainers can sign up for
the generic code ''and'' code for one or more platforms.  By
overlapping the generic code, we ensure that the public interfaces to
Tk will stay consistent among the platforms, while not forcing
maintainers to presume expertise in code they can't even compile, much
less test or understand fully.

~ Proposal

The Tk toolkit shall be divided into the following eighty-six functional
units, each to be assigned one or more maintainers.  Each area will also
The Tk toolkit shall be divided into the following ninety-two functional
units, each to be assigned one or more maintainers:
be a Category in the SourceForge Tracker for Tk:

   Widgets: 

   >  1. ''Bindings'' -
     library/tk.tcl
   >  1. ''Standard bindings'' - library/tk.tcl

   >  2. ''Appearance'' -
     generic/default.h,
   >  2. ''Default appearance'' - generic/default.h,
     mac/tkMacDefault.h,
     unix/tkUnixDefault.h,
     win/tkWinDefault.h

   >  3. ''[*button] and [label]'' -
   >  3. ''button, checkbutton, radiobutton, label'' -
     doc/button.n,
     doc/checkbutton.n,
     doc/label.n,
     doc/radiobutton.n,
     generic/tkButton.c,
     generic/tkButton.h,
     library/button.tcl,
     mac/tkMacButton.c,
     unix/tkUnixButton.c,
     tests/butGeom.tcl,
     tests/butGeom2.tcl,
     tests/button.test,
     tests/unixButton.test,
     tests/winButton.test,
     win/rc/buttons.bmp,
     win/tkWinButton.c

   >  4. ''Canvas Basics'' -
   >  4. ''canvas (Basics)'' -
     doc/CanvPsY.3,
     doc/CanvTxtInfo.3,
     doc/CanvTkwin.3,
     doc/CrtItemType.3,
     doc/GetDash.3,
     doc/canvas.n,
     generic/tkCanvUtil.c,
     generic/tkCanvas.c,
     generic/tkCanvas.h,
     tests/canvas.test

   >  5. ''Canvas Items'' -
   >  5. ''canvas (Canvas items)'' -
     generic/tkCanvArc.c,
     generic/tkCanvBmap.c,
     generic/tkCanvImg.c,
     generic/tkCanvLine.c,
     generic/tkCanvPoly.c,
     generic/tkCanvText.c,
     generic/tkCanvWind.c,
     generic/tkRectOval.c,
     tests/arc.tcl,
     tests/canvImg.test,
     tests/canvRect.test,
     tests/canvText.test,
     tests/canvWind.test
     tests/canvWind.test,

   >  6. ''Canvas PostScript'' -
   >  6. ''canvas (PostScript printing)'' -
     generic/prolog.ps,
     generic/tkCanvPs.c,
     library/prolog.ps,
     tests/canvPs.test,
     tests/canvPsArc.tcl,
     tests/canvPsBmap.tcl,
     tests/canvPsGrph.tcl,
     tests/canvPsImg.tcl,
     tests/canvPsText.tcl

   >  7. ''[entry]'' -
   >  7. ''entry'' -
     doc/entry.n,
     generic/tkEntry.c,
     library/entry.tcl,
     tests/entry.test

   >  8. ''[frame] and [toplevel]'' -
   >  8. ''frame and toplevel'' -
     doc/frame.n,
     doc/toplevel.n,
     generic/tkFrame.c,
     tests/frame.test

   >  9. ''[listbox]'' -
   >  9. ''listbox'' -
     doc/listbox.n,
     generic/tkListbox.c,
     library/listbox.tcl,
     tests/listbox.test

   >  10. ''Generic Menus'' -
   >  10. ''menu, menubutton, and tk_popup (Generic)'' -
     doc/menu.n,
     doc/menubutton.n,
     doc/popup.n,
     generic/tkMacWinMenu.c,
     generic/tkMenu.c,
     generic/tkMenu.h,
     generic/tkMenuDraw.c,
     generic/tkMenubutton.c,
     generic/tkMenubutton.h,
     library/menu.tcl,
     library/tearoff.tcl,
     tests/macWinMenu.test,
     tests/menu.test,
     tests/menuDraw.test,
     tests/menubut.test
     tests/menubut.test,

   >  11. ''Mac Menus'' -
   >  11. ''menu, etc. (Macintosh)'' -
     mac/tkMacMDEF.c,
     mac/tkMacMDEF.r,
     mac/tkMacMenu.c,
     mac/tkMacMenu.r,
     mac/tkMacMenubutton.c,
     mac/tkMacMenus.c,
     tests/macMenu.test

   >  12. ''Unix Menus'' -
   >  12. ''menu, etc. (Unix)'' -
     tests/unixMenu.test,
     unix/tkUnixMenu.c,
     unix/tkUnixMenubu.c

   >  13. ''Win Menus'' -
   >  13. ''menu, etc. (Windows)'' -
     tests/winMenu.test,
     win/tkWinMenu.c

   >  14. ''[message]'' -
   >  14. ''message'' -
     doc/message.n,
     generic/tkMessage.c,
     tests/message.test

   >  15. ''[scale]'' -
   >  15. ''scale'' -
     doc/scale.n,
     generic/tkScale.c,
     generic/tkScale.h,
     library/scale.tcl,
     mac/tkMacScale.c,
     tests/scale.test,
     unix/tkUnixScale.c
     unix/tkUnixScale.c,

   >  16. ''[scrollbar]'' -
   >  16. ''scrollbar'' -
     doc/scrollbar.n,
     generic/tkScrollbar.c,
     generic/tkScrollbar.h,
     library/scrlbar.tcl,
     mac/tkMacScrlbr.c,
     tests/macscrollbar.test,
     tests/scrollbar.test,
     unix/tkUnixScrlbr.c,
     win/tkWinScrlbr.c

   >  17. ''[spinbox]'' -
   >  17. ''spinbox'' -
     doc/spinbox.n,
     library/spinbox.tcl,
     tests/spinbox.test

   >  18. ''[text]'' -
   >  18. ''text'' -
     doc/text.n,
     generic/tkText.c,
     generic/tkText.h
     generic/tkTextBTree.c,
     generic/tkTextDisp.c,
     generic/tkTextImage.c,
     generic/tkTextIndex.c,
     generic/tkTextMark.c,
     generic/tkTextTag.c,
     generic/tkTextWind.c,
     library/text.tcl,
     tests/text.test,
     tests/textBTree.test,
     tests/textDisp.test,
     tests/textImage.test,
     tests/textIndex.test,
     tests/textMark.test,
     tests/textTag.test,
     tests/textWind.test

   >  19. ''Menubars (obsolete)'' -
   >  19. ''tk_menubar (Deprecated)'' -
     doc/menubar.n,
     library/obsolete.tcl

   >  20. ''[tk_optionMenu]'' -
   >  20. ''tk_optionMenu'' -
     doc/optionMenu.n,
     library/optMenu.tcl
     library/optionMenu.tcl

   Widget Options: 

   >  1. ''Standard options'' -
     doc/options.n

   >  1. ''Option Parsing'' -
   >  2. ''Option parsing'' -
     doc/ConfigWidg.3,
     doc/SetOptions.3,
     generic/tkConfig.c,
     generic/tkOldConfig.c,
     mac/tkMacConfig.c,
     unix/tkUnixConfig.c,
     tests/config.test,
     win/tkWinConfig.c

   >  2. ''Relief'' -
   >  3. ''Relief'' -
     doc/3DBorder.3,
     doc/GetRelief.3,
     generic/tk3d.c,
     generic/tk3d.h,
     unix/tkUnix3d.c,
     tests/bevel.tcl,
     tests/border.tcl,
     win/tkWin3d.c

   >  3. ''Built-in Bitmaps'' -
   >  4. ''Standard bitmaps'' -
     bitmaps/error.bmp,
     bitmaps/gray12.bmp,
     bitmaps/gray25.bmp,
     bitmaps/gray50.bmp,
     bitmaps/gray75.bmp,
     bitmaps/hourglass.bmp,
     bitmaps/info.bmp,
     bitmaps/questhead.bmp,
     bitmaps/question.bmp,
     bitmaps/warning.bmp,
     doc/GetBitmap.3,
     generic/tkBitmap.c,
     mac/tkMacBitmap.c,
     tests/bitmap.test

   >  4. ''Conversions From String'' -
   >  5. ''Anchors, line styles, justification, and metrics'' -
     doc/GetAnchor.3,
     doc/GetCapStyl.3,
     doc/GetJoinStl.3,
     doc/GetJustify.3,
     doc/GetPixels.3,
     doc/GetUid.3,
     generic/tkGet.c,
     tests/get.test

   >  5. ''Objects'' - 
     generic/tkObj.c,
     tests/get.test,
     tests/obj.test

   >  6. ''Utility Functions'' -
   >  6. ''Focus highlights and scroll quantities'' -
     doc/DrawFocHlt.3,
     doc/GetScroll.3,
     generic/tkUtil.c,
     tests/util.test

   >  7. ''Colormaps and Visuals'' -
   >  7. ''Colormaps and visuals'' -
     doc/GetClrmap.3,
     doc/GetVisual.3,
     generic/tkVisual.c,
     tests/visual.test

   >  8. ''Color Names'' -
   >  8. ''Color names'' -
     doc/GetColor.3,
     doc/colors.n,
     generic/tkColor.c,
     generic/tkColor.h,
     mac/tkMacColor.c,
     unix/tkUnixColor.c,
     tests/cmap.tcl,
     tests/color.test,
     win/tkWinColor.c,
     xlib/colors.c

   >  9. ''Cursor Names'' -
   >  9. ''Cursor names'' -
     doc/GetCursor.3,
     doc/cursors.n,
     generic/tkCursor.c,
     mac/tkMacCursor.c,
     mac/tkMacCursors.r,
     mac/tkMacXCursors.r,
     unix/tkUnixCursor.c,
     tests/cursor.test,
     win/rc/cursor*.cur,
     win/rc/cursor*.cur
     win/tkWinCursor.c,
     xlib/X11/cursorfont.h

   >  10. ''Key Symbols'' -
   >  10. ''Key symbols'' -
     doc/keysyms.n,
     mac/tkMacKeyboard.c,
     unix/tkUnixKey.c,
     win/tkWinKey.c,
     xlib/X11/keysym.h,
     xlib/X11/keysymdef.h

   Standard Dialogs: 

   >  1. ''Generic Dialog Support'' -
   >  1. ''Common code'' -
     library/comdlg.tcl

   >  2. ''[tk_chooseColor]'' -
   >  2. ''Color selection'' -
     doc/chooseColor.n,
     library/clrpick.tcl,
     tests/clrpick.test

   >  3. ''[tk_dialog]'' -
   >  3. ''tk_dialog'' -
     doc/dialog.n,
     library/dialog.tcl,
     mac/tkMacDialog.c,
     tests/winDialog.test,
     unix/tkUnixDialog.c,
     win/tkWinDialog.c

   >  4. ''[tk_chooseDirectory]'' -
   >  4. ''Directory selection'' -
     doc/chooseDirectory.n,
     library/choosedir.tcl,
     tests/choosedir.test

   >  5. ''[tk_get*File]'' -
   >  5. ''File selection'' -
     doc/getOpenFile.n,
     generic/tkFileFilter.c,
     generic/tkFileFilter.h,
     library/tkfbox.tcl,
     library/xmfbox.tcl,
     tests/filebox.test,
     tests/xmfbox.test

   >  6. ''[tk_messageBox]'' -
   >  6. ''tk_messageBox'' -
     doc/messageBox.n,
     library/msgbox.tcl,
     tests/msgbox.test

   Images: 

   >  1. ''Image Basics'' -
   >  1. ''Basic image support'' -
     doc/CrtImgType.3,
     doc/DeleteImg.3,
     doc/GetImage.3,
     doc/ImgChanged.3,
     doc/NameOfImg.3,
     doc/image.n,
     generic/tkImage.c,
     generic/tkImgUtil.c,
     generic/tkStubImg.c,
     tests/image.test

   >  2. ''Bitmap Images'' -
   >  2. ''Bitmap images'' -
     doc/bitmap.n,
     generic/tkImgBmap.c,
     tests/imgBmap.test

   >  3. ''Photo Images'' -
   >  3. ''Photo images'' -
     doc/CrtPhImgFmt.3,
     doc/FindPhoto.3,
     doc/photo.n,
     generic/tkImgPhoto.c,
     tests/imgPhoto.test

   >  4. ''Photo Image|GIF'' -
   >  4. ''GIF support'' -
     generic/tkImgGIF.c

   >  5. ''Photo Image|PPM'' -
   >  5. ''PPM support'' -
     generic/tkImgPPM.c,
     tests/imgPPM.test

   Fonts: 

   >  1. ''Generic Fonts'' -
   >  1. ''Fonts'' -
     doc/FontId.3,
     doc/GetFont.3,
     doc/MeasureChar.3,
     doc/TextLayout.3,
     doc/font.n,
     generic/tkFont.c,
     generic/tkFont.h,
     tests/font.test

   >  2. ''Mac Fonts'' -
   >  2. ''Macintosh font support'' -
     mac/tkMacFont.c,
     tests/macFont.test

   >  3. ''Unix Fonts'' -
   >  3. ''Unix font support'' -
     tests/unixFont.test,
     unix/tkUnixFont.c

   >  4. ''Win Fonts'' -
   >  4. ''Windows font support'' -
     tests/winFont.test,
     win/tkWinFont.c

   Geometry management: 

   >  1. ''Geometry Management'' -
   >  1. ''Common geometry management'' -
     doc/GeomReq.3,
     doc/MaintGeom.3,
     doc/ManageGeom.3,
     generic/tkGeometry.c,
     tests/geometry.test

   >  2. ''[grid]'' -
   >  2. ''grid'' -
     doc/grid.n,
     generic/tkGrid.c,
     tests/grid.test

   >  3. ''[pack]'' -
   >  3. ''pack'' -
     doc/pack-old.n,
     doc/pack.n,
     generic/tkPack.c,
     tests/oldpack.test,
     tests/pack.test

   >  4. ''[place]'' -
   >  4. ''place'' -
     doc/place.n,
     generic/tkPlace.c,
     tests/place.test

   Selection and Clipboard: 

   >  1. ''[clipboard]'' -
   >  1. ''clipboard'' -
     doc/Clipboard.3,
     doc/clipboard.n,
     generic/tkClipboard.c,
     mac/tkMacClipboard.c,
     tests/clipboard.test,
     tests/unixSelect.test,
     tests/winClipboard.test,
     unix/tkUnixSelect.c,
     win/tkWinClipboard.c

   >  2. ''[selection]'' -
   >  2. ''selection'' -
     doc/ClrSelect.3,
     doc/CrtSelHdlr.3,
     doc/GetSelect.3,
     doc/OwnSelect.3,
     doc/selection.n,
     generic/tkSelect.c,
     generic/tkSelect.h,
     tests/select.test

   Other Tk commands: 

    >  1. ''[console]'' -
     doc/console.n
    >  1. ''console'' --
     generic/tkConsole.c,
     library/console.tcl

    >  2. ''[focus]'' -
    >  2. ''focus'' -
     doc/focus.n,
     generic/tkFocus.c,
     tests/focus.test

    >  3. ''[grab]'' -
    >  3. ''grab'' -
     doc/Grab.3,
     doc/grab.n,
     generic/tkGrab.c,
     tests/grab.test

    >  4. ''[option]'' -
    >  4. ''option'' -
     doc/AddOption.3,
     doc/GetOption.3,
     doc/option.n,
     generic/tkOption.c,
     tests/option.file1,
     tests/option.file2,
     tests/option.test

   >  5. ''[send]'' -
   >  5. ''send'' -
     doc/SetAppName.3,
     doc/send.n,
     mac/tkMacSend.c,
     tests/send.test,
     tests/unixSend.test,
     tests/winSend.test,
     unix/tkUnixSend.c,
     win/tkWinSend.c

   >  6. ''[tk_focus*]'' -
   >  6. ''tk_focusNext and friends'' -
     doc/focusNext.n,
     library/focus.tcl,
     tests/focusTcl.test

   >  7. ''[tk_setPalette]'' -
   >  7. ''tk_palette'' -
     doc/palette.n,
     library/palette.tcl

   >  8. ''Safe Tk'' -
     doc/loadTk.n,
     library/safetk.tcl,
     tests/safe.test

   Low-level Tk functions: 

   >  1. ''Geometry Functions'' -
   >  1. ''Geometry'' -
     generic/tkTrig.c

   >  2. ''Tk_Win Functions'' -
   >  2. ''Tk_Win functions'' -
     doc/ConfigWind.3,
     doc/CrtWindow.3,
     doc/IdToWindow.3,
     doc/MainWin.3,
     doc/MapWindow.3,
     doc/Name.3,
     doc/Restack.3,
     doc/SetClass.3,
     doc/SetClassProcs.3,
     doc/SetVisual.3,
     doc/StrictMotif.3,
     doc/Tk_Init.3,
     doc/WindowId.3,
     generic/tkWindow.c,
     tests/window.test

   >  3. ''Graphic Contexts'' -
   >  3. ''Graphic contexts'' -
     doc/GetGC.3,
     generic/tkGC.c

   >  4. ''Generic Window Operations'' -
   >  4. ''Basic window manipulations'' -
     doc/CoordToWin.3,
     doc/FreeXId.3,
     doc/GetHINSTANCE.3,
     doc/GetHWND.3,
     doc/GetPixmap.3,
     doc/GetRootCrd.3,
     doc/GetVRoot.3,

     tests/cmds.test,
     tests/id.test,
     tests/raise.test,
     tests/tk.test,
     tests/winfo.test,
     xlib/xgc.c

   >  5. ''Mac Window Operations'' -
   >  5. ''Macintosh window operations'' -
     mac/tkMacAppearanceStubs.c,
     mac/tkMacDraw.c,
     mac/tkMacEmbed.c,
     mac/tkMacHLEvents.c,
     mac/tkMacRegion.c,
     mac/tkMacSubwindows.c,
     mac/tkMacWindowMgr.c,
     mac/tkMacWm.c,
     mac/tkMacXStubs.c,
     tests/macEmbed.test

   >  6. ''Unix Window Operations'' -
     
   >  6. ''Unix window operations'' -
     tests/unixEmbed.test,
     tests/unixWm.test,
     unix/tkUnix.c,
     unix/tkUnixDraw.c,
     unix/tkUnixEmbed.c,
     unix/tkUnixEvent.c,
     unix/tkUnixFocus.c,
     unix/tkUnixWm.c,
     unix/tkUnixXId.c

   >  7. ''Win Window Operations'' -
   >  7. ''Windows window operations'' -
     tests/WinWm.test,
     win/stubs.c,
     win/tkWinDraw.c,
     win/tkWinEmbed.c,
     win/tkWinImage.c,
     win/tkWinPixmap.c,
     win/tkWinPointer.c,
     win/tkWinRegion.c,
     win/tkWinWindow.c,
     win/tkWinWm.c,
     win/tkWinX.c

   >  8. ''Events'' -
     doc/BindTable.3,
     doc/event.n,
     generic/tkBind.c,
     tests/bind.test

   >  9. ''Event Loop'' -
   >  9. ''Event loop'' -
     doc/CrtCmHdlr.3,
     doc/CrtGenHdlr.3,
     doc/EventHndlr.3,
     doc/HandleEvent.3,
     doc/MainLoop.3,
     doc/QWinEvent.3,
     doc/RestrictEv.3,
     generic/tkEvent.c,
     tests/event.test

   >  10. ''Error Handling'' -
   >  10. ''Error handling'' -
     doc/CrtErrHdlr.3,
     doc/tkerror.n,
     generic/tkError.c,
     library/bgerror.tcl,
     tests/bgerror.test

   >  11. ''Atoms'' -
     doc/InternAtom.3,
     generic/tkAtom.c,
     xlib/X11/Xatom.h

   Shells: 

   >  1. ''Argv Parsing'' -
   >  1. ''Argc/argv parsing'' -
     doc/ParseArgv.3,
     generic/tkArgv.c

   >  2. ''Application Embedding'' -
   >  2. ''Application embedding'' -
     doc/Tk_Main.3,
     doc/loadTk.n,
     generic/tkInitScript.h,
     generic/tkMain.c,
     mac/tkMacInit.c,
     unix/tkUnixInit.c,
     win/tkWin32DLL.c,
     win/tkWinInit.c,
     tests/main.test,
     tests/safe.test

   >  3. ''wish'' -
     doc/wish.1,
     mac/tkMacAppInit.c,
     unix/tkAppInit.c,
     win/winMain.c

   >  4. ''Mac DND Tclets'' -
   >  4. ''Drag and Drop Tclets (Macintosh)'' -
     mac/tclets.r,
     mac/tclets.tcl

   Demonstrations: 

   >  1. ''Widget Tour'' -
     library/demos/arrow.tcl,

     library/demos/images/gray25.bmp,
     library/demos/images/letters.bmp,
     library/demos/images/noletter.bmp,
     library/demos/images/pattern.bmp,
     library/demos/images/tcllogo.gif,
     library/demos/images/teapot.ppm

   >  2. ''Square Demo'' -
   >  2. ''The square extension'' -
     generic/tkSquare.c,
     library/demos/square

   >  3. ''Other Demos'' -
   >  3. ''Miscellaneous demos'' -
     library/demos/browse,
     library/demos/hello,
     library/demos/ixset,
     library/demos/rmt,
     library/demos/rolodex,
     library/demos/tcolor,
     library/demos/timer

   Localization: 

   >  1. ''L10N'' -
     library/msgs/de.msg,
     library/msgs/el.msg,
     library/msgs/en.msg,
     library/msgs/es.msg,
     library/msgs/fr.msg,
     library/msgs/it.msg,
   >  1. ''German'' -
     library/msgs/de.msg

   >  2. ''Greek'' -
     library/msgs/el.msg

   >  3. ''English'' -
     library/msgs/en.msg

   >  4. ''Spanish'' -
     library/msgs/es.msg

   >  5. ''French'' -
     library/msgs/fr.msg

   >  6. ''Italian'' -
     library/msgs/it.msg

   >  7. ''Dutch'' -
     library/msgs/nl.msg

   Release Engineering: 

   >  1. ''Release Notes'' -
     README,
     */README,
     */*/README,
     changes,
     license.terms,
     tk4.0.ps,
     doc/options.n
     mac/bugs.doc,
     tests/bugs.tcl
     tests/bugs.tcl,

   >  2. ''Portability'' -
   >  2. ''Portability Support'' -
     compat/limits.h,
     compat/stdlib.h,
     compat/unistd.h

   >  3. ''X11 Emulation'' -
   >  3. ''X11 Emulation Support'' -,
     xlib/X11/X.h,
     xlib/X11/Xfuncproto.h,
     xlib/X11/Xlib.h,
     xlib/X11/Xutil.h,
     xlib/xbytes.h,
     xlib/xdraw.c,
     xlib/ximage.c,
     xlib/xutil.c

   >  4. ''Mac Build'' -
   >  4. ''Macintosh Configuration and Build Tools'' -
     mac/MW_TkHeader.h,
     mac/MW_TkHeader.pch,
     mac/MW_TkOldImgHeader.h,
     mac/MW_TkTestHeader.h,
     mac/MW_TkTestHeader.pch,
     mac/tkMacApplication.r,
     mac/tkMacLibrary.r,
     mac/tkMacProjects.sea.hqx,
     mac/tkMacResource.r,
     mac/tkMacShlib.exp

   >  5. ''Unix Build'' -
   >  5. ''Unix configuration and Build Tools'' -
     unix/Makefile.in,
     unix/aclocal.m4,
     unix/configure.in,
     unix/install-sh,
     unix/mkLinks,
     unix/tcl.m4,
     unix/tk.spec,
     unix/tkConfig.sh.in

   >  6. ''Win Build'' -
   >  6. ''Windows Configuration and Build Tools'' -
     win/Makefile.in,
     win/aclocal.m4,
     win/configure.in,
     win/makefile.vc,
     win/mkd.bat,
     win/rc/tk.rc,
     win/rc/tk_base.rc,

     generic/tkTest.c,
     mac/tkMacTest.c,
     win/tkWinTest.c,
     tests/all.tcl,
     tests/defs.tcl,
     tests/visual_bb.test

   >  8. ''Logos'' -
   >  8. ''Logos and Branding'' -
     library/images/logo.eps,
     library/images/logo100.gif,
     library/images/logo64.gif,
     library/images/logoLarge.gif,
     library/images/logoMed.gif,
     library/images/pwrdLogo.eps,
     library/images/pwrdLogo100.gif,

The following files are shared by all of Tk.  Any maintainer may
modify them as necessary to complete changes they are making to
their portion of Tk.  Some of the following files define Tk's
API and should be changed only with TCT approval.

   * ChangeLog,
     changes,
     doc/tkvars.n,
     doc/TkInitStubs.3,
     doc/man.macros,
     generic/tk.decls,
     generic/tk.h,
     generic/tkInt.decls,
     generic/tkInt.h,
     generic/tkPort.h,
     generic/tkPort.h
     generic/tkStubLib.c,
     mac/tkMac.h,
     mac/tkMacInt.h,
     mac/tkMacPort.h,
     unix/tkUnixInt.h,
     unix/tkUnixPort.h,
     win/tkWinInt.h,
     win/tkWinPort.h

~ Generated Files

The following files are generated, so they don't need maintainers.

   * generic/ks_names.h,
     generic/tkDecls.h,
     generic/tkIntDecls.h,
     generic/tkIntPlatDecls.h,
     generic/tkIntXlibDecls.h,
     generic/tkPlatDecls.h,
     generic/tkStubInit.c,
     library/demos/tclIndex
     library/tclIndex
     unix/configure,
     unix/mkLinks,
     win/configure

~ Platform Dependencies

In addition to the division into functional areas, responsibility for
a given area can also be qualified by one or more ''platform''
specifiers.  Some areas, like ''Windows Configuration and Build
Tools'' are obviously platform specific, so the qualification is
unnecessary.  Others, like ''Canvas Items'', are wholly generic.  But
others, like ''Button'', ''Scale'' or ''Scrollbar'' contain code for
all platforms.

A maintainer can sign up for one of these latter areas, but specify
support for only one platform.  This means that that person will be
responsible for the generic code in this area, in conjunction with the
other platform maintainers in this area, and the platform specific
code in that area.

The point behind sharing the generic code among all the maintainers is
so that any changes to the Tk visible face of the widget be designed
in concert for all platforms.  Therefore, it is the responsibility of
a platform maintainer for one platform who is sponsering a new feature
for that area to work with the other platform maintainers to ensure
that the feature is implemented on all platforms.  One of the
strengths of Tk is its cross-platform nature, and one of the
maintainer's jobs is to ensure that this continues.

Procedurally, the maintainer will be listed as ''Button Widget -
Macintosh'', etc.  A maintainer for a given area can sign up for one
or more platforms.  Due to the good design of the Tk's platform
dependencies, determining which files are generic, and which are
platform specific is trivial.  The generic ones are in the ''generic''
directory, the Mac ones in the ''mac'' directory, etc.  Similarly, an
area which has NO files in the mac, win, or unix directories is a
generic area, and no qualifiers are needed.

~ Copyright

This document has been placed in the public domain.

TIP:            24
Title:          Tcl Maintainer Assignments
Version:        $Revision: 1.24 $
Version:        $Revision: 1.1 $
Author:         Don Porter <[email protected]>
Author:         Donal K. Fellows <[email protected]>
Author:         Kevin B KENNY <[email protected]>
Author:         <[email protected]>
Author:         Jeff Hobbs <[email protected]>
State:          Draft
Type:           Informative
Vote:           Pending
Created:        29-Jan-2001
Post-History:   

~ Abstract

This document keeps a record of who maintains each functional area
of Tcl ([16]).

~ Assignments

Listed below are Tcl's 52 functional units, in the same order as
in [16].  See [16] for the precise definition of what code belongs to
what area.  The area names are changed to match the Categories in Tcl's
SourceForge Bug Manager (http://sourceforge.net/bugs/?group_id=10894).

Note that an area can have more than one maintainer.  When the
maintenance of the entire area requires several types of
expertise, it is desirable to have more than one maintainer.

In several of the areas below, there are maintainers who have
volunteered to provide special expertise (for example, assistance
with programming and testing for the Mac platform) to assist
in maintaining an area, but who have not taken on the whole area.
These maintainers are indicated by a parenthesized designation
of their expertise.

For each of Tcl's functional units, the following maintainers are
assigned:

   1. ''Notifier'' - Daniel Steffen <[email protected]> (Mac),
   1. ''Notifier'' - 
                     Jim Ingham <[email protected]> (Mac),
                     Kevin Kenny <[email protected]> (Win32, Solaris, HP-UX)

   2. ''Event Loops'' - Jan Nijtmans <[email protected]>, Jeff Hobbs <[email protected]>
   1. ''Event Loops'' -

   3. ''Timer Events'' - Kevin Kenny <[email protected]>, Jeff Hobbs <[email protected]>
   1. ''Timer Events'' -

   4. ''Async Events'' - 
   1. ''Async Events'' - 

   5. ''XT Notifier'' - 
   1. ''XT Notifier'' - 

   6. ''Time Measurement'' -  Kevin Kenny <[email protected]>,
   1. ''Time Measurement'' - 
                              Daniel Steffen <[email protected]> (Mac),
                              Jim Ingham <[email protected]> (Mac),
			      Jeff Hobbs <[email protected]>

   7. ''Variables'' - Miguel Sofer <[email protected]>, Jeff Hobbs <[email protected]>
   1. ''Variables'' - 

   8. ''Environment Variables'' -
   1. ''Environment Variables'' - 
        Daniel Steffen <[email protected]> (Mac),
        Jim Ingham <[email protected]> (Mac)
	Jeff Hobbs <[email protected]>

   9. ''Linked C Variables'' - Jeff Hobbs <[email protected]>
   1. ''Linked C Variables'' - 

   10. ''Objects'' - Miguel Sofer <[email protected]>, Jeff Hobbs <[email protected]>
   1. ''Compiler and Objects'' - 

   11. ''Conversions from String'' - Jeff Hobbs <[email protected]>
   1. ''Conversions from String'' - 

   12. ''ByteArray Objects'' - Jan Nijtmans <[email protected]>, Jeff Hobbs <[email protected]>
   1. ''ByteArray Objects'' - 

   13. ''Index Object'' - Jan Nijtmans <[email protected]>, Jeff Hobbs <[email protected]>
   1. ''Index Object'' - 

   14. ''List Object'' - Jan Nijtmans <[email protected]>, Jeff Hobbs <[email protected]>

   15. ''Commands A-H'' - Donal K. Fellows <[email protected]>, Jeff Hobbs <[email protected]>

   16. ''Commands I-L'' - Donal K. Fellows <[email protected]>, Jeff Hobbs <[email protected]>
   1. ''List Object'' - 

   17. ''Commands M-Z'' - Donal K. Fellows <[email protected]>, Jeff Hobbs <[email protected]>
   1. ''Commands A-H'' - 

   18. ''[[history]]'' - Jeff Hobbs <[email protected]>

   1. ''Commands I-L'' - 
   19. ''[[interp]]'' - Jeff Hobbs <[email protected]>

   20. ''[[namespace]]'' - Miguel Sofer <[email protected]>, Jeff Hobbs <[email protected]>

   1. ''Commands M-Z'' - 
   21. ''[[proc]] and [[uplevel]]'' - Miguel Sofer <[email protected]>, Jeff Hobbs <[email protected]>

   22. ''[[scan]]'' - Jeff Hobbs <[email protected]>
   1. ''History'' - 

   23. ''Channel Commands'' - Andreas Kupries <[email protected]>, Jeff Hobbs <[email protected]>
   1. ''Interp Command'' - 

   24. ''Channel System'' - Andreas Kupries <[email protected]>, Jeff Hobbs <[email protected]>

   1. ''Namespaces'' - 
   25. ''Channel Transforms'' - Andreas Kupries <[email protected]>, Jeff Hobbs <[email protected]>

   26. ''Channel Types'' - Andreas Kupries <[email protected]>,
   1. ''Procedures'' - 
                          Rolf Schroedter <[email protected]> (WinSerial),
                          Daniel Steffen <[email protected]> (Mac),
                          Jim Ingham <[email protected]> (Mac),
			  Jeff Hobbs <[email protected]>

   27. ''dde Package'' - Kevin Kenny <[email protected]>
   1. ''Scan Command'' - 

   28. ''http Package'' - Jeff Hobbs <[email protected]>
   1. ''Channel Commands'' - 

   29. ''msgcat Package'' - 
   1. ''Channel System'' - 

   30. ''opt Package'' - 
   1. ''Channel Transforms'' - 

   31. ''registry Package'' - Kevin Kenny <[email protected]>
   1. ''Channel Types'' - 

   32. ''Safe Base'' - Jeff Hobbs <[email protected]>
   1. ''dde Package'' - 

   33. ''tcltest Package'' - Jeff Hobbs <[email protected]>,
	Melissa Chawla <[email protected]>
   1. ''http Package'' - 

   1. ''msgcat Package'' - 

   34. ''Pathname Management'' -
        Daniel Steffen <[email protected]> (Mac),
        Jim Ingham <[email protected]> (Mac),
	Vincent Darley <[email protected]>,
	Jeff Hobbs <[email protected]>
   1. ''opt Package'' - 

   1. ''registry Package'' - 

   1. ''Safe Base'' - 

   1. ''Tcltest'' - 

   1. ''Pathname Management'' - 

   35. ''File System'' - Daniel Steffen <[email protected]> (Mac),
   1. ''File System'' - 
                        Jim Ingham <[email protected]> (Mac),
			Vincent Darley <[email protected]>,
			Jeff Hobbs <[email protected]>

   36. ''Init - Library - Autoload'' -
   1. ''Init - Library - Autoload'' -
        Don Porter <[email protected]>,
        Daniel Steffen <[email protected]> (Mac),
        Jim Ingham <[email protected]> (Mac),
	Jeff Hobbs <[email protected]>

   37. ''Package Manager'' -  Don Porter <[email protected]>, Jeff Hobbs <[email protected]>
   1. ''Package Manager'' - 

   38. ''Dynamic Loading'' -  Kevin Kenny <[email protected]>,
   1. ''Dynamic Loading'' - 
                             Daniel Steffen <[email protected]> (Mac),
                             Jim Ingham <[email protected]> (Mac),
                             Jan Nijtmans <[email protected]>,
			     Jeff Hobbs <[email protected]>

   39. ''Memory Allocation'' - Jeff Hobbs <[email protected]>
   1. ''Memory Allocation'' - 

   40. ''Memory Preservation'' - Jeff Hobbs <[email protected]>

   41. ''Regexp'' -

   1. ''Memory Preservation'' - 

   1. ''Regexp'' -

   42. ''UTF-8 Strings'' - Jan Nijtmans <[email protected]>, Jeff Hobbs <[email protected]>
   1. ''UTF-8 Strings'' -

   43. ''Parsing and Eval'' - Miguel Sofer <[email protected]>, Jeff Hobbs <[email protected]>
   1. ''Parsing and Eval'' -

   44. ''Bytecode Compiler'' - Miguel Sofer <[email protected]>, Jeff Hobbs <[email protected]>
   1. ''Bytecodes'' -

   45. ''Threading'' - Andreas Kupries <[email protected]>,
   1. ''Threading'' -
                      Daniel Steffen <[email protected]> (Mac),
                      Jim Ingham <[email protected]> (Mac),
		      Jeff Hobbs <[email protected]>

   46. ''Embedding Support'' - Don Porter <[email protected]>,
   1. ''Embedding Support'' -
                              Daniel Steffen <[email protected]> (Mac),
                              Jim Ingham <[email protected]> (Mac),
			      Jeff Hobbs <[email protected]>

   47. ''Release Notes'' - Daniel Steffen <[email protected]> (Mac),
   1. ''Release Notes'' - 
                          Jim Ingham <[email protected]> (Mac),
			  Jeff Hobbs <[email protected]>

   48. ''Portability Support'' -
   1. ''Portability Support'' - 
        Mo DeJong <[email protected]>,
        Daniel Steffen <[email protected]> (Mac),
        Jim Ingham <[email protected]> (Mac),
	Jeff Hobbs <[email protected]>

   49. ''Configure and Build Tools'' - Mo DeJong <[email protected]>, Jeff Hobbs <[email protected]>,
   1. ''Configure and Build Tools'' - 
	Lloyd Lim <[email protected]>

   50. ''Other Tools'' - Jeff Hobbs <[email protected]>
   1. ''Other Tools'' - 

   51. ''[[resource]]'' - Daniel Steffen <[email protected]>
   1. ''resource Command'' - 
                      Jim Ingham <[email protected]>

   52. ''Macintosh'' - Daniel A. Steffen <[email protected]>,
   1. ''Macintosh'' -
                       Jim Ingham <[email protected]>

~ Orphaned Categories

The following Categories in Tcl's SourceForge Bug Tracker should be
mapped to new Categories corresponding to a maintained area of Tcl,
when seeking the appropriate maintainer:

   1. ''Build'' - map to ''Configure and Build Tools''.
   1. ''Other'' - Used for reports that span several categories.  Also
		  includes many closed old reports from before the time
		  the current categories were established.

   1. ''Clock'' - map to ''Time Measurement''.

   1. ''CodeCleanup'' - map to section of code being cleaned up.

   1. ''Commands'' - map to the specific command or one of ''A-H'',
      ''I-L'', or ''M-Z''.

   1. ''Docs'' - no longer a separate Category.  Map to the section
      of code being documented.

   1. ''Exec and Pipe'' - map to ''Channel Types''.

   1. ''File System (trash)'' - map to ''File System''.

   1. ''I18N'' - map to ???

   1. ''Installation'' - map to ''Configure and Build Tools''.

   1. ''Other'' - reassign once area is determined.

   1. ''Other IO'' - reassign to appropriate ''Channel'' category.

   1. ''Packaging'' - map to ???

   1. ''Sockets'' - map to ''Channel Types''.

   1. ''Tests'' - no longer a separate Category.  Map to the section
      of code being tested.

   1. ''Unix'' - map to specific problem on Unix.

   1. ''Windows'' - map to specific problem on Windows.

~ Sections Without Maintainers

Those sections without a maintainer are maintained by the Tcl Core
Team with each change requiring TYANNOTT review.

~ Copyright

This document has been placed in the public domain.

diff -c -r orig_2/tk8.4a2/doc/text.n try/tk8.4a2/doc/text.n
*** orig_2/tk8.4a2/doc/text.n	Fri Aug 25 08:58:33 2000
--- try/tk8.4a2/doc/text.n	Sat Jul  7 20:04:52 2001
***************
*** 26,31 ****
--- 26,34 ----
  \-highlightcolor	\-pady	\-yscrollcommand
  .SE
  .SH "WIDGET-SPECIFIC OPTIONS"
+ .OP \-autoseparators autoSseparators AutoSeparators
+ Specifies whether separators are automatically inserted in the undo
+ stack. Is only active when the \fB\-undo\fR option is true.
  .OP \-height height Height
  Specifies the desired height for the window, in units of characters
  in the font given by the \fB\-font\fR option.
***************
*** 83,88 ****
--- 86,94 ----
  If no \fB\-tabs\fR option is specified, or if it is specified as
  an empty list, then Tk uses default tabs spaced every eight
  (average size) characters.
+ .OP \-undo undo Undo
+ Specifies whether the undo mechanism is active (value \fB0\fR) or
+ not (value \fB1\fR).
  .OP \-width width Width
  Specifies the desired width for the window in units of characters
  in the font given by the \fB\-font\fR option.
***************
*** 141,146 ****
--- 147,155 ----
  widget.
  See EMBEDDED IMAGES below for more details.
  .VE
+ .PP
+ The text widget also has a built-in undo/redo mechanism. See 
+ UNDO MECHANISM below for more details.
  
  .SH INDICES
  .PP
***************
*** 682,687 ****
--- 691,699 ----
  If the selection is claimed away by another application or by another
  window within this application, then the \fBsel\fR tag will be removed
  from all characters in the text.
+ .IP [4]
+ Whenever the \fBsel\fR tag range changes a virtual event 
+ \fB<<Selection>>\fR is generated.
  .PP
  The \fBsel\fR tag is automatically defined when a text widget is
  created, and it may not be deleted with the ``\fIpathName \fBtag delete\fR''
***************
*** 702,707 ****
--- 714,760 ----
  cursor, and the insertion cursor will automatically be drawn at
  this point whenever the text widget has the input focus.
  
+ .SH "THE MODIFIED FLAG"
+ The text widget can keep track of changes to the content of the widget
+ by means of the modified flag. Inserting or deleting text will set
+ this flag. The flag can be queried, set and cleared programatically
+ as well. Whenever the flag changes state a \fB<<Modified>>\fR virtual 
+ event is generated. See the \fBedit modified\fR widget command for 
+ more details.
+ 
+ .SH "THE UNDO MECHANISM"
+ .PP
+ The text widget has an unlimited undo and redo mechanism. This undo 
+ mechanism is only active when the \fB-undo\fR widget option is true.
+ Every insert and delete action is recorded on this stack.
+ .PP
+ Boundaries are inserted between edit actions: the so-called 
+ separators. The purpose of these separators is to group inserts and
+ deletes into one compound edit action. When undoing a change everything
+ between two separators will be undone. The undone changes are then
+ moved to the redo stack, so that an undone edit can be redone again.
+ The redo stack is cleared whenever new edit actions are recorded
+ on the undo stack. The undo and redo stacks can be cleared to keep 
+ their depth under control.
+ .PP
+ Separators are inserted automatically when the 
+ \fB-autoseparators\fR widget option is true. You can insert separators
+ programatically as well. If a separator is already present at the top
+ of the undo stack no other will inserted. That means that two 
+ separators on the undo stack are always separated by at least one 
+ insert or delete action.
+ .PP
+ The undo mechanism is also linked to the modified flag. This means
+ that undoing or redoing changes can take a modified text widget back 
+ to the unmodified state or vice versa. The modified flag
+ will be set to automatically to the appropriate state. This 
+ automatic coupling does not work when the modified flag has been 
+ set by the user, until the flag has been reset again. 
+ 
+ .PP
+ See below for the \fBedit\fR widget command that controls the 
+ undo mechanism.
+ 
  .SH "WIDGET COMMAND"
  .PP
  The \fBtext\fR command creates a new Tcl command whose
***************
*** 863,868 ****
--- 916,956 ----
  window by its index position to get more information.
  .RE
  .TP
+ \fIpathName \fBedit \fIoption \fR?\fIarg arg ...\fR?
+ This command controls the undo mechanism and the modified flag.  
+ The exact behavior of the command depends on the \fIoption\fR 
+ argument that follows the \fBedit\fR argument.  The following 
+ forms of the command are currently supported:
+ .RS
+ .TP
+ \fIpathName \fBedit modified ?\fIboolean\fR?
+ If \fIboolean\fR is not specified, returns the modified flag of
+ the widget. The insert, delete, edit undo and edit redo commands
+ or the user can set or clear the modified flag.
+ If \fIboolean\fR is specified, sets the modified flag of the widget
+ to \fIboolean\fR.
+ .TP
+ \fIpathName \fBedit redo\fR
+ When the \fB-undo\fR option is true, reapplies the last undone 
+ edits provided no other edits were done since then. Generates an
+ error when the redo stack is empty.
+ Does nothing when the \fB-undo\fR option is false.
+ .TP
+ \fIpathName \fBedit reset\fR
+ Clears the undo and redo stacks.
+ .TP
+ \fIpathName \fBedit separator\fR
+ Inserts a separator (boundary) on the undo stack. Does nothing
+ when the \fB-undo\fR option is false.
+ .TP
+ \fIpathName \fBedit undo\fR
+ Undoes the last edit action when the \fB-undo\fR option is true. 
+ An edit action is defined as all the insert and delete commands that are 
+ recorded on the undo stack in between two separators. Generates an error
+ when the undo stack is empty.
+ Does nothing when the \fB-undo\fR option is false.
+ .RE
+ .TP
  \fIpathName \fBget \fIindex1 \fR?\fIindex2\fR?
  Return a range of characters from the text.
  The return value will be all the characters in the text starting
***************
*** 1591,1596 ****
--- 1679,1690 ----
  .IP [31]
  Control-t reverses the order of the two characters to the right of
  the insertion cursor. 
+ .IP [32]
+ Control-z undoes the last edit action if the \fB-undo\fR option is
+ true. Does nothing otherwise.
+ .IP [33]
+ Control-Z reapplies the last undone edit action if the \fB-undo\fR 
+ option is true. Does nothing otherwise.
  .PP
  If the widget is disabled using the \fB\-state\fR option, then its
  view can still be adjusted and text can still be selected,
diff -c -r orig_2/tk8.4a2/generic/tkText.c try/tk8.4a2/generic/tkText.c
*** orig_2/tk8.4a2/generic/tkText.c	Tue Jul 25 02:05:40 2000
--- try/tk8.4a2/generic/tkText.c	Sun Jul  8 07:48:11 2001
***************
*** 42,47 ****
--- 42,50 ----
   */
  
  static Tk_ConfigSpec configSpecs[] = {
+     {TK_CONFIG_BOOLEAN, "-autoseparators", "autoSeparators",
+         "AutoSeparators", DEF_TEXT_AUTO_SEPARATORS,
+         Tk_Offset(TkText, autoSeparators), 0},
      {TK_CONFIG_BORDER, "-background", "background", "Background",
  	DEF_TEXT_BG_COLOR, Tk_Offset(TkText, border), TK_CONFIG_COLOR_ONLY},
      {TK_CONFIG_BORDER, "-background", "background", "Background",
***************
*** 129,134 ****
--- 132,139 ----
      {TK_CONFIG_STRING, "-takefocus", "takeFocus", "TakeFocus",
  	DEF_TEXT_TAKE_FOCUS, Tk_Offset(TkText, takeFocus),
  	TK_CONFIG_NULL_OK},
+     {TK_CONFIG_BOOLEAN, "-undo", "undo", "Undo",
+         DEF_TEXT_UNDO, Tk_Offset(TkText, undo), 0},
      {TK_CONFIG_INT, "-width", "width", "Width",
  	DEF_TEXT_WIDTH, Tk_Offset(TkText, width), 0},
      {TK_CONFIG_CUSTOM, "-wrap", "wrap", "Wrap",
***************
*** 292,297 ****
--- 297,304 ----
  			    int offset, char *buffer, int maxBytes));
  static int		TextSearchCmd _ANSI_ARGS_((TkText *textPtr,
  			    Tcl_Interp *interp, int argc, char **argv));
+ static int              TextEditCmd _ANSI_ARGS_((TkText *textPtr,
+                             Tcl_Interp *interp, int argc, char **argv));
  static int		TextWidgetCmd _ANSI_ARGS_((ClientData clientData,
  			    Tcl_Interp *interp, int argc, char **argv));
  static void		TextWorldChanged _ANSI_ARGS_((
***************
*** 304,309 ****
--- 311,336 ----
  static int		DumpSegment _ANSI_ARGS_((Tcl_Interp *interp, char *key,
  			    char *value, char * command, TkTextIndex *index,
  			    int what));
+ static int              TextEditUndo _ANSI_ARGS_((Tcl_Interp * interp,
+                             TkText *textPtr));
+ static int              TextEditRedo _ANSI_ARGS_((Tcl_Interp * interp,
+                             TkText *textPtr));
+ static char *           TextGetText _ANSI_ARGS_((TkTextIndex * index1,
+                             TkTextIndex * index2));
+ static void             pushStack _ANSI_ARGS_(( TkTextEditAtom ** stack, 
+                             TkTextEditAtom * elem ));
+ 
+ static TkTextEditAtom * popStack   _ANSI_ARGS_(( TkTextEditAtom ** stack ));
+ 
+ static void             clearStack _ANSI_ARGS_(( TkTextEditAtom ** stack ));
+ 
+ static void             insertSeparator _ANSI_ARGS_(( TkTextEditAtom ** stack ));
+ 
+ static void             updateDirtyFlag _ANSI_ARGS_((TkText *textPtr));
+ 
+ static void             setDirtyFlag  _ANSI_ARGS_((TkText *textPtr));
+ 
+ static void             resetDirtyFlag  _ANSI_ARGS_((TkText *textPtr));
  
  /*
   * The structure below defines text class behavior by means of procedures
***************
*** 426,431 ****
--- 453,465 ----
      textPtr->xScrollCmd = NULL;
      textPtr->yScrollCmd = NULL;
      textPtr->flags = 0;
+     textPtr->undo = 1;
+     textPtr->modifiedSet = 0;
+     textPtr->isDirty = 0;
+     textPtr->isDirtyIncrement = 1;
+     textPtr->undoStack = NULL;
+     textPtr->redoStack = NULL;
+     textPtr->autoSeparators = 1;
  
      /*
       * Create the "sel" tag and the "current" and "insert" marks.
***************
*** 489,494 ****
--- 523,529 ----
      size_t length;
      int c;
      TkTextIndex index1, index2;
+     char * string;
  
      if (argc < 2) {
  	Tcl_AppendResult(interp, "wrong # args: should be \"",
***************
*** 636,641 ****
--- 671,678 ----
  	    sprintf(buf, "%d %d %d %d %d", x, y, width, height, base);
  	    Tcl_SetResult(interp, buf, TCL_VOLATILE);
  	}
+     } else if ((c == 'e') && (strncmp(argv[1], "edit", length) == 0)) {
+         result = TextEditCmd(textPtr, interp, argc, argv);
      } else if ((c == 'g') && (strncmp(argv[1], "get", length) == 0)) {
  	if ((argc != 3) && (argc != 4)) {
  	    Tcl_AppendResult(interp, "wrong # args: should be \"",
***************
*** 658,689 ****
  	if (TkTextIndexCmp(&index1, &index2) >= 0) {
  	    goto done;
  	}
! 	while (1) {
! 	    int offset, last, savedChar;
! 	    TkTextSegment *segPtr;
! 
! 	    segPtr = TkTextIndexToSeg(&index1, &offset);
! 	    last = segPtr->size;
! 	    if (index1.linePtr == index2.linePtr) {
! 		int last2;
! 
! 		if (index2.byteIndex == index1.byteIndex) {
! 		    break;
! 		}
! 		last2 = index2.byteIndex - index1.byteIndex + offset;
! 		if (last2 < last) {
! 		    last = last2;
! 		}
! 	    }
! 	    if (segPtr->typePtr == &tkTextCharType) {
! 		savedChar = segPtr->body.chars[last];
! 		segPtr->body.chars[last] = 0;
! 		Tcl_AppendResult(interp, segPtr->body.chars + offset,
! 			(char *) NULL);
! 		segPtr->body.chars[last] = savedChar;
! 	    }
! 	    TkTextIndexForwBytes(&index1, last-offset, &index1);
! 	}
      } else if ((c == 'i') && (strncmp(argv[1], "index", length) == 0)
  	    && (length >= 3)) {
  	char buf[200];
--- 695,704 ----
  	if (TkTextIndexCmp(&index1, &index2) >= 0) {
  	    goto done;
  	}
!         string = TextGetText(&index1,&index2);
!         Tcl_AppendResult(interp, string, (char *) NULL);
!         ckfree(string);
!         
      } else if ((c == 'i') && (strncmp(argv[1], "index", length) == 0)
  	    && (length >= 3)) {
  	char buf[200];
***************
*** 771,778 ****
      } else {
  	Tcl_AppendResult(interp, "bad option \"", argv[1],
  		"\": must be bbox, cget, compare, configure, debug, delete, ",
! 		"dlineinfo, dump, get, image, index, insert, mark, scan, ",
! 		"search, see, tag, window, xview, or yview",
  		(char *) NULL);
  	result = TCL_ERROR;
      }
--- 786,793 ----
      } else {
  	Tcl_AppendResult(interp, "bad option \"", argv[1],
  		"\": must be bbox, cget, compare, configure, debug, delete, ",
!                 "dlineinfo, dump, edit, get, image, index, insert, mark, ",
!                 "scan, search, see, tag, window, xview, or yview",
  		(char *) NULL);
  	result = TCL_ERROR;
      }
***************
*** 1209,1214 ****
--- 1224,1232 ----
  {
      int lineIndex, resetView, offset;
      TkTextIndex newTop;
+     TkTextEditAtom * insertion;
+     char indexBuffer[TK_POS_CHARS];
+     
  
      /*
       * Don't allow insertions on the last (dummy) line of the text.
***************
*** 1237,1242 ****
--- 1255,1286 ----
      }
      TkTextChanged(textPtr, indexPtr, indexPtr);
      TkBTreeInsertChars(indexPtr, string);
+ 
+     /*
+      * Push the insertion on the undo stack
+      */
+ 
+     if ( textPtr->undo ) {
+         if (textPtr->autoSeparators && textPtr->undoStack &&
+             textPtr->undoStack->type != INSERT) {
+             insertSeparator(&(textPtr->undoStack));
+         }
+         
+         insertion = (TkTextEditAtom *) ckalloc(sizeof(TkTextEditAtom));
+         insertion->type = INSERT;
+         
+         TkTextPrintIndex(indexPtr,indexBuffer);
+         insertion->index = (char *) ckalloc(strlen(indexBuffer) + 1);
+         strcpy(insertion->index,indexBuffer);
+         
+         insertion->string = (char *) ckalloc(strlen(string) + 1);
+         strcpy(insertion->string,string);
+ 
+         pushStack(&(textPtr->undoStack),insertion);
+         clearStack(&(textPtr->redoStack));
+     }
+     updateDirtyFlag(textPtr);
+ 
      if (resetView) {
  	TkTextMakeByteIndex(textPtr->tree, lineIndex, 0, &newTop);
  	TkTextIndexForwBytes(&newTop, offset, &newTop);
***************
*** 1280,1285 ****
--- 1324,1331 ----
  {
      int line1, line2, line, byteIndex, resetView;
      TkTextIndex index1, index2;
+     TkTextEditAtom * deletion;
+     char indexBuffer[TK_POS_CHARS];
  
      /*
       * Parse the starting and stopping indices.
***************
*** 1391,1396 ****
--- 1437,1467 ----
  	    byteIndex -= (index2.byteIndex - index1.byteIndex);
  	}
      }
+     
+     
+     /*
+      * Push the deletion on the undo stack
+      */
+ 
+     if ( textPtr->undo ) {
+         if (textPtr->autoSeparators && textPtr->undoStack && textPtr->undoStack->type != DELETE) {
+            insertSeparator(&(textPtr->undoStack));
+         }
+         
+         deletion = (TkTextEditAtom *) ckalloc(sizeof(TkTextEditAtom));
+         deletion->type = DELETE;
+         
+         TkTextPrintIndex(&index1,indexBuffer);
+         deletion->index = (char *) ckalloc(strlen(indexBuffer) + 1);
+         strcpy(deletion->index,indexBuffer);
+         
+         deletion->string = TextGetText(&index1, &index2);
+ 
+         pushStack(&(textPtr->undoStack),deletion);
+         clearStack(&(textPtr->redoStack));
+     }
+     updateDirtyFlag(textPtr);
+ 
      TkBTreeDeleteChars(&index1, &index2);
      if (resetView) {
  	TkTextMakeByteIndex(textPtr->tree, line, byteIndex, &index1);
***************
*** 1572,1577 ****
--- 1643,1649 ----
      register TkText *textPtr = (TkText *) clientData;
  #ifdef ALWAYS_SHOW_SELECTION
      TkTextIndex start, end;
+     char selMessage[1000];
  
      if (!textPtr->exportSelection) {
  	return;
***************
*** 1588,1593 ****
--- 1660,1668 ----
      TkTextRedrawTag(textPtr, &start, &end, textPtr->selTagPtr, 1);
      TkBTreeTag(&start, &end, textPtr->selTagPtr, 0);
  #endif
+     /* Send an event that the selection changed */
+     sprintf(selMessage,"event generate %s <<Selection>>",Tk_PathName(textPtr->tkwin));
+     Tcl_Eval(textPtr->interp,selMessage);
      textPtr->flags &= ~GOT_SELECTION;
  }
  
***************
*** 2421,2423 ****
--- 2496,2990 ----
      }
  }
  
+ 
+ /*
+  * pushStack
+  *    Push elem on the stack identified by stack.
+  *
+  * Results:
+  *    None
+  *
+  * Side effects:
+  *    None.
+  */
+  
+ static void pushStack ( stack, elem )
+     TkTextEditAtom ** stack;
+     TkTextEditAtom *  elem;
+ { 
+     elem->next = *stack;
+     *stack = elem;
+ }
+ 
+ 
+ /*
+  * popStack --
+  *    Remove and return the top element from the stack identified by 
+  *      stack.
+  *
+  * Results:
+  *    None
+  *
+  * Side effects:
+  *    None.
+  */
+  
+ TkTextEditAtom * popStack ( stack )
+     TkTextEditAtom ** stack ;
+ { 
+     TkTextEditAtom * elem = NULL;
+     if (*stack != NULL ) {
+         elem   = *stack;
+         *stack = elem->next;
+     }
+     return elem;
+ }
+ 
+ 
+ /*
+  * insertSeparator --
+  *    insert a separator on the stack, indicating a border for
+  *      an undo/redo chunk.
+  *
+  * Results:
+  *    None
+  *
+  * Side effects:
+  *    None.
+  */
+  
+ static void insertSeparator ( stack )
+     TkTextEditAtom ** stack;
+ {
+     TkTextEditAtom * separator;
+ 
+     if ( *stack != NULL && (*stack)->type != SEPARATOR ) {
+         separator = (TkTextEditAtom *) ckalloc(sizeof(TkTextEditAtom));
+         separator->type = SEPARATOR;
+         pushStack(stack,separator);
+     }
+ }
+ 
+ 
+ /*
+  * clearStack --
+  *    Clear an entire undo or redo stack and destroy all elements in it.
+  *
+  * Results:
+  *    None
+  *
+  * Side effects:
+  *    None.
+  */
+  
+ static void clearStack ( stack )
+     TkTextEditAtom ** stack;      /* An Undo or Redo stack */
+ {
+     TkTextEditAtom * elem;
+ 
+     while ( (elem = popStack(stack)) ) {
+         if ( elem->type != SEPARATOR ) {
+             ckfree(elem->index);
+             ckfree(elem->string);
+         }
+         ckfree((char *)elem);
+     }
+     *stack = NULL;
+ }
+ 
+ 
+ /*
+  * TextEditUndo --
+  *    undo the last change.
+  *
+  * Results:
+  *    None
+  *
+  * Side effects:
+  *    None.
+  */
+  
+ static int TextEditUndo (interp,textPtr)
+     Tcl_Interp * interp;
+     TkText     * textPtr;             /* Overall information about text widget. */
+ {
+     TkTextEditAtom * elem      ;
+     TkTextIndex      fromIndex ;
+     TkTextIndex      toIndex   ;
+     char             buffer[TK_POS_CHARS];
+     char             viewIndex[TK_POS_CHARS];
+     
+     if ( ! textPtr->undo ) {
+        return TCL_OK;
+     }
+     
+ 
+     /* Turn off the undo feature */
+     
+     textPtr->undo = 0;
+     
+     /* insert a separator on the redo stack */
+     
+     insertSeparator(&(textPtr->redoStack));
+     
+     /* Pop and skip the first separator if there is one*/
+     
+     elem = popStack(&(textPtr->undoStack));
+ 
+     if ( elem == NULL ) {
+         textPtr->undo = 1;
+         return TCL_ERROR;
+     }
+     
+     if ( ( elem != NULL ) && ( elem->type == SEPARATOR ) ) {
+         ckfree((char *) elem);
+         elem = popStack(&(textPtr->undoStack));
+     }
+     
+     while ( elem && (elem->type != SEPARATOR) ) {
+         switch ( elem->type ) {
+             case INSERT:
+                 TkTextGetIndex(interp,textPtr,elem->index,&toIndex);
+                 strcpy(viewIndex,elem->index);
+                 TkTextIndexForwBytes(&toIndex,(int)strlen(elem->string),&toIndex);
+                 TkTextPrintIndex(&toIndex,buffer);
+                 textPtr->isDirtyIncrement = -1;
+                 DeleteChars(textPtr,elem->index,buffer);
+                 textPtr->isDirtyIncrement = 1;
+                 break;
+             case DELETE: 
+                 TkTextGetIndex(interp,textPtr,elem->index,&fromIndex);
+                 textPtr->isDirtyIncrement = -1;
+                 InsertChars(textPtr,&fromIndex,elem->string);
+                 TkTextIndexForwBytes(&fromIndex,(int)strlen(elem->string),&toIndex);
+                 TkTextPrintIndex(&toIndex,viewIndex);
+                 textPtr->isDirtyIncrement = 1;
+                 break;
+             default:
+                 return TCL_ERROR;
+         }
+         pushStack(&(textPtr->redoStack),elem);
+         elem = popStack(&(textPtr->undoStack));
+     }
+     
+     /* view the last changed position */
+     
+     TkTextGetIndex(interp,textPtr,viewIndex,&toIndex);
+     TkTextSetMark(textPtr, "insert", &toIndex);
+ 
+     /* insert a separator on the undo stack */
+     
+     insertSeparator(&(textPtr->undoStack));
+     
+     /* Turn back on the undo feature */
+     
+     textPtr->undo = 1;
+     
+     return TCL_OK;
+ }
+ 
+ 
+ /*
+  * TextEditRedo --
+  *    redo the last undone change.
+  *
+  * Results:
+  *    None
+  *
+  * Side effects:
+  *    None.
+  */
+  
+ static int TextEditRedo (interp,textPtr)
+     Tcl_Interp * interp;
+     TkText     * textPtr;             /* Overall information about text widget. */
+ {
+     TkTextEditAtom * elem      ;
+     TkTextIndex      fromIndex ;
+     TkTextIndex      toIndex   ;
+     char             buffer[TK_POS_CHARS];
+     char             viewIndex[TK_POS_CHARS];
+     
+     if ( ! textPtr->undo ) {
+        return TCL_OK;
+     }
+     
+     /* Turn off the undo feature temporarily */
+     
+     textPtr->undo = 0;
+     
+     /* insert a separator on the undo stack */
+     
+     insertSeparator(&(textPtr->undoStack));
+     
+     /* Pop and skip the first separator if there is one*/
+     
+     elem = popStack(&(textPtr->redoStack));
+ 
+     if ( elem == NULL ) {
+        textPtr->undo = 1;
+        return TCL_ERROR;
+     }
+     
+     if ( ( elem != NULL ) && ( elem->type == SEPARATOR ) ) {
+         ckfree((char *) elem);
+         elem = popStack(&(textPtr->redoStack));
+     }
+     
+     while ( elem && (elem->type != SEPARATOR) ) {
+         switch ( elem->type ) {
+             case INSERT:
+                 TkTextGetIndex(interp,textPtr,elem->index,&fromIndex);
+                 InsertChars(textPtr,&fromIndex,elem->string);
+                 TkTextIndexForwBytes(&fromIndex,(int)strlen(elem->string),&toIndex);
+                 TkTextPrintIndex(&toIndex,viewIndex);
+                 break;
+             case DELETE: 
+                 TkTextGetIndex(interp,textPtr,elem->index,&toIndex);
+                 strcpy(viewIndex,elem->index);
+                 TkTextIndexForwBytes(&toIndex,(int)strlen(elem->string),&toIndex);
+                 TkTextPrintIndex(&toIndex,buffer);
+                 DeleteChars(textPtr,elem->index,buffer);
+                 break;
+             default:
+                 return TCL_ERROR;
+         }
+         pushStack(&(textPtr->undoStack),elem);
+         elem = popStack(&(textPtr->redoStack));
+     }
+     
+     /* view the last changed position */
+     
+     TkTextGetIndex(interp,textPtr,viewIndex,&toIndex);
+     TkTextSetMark(textPtr, "insert", &toIndex);
+ 
+     /* insert a separator on the undo stack */
+     
+     insertSeparator(&(textPtr->undoStack));
+ 
+     /* Turn back on the undo feature */
+     
+     textPtr->undo = 1;
+     
+     return TCL_OK;
+ }
+ 
+ static int
+ TextEditCmd(textPtr, interp, argc, argv)
+     TkText *textPtr;          /* Information about text widget. */
+     Tcl_Interp *interp;               /* Current interpreter. */
+     int argc;                 /* Number of arguments. */
+     char **argv;              /* Argument strings. */
+ {
+     int      c            ;
+     size_t   length       ;
+     int      setModified  ;
+     
+     if (argc < 3) {
+       Tcl_AppendResult(interp, "wrong # args: should be \"",
+               argv[0], " edit option ?arg arg ...?\"", (char *) NULL);
+       return TCL_ERROR;
+     }
+     c = argv[2][0];
+     length = strlen(argv[2]);
+     if ((c == 'm') && (strncmp(argv[2], "modified", length) == 0)) {
+       if (argc != 3) {
+ 	    if (Tcl_GetBoolean(interp, argv[3], &setModified) == TCL_OK) {
+                 if ( argc != 4 ) {
+                   Tcl_AppendResult(interp, "wrong # args: should be \"",
+                           argv[0], " edit modified ?boolean? \"", (char *) NULL);
+                   return TCL_ERROR;
+                 }
+                 if ( setModified ) {
+                     setDirtyFlag(textPtr);
+                 } else {
+                     resetDirtyFlag(textPtr);
+                 }
+             } else {
+               Tcl_AppendResult(interp, "bad modified option \"", argv[3],
+                       "\": must be a boolean",
+                       (char *) NULL);
+               return TCL_ERROR;
+             }
+       } else {
+             if (textPtr->isDirty) {
+                 Tcl_AppendResult(interp, "1",(char *) NULL);
+             } else {
+                 Tcl_AppendResult(interp, "0",(char *) NULL);
+             }
+         }
+     } else if ((c == 'r') && (strncmp(argv[2], "redo", length) == 0)  && (length >= 3)) {
+       if (argc != 3) {
+           Tcl_AppendResult(interp, "wrong # args: should be \"",
+                   argv[0], " edit redo \"", (char *) NULL);
+           return TCL_ERROR;
+       }
+         if ( TextEditRedo(interp,textPtr) ) {
+             Tcl_AppendResult(interp, "nothing to redo",
+                   (char *) NULL);
+           return TCL_ERROR;
+         }
+     } else if ((c == 'r') && (strncmp(argv[2], "reset", length) == 0) && (length >= 3)) {
+       if (argc != 3) {
+           Tcl_AppendResult(interp, "wrong # args: should be \"",
+                   argv[0], " edit reset \"", (char *) NULL);
+           return TCL_ERROR;
+       }
+         clearStack(&(textPtr->undoStack));
+         clearStack(&(textPtr->redoStack));
+     } else if ((c == 's') && (strncmp(argv[2], "separator", length) == 0)) {
+       if (argc != 3) {
+           Tcl_AppendResult(interp, "wrong # args: should be \"",
+                   argv[0], " edit separator \"", (char *) NULL);
+           return TCL_ERROR;
+       }
+         insertSeparator(&(textPtr->undoStack));
+     } else if ((c == 'u') && (strncmp(argv[2], "undo", length) == 0)) {
+       if (argc != 3) {
+           Tcl_AppendResult(interp, "wrong # args: should be \"",
+                   argv[0], " edit undo \"", (char *) NULL);
+           return TCL_ERROR;
+       }
+         if ( TextEditUndo(interp,textPtr) ) {
+             Tcl_AppendResult(interp, "nothing to undo",
+                   (char *) NULL);
+           return TCL_ERROR;
+         }
+     } else {
+       Tcl_AppendResult(interp, "bad edit option \"", argv[2],
+               "\": must be modified, redo, reset, separator or undo",
+               (char *) NULL);
+       return TCL_ERROR;
+     }
+     
+     return TCL_OK;
+ }
+ 
+ 
+ 
+ /*
+  * TextGetText --
+  *    returns the text from indexPtr1 to indexPtr2.
+  *
+  * Results:
+  *    the string between indices indexPtr1 and indexPtr2
+  *
+  * Side effects:
+  *    None.
+  */
+  
+ char * TextGetText(indexPtr1,indexPtr2)
+     TkTextIndex * indexPtr1;
+     TkTextIndex * indexPtr2;
+ {
+     TkTextIndex tmpIndex;
+     char * string;
+     string = (char *) ckalloc(1);
+     *string = '\0';
+     
+     TkTextMakeByteIndex(indexPtr1->tree,TkBTreeLineIndex(indexPtr1->linePtr),indexPtr1->byteIndex,&tmpIndex);
+ 
+     if (TkTextIndexCmp(indexPtr1, indexPtr2) >= 0) {
+       return string;
+     }
+     while (1) {
+       int offset, last, savedChar;
+       TkTextSegment *segPtr;
+ 
+       segPtr = TkTextIndexToSeg(&tmpIndex, &offset);
+       last = segPtr->size;
+       if (tmpIndex.linePtr == indexPtr2->linePtr) {
+           int last2;
+ 
+           if (indexPtr2->byteIndex == tmpIndex.byteIndex) {
+               break;
+           }
+           last2 = indexPtr2->byteIndex - tmpIndex.byteIndex + offset;
+           if (last2 < last) {
+               last = last2;
+           }
+       }
+       if (segPtr->typePtr == &tkTextCharType) {
+           savedChar = segPtr->body.chars[last];
+           segPtr->body.chars[last] = 0;
+             string = (char *) ckrealloc(string,strlen(string) + strlen(segPtr->body.chars + offset) + 1);
+             strcat(string,segPtr->body.chars + offset);
+           segPtr->body.chars[last] = savedChar;
+       }
+       TkTextIndexForwBytes(&tmpIndex, last-offset, &tmpIndex);
+     }
+ 
+     return string;
+ }
+ 
+ 
+ /*
+  * updateDirtyFlag --
+  *    increases the dirtyness of the text widget
+  *
+  * Results:
+  *    None
+  *
+  * Side effects:
+  *    None.
+  */
+  
+ static void updateDirtyFlag (textPtr)
+     TkText *textPtr;          /* Information about text widget. */
+ {
+     char eventMessage[1000];
+     int oldDirtyFlag;
+ 
+     if ( textPtr->modifiedSet ) {
+         return;
+     }
+     oldDirtyFlag = textPtr->isDirty;
+     textPtr->isDirty += textPtr->isDirtyIncrement;
+     if (textPtr->isDirty == 0 || oldDirtyFlag == 0) {
+         sprintf(eventMessage,"event generate %s <<Modified>>",Tk_PathName(textPtr->tkwin));
+         Tcl_Eval(textPtr->interp,eventMessage);
+     }
+ }
+ 
+ /*
+  * setDirtyFlag --
+  *    sets the dirtyness of the text widget
+  *
+  * Results:
+  *    None
+  *
+  * Side effects:
+  *    None.
+  */
+  
+ static void setDirtyFlag (textPtr)
+     TkText *textPtr;          /* Information about text widget. */
+ {
+     char eventMessage[1000];
+     textPtr->isDirty = 1;
+     textPtr->modifiedSet = 1;
+     sprintf(eventMessage,"event generate %s <<Modified>>",Tk_PathName(textPtr->tkwin));
+     Tcl_Eval(textPtr->interp,eventMessage);
+ }
+   
+ /*
+  * resetDirtyFlag --
+  *    resets the dirtyness of the text widget
+  *
+  * Results:
+  *    None
+  *
+  * Side effects:
+  *    None.
+  */
+  
+ static void resetDirtyFlag (textPtr)
+     TkText *textPtr;          /* Information about text widget. */
+ {
+     char eventMessage[1000];
+     textPtr->isDirty = 0;
+     textPtr->modifiedSet = 0;
+     sprintf(eventMessage,"event generate %s <<Modified>>",Tk_PathName(textPtr->tkwin));
+     Tcl_Eval(textPtr->interp,eventMessage);
+ }
+   
diff -c -r orig_2/tk8.4a2/generic/tkText.h try/tk8.4a2/generic/tkText.h
*** orig_2/tk8.4a2/generic/tkText.h	Thu Jan  6 03:18:58 2000
--- try/tk8.4a2/generic/tkText.h	Sat Jul  7 19:35:34 2001
***************
*** 451,456 ****
--- 451,473 ----
  					 * BE THE LAST IN THE STRUCTURE. */
  } TkTextTabArray;
  
+ /* enum definining the types used in an edit stack */
+ 
+ typedef enum {
+     SEPARATOR,                          /* Marker */
+     INSERT,                             /* The undo is an insert */
+     DELETE                              /* The undo is a delete */
+ } TkTextEditType;
+ 
+ /* strcut defining the basic undo/redo stack element */
+ 
+ typedef struct TkTextEditAtom {
+     TkTextEditType type;                /* The type that will trigger the required action*/
+     char * index;                       /* The starting index of the range */
+     char * string;                      /* The text to be inserted or deleted */
+     struct TkTextEditAtom * next;       /* Pointer to the next element in the stack */
+ } TkTextEditAtom;
+ 
  /*
   * A data structure of the following type is kept for each text widget that
   * currently exists for this process:
***************
*** 625,630 ****
--- 642,675 ----
  				 * vertical scrollbar when view changes. */
      int flags;			/* Miscellaneous flags;  see below for
  				 * definitions. */
+ 
+     /*
+      * Information related to the undo/redo functonality
+      */
+      
+     TkTextEditAtom * undoStack; /* The undo stack */
+     
+     TkTextEditAtom * redoStack; /* The redo stack */
+     
+     int undo;                   /* non zero means the undo/redo behaviour is 
+                                  * enabled */
+     
+     int autoSeparators;         /* non zero means the separatorss will be 
+                                  * inserted automatically */
+     
+     int modifiedSet;            /* Flag indicating that the 'dirtynesss' of
+                                  * the text widget has been expplicitly set.
+                                  */
+ 
+     int isDirty;                /* Flag indicating the 'dirtynesss' of the text
+                                  * widget. If the flag is not zero, unsaved 
+                                  * modifications have been applied to the
+                                  * text widget */
+ 
+     int isDirtyIncrement;       /* Amount with which the isDirty flag is
+                                  * incremented every edit action
+                                  */
+ 
  } TkText;
  
  /*
diff -c -r orig_2/tk8.4a2/generic/tkTextTag.c try/tk8.4a2/generic/tkTextTag.c
*** orig_2/tk8.4a2/generic/tkTextTag.c	Thu Jan  6 03:18:59 2000
--- try/tk8.4a2/generic/tkTextTag.c	Sat Feb 17 11:27:04 2001
***************
*** 114,119 ****
--- 114,120 ----
      char *fullOption;
      register TkTextTag *tagPtr;
      TkTextIndex first, last, index1, index2;
+     char selMessage[1000];
  
      if (argc < 3) {
  	Tcl_AppendResult(interp, "wrong # args: should be \"",
***************
*** 171,176 ****
--- 172,180 ----
  	     */
      
  	    if (tagPtr == textPtr->selTagPtr) {
+                 /* Send an event that the selection changed */
+                 sprintf(selMessage,"event generate %s <<Selection>>",Tk_PathName(textPtr->tkwin));
+                 Tcl_Eval(textPtr->interp,selMessage);
  		if (addTag && textPtr->exportSelection
  			&& !(textPtr->flags & GOT_SELECTION)) {
  		    Tk_OwnSelection(textPtr->tkwin, XA_PRIMARY,
***************
*** 462,467 ****
--- 466,478 ----
  	    TkTextMakeByteIndex(textPtr->tree, TkBTreeNumLines(textPtr->tree),
  		    0, &last),
  	    TkBTreeTag(&first, &last, tagPtr, 0);
+ 
+             if (tagPtr == textPtr->selTagPtr) {
+                 /* Send an event that the selection changed */
+                 sprintf(selMessage,"event generate %s <<Selection>>",Tk_PathName(textPtr->tkwin));
+                 Tcl_Eval(textPtr->interp,selMessage);
+             }
+ 
  	    Tcl_DeleteHashEntry(hPtr);
  	    if (textPtr->bindingTable != NULL) {
  		Tk_DeleteAllBindings(textPtr->bindingTable,
diff -c -r orig_2/tk8.4a2/library/text.tcl try/tk8.4a2/library/text.tcl
*** orig_2/tk8.4a2/library/text.tcl	Thu Jul 20 01:22:20 2000
--- try/tk8.4a2/library/text.tcl	Sun Jul  8 07:26:00 2001
***************
*** 204,209 ****
--- 204,210 ----
  }
  bind Text <Return> {
      tkTextInsert %W \n
+     if {[%W cget -autoseparators]} {%W edit separator}
  }
  bind Text <Delete> {
      if {[string compare [%W tag nextrange sel 1.0 end] ""]} {
***************
*** 338,343 ****
--- 339,356 ----
      }
  }
  
+ bind Text <<Undo>> {
+     if { ! [ catch { %W edit undo } ] } {
+        %W see insert
+     }
+ }
+ 
+ bind Text <<Redo>> {
+     if { ! [ catch { %W edit redo } ] } {
+        %W see insert
+     }
+ }
+ 
  if {[string compare $tcl_platform(platform) "windows"]} {
  bind Text <Control-v> {
      if {!$tk_strictMotif} {
***************
*** 518,523 ****
--- 531,537 ----
      $w mark set insert [tkTextClosestGap $w $x $y]
      $w mark set anchor insert
      if {[string equal [$w cget -state] "normal"]} {focus $w}
+     if {[$w cget -autoseparators]} {$w edit separator}
  }
  
  # tkTextSelectTo --
***************
*** 633,639 ****
  
  proc tkTextPaste {w x y} {
      $w mark set insert [tkTextClosestGap $w $x $y]
!     catch {$w insert insert [selection get -displayof $w]}
      if {[string equal [$w cget -state] "normal"]} {focus $w}
  }
  
--- 647,664 ----
  
  proc tkTextPaste {w x y} {
      $w mark set insert [tkTextClosestGap $w $x $y]
!     catch {
!         set oldSeparator [$w cget -autoseparators]
!         if {$oldSeparator} {
!             $w configure -autoseparators 0
!             $w edit separator
!         }
!         $w insert insert [selection get -displayof $w]
!         if {$oldSeparator} {
!            $w edit separator
!            $w configure -autoseparators 1
!         }
!     }
      if {[string equal [$w cget -state] "normal"]} {focus $w}
  }
  
***************
*** 685,690 ****
--- 710,716 ----
      $w mark set insert $pos
      $w tag remove sel 1.0 end
      $w see insert
+     if {[$w cget -autoseparators]} {$w edit separator}
  }
  
  # tkTextKeySelect
***************
*** 794,807 ****
--- 820,844 ----
      if {[string equal $s ""] || [string equal [$w cget -state] "disabled"]} {
  	return
      }
+     set compound 0
      catch {
  	if {[$w compare sel.first <= insert] \
  		&& [$w compare sel.last >= insert]} {
+             set oldSeparator [$w cget -autoseparators]
+             if { $oldSeparator } {
+                 $w configure -autoseparators 0
+                 $w edit separator
+                 set compound 1
+             }
  	    $w delete sel.first sel.last
  	}
      }
      $w insert insert $s
      $w see insert
+     if { $compound && $oldSeparator } {
+         $w edit separator
+         $w configure -autoseparators 1
+     }
  }
  
  # tkTextUpDownLine --
***************
*** 975,986 ****
--- 1012,1032 ----
  proc tk_textPaste w {
      global tcl_platform
      catch {
+         set oldSeparator [$w cget -autoseparators]
+         if { $oldSeparator } {
+             $w configure -autoseparators 0
+             $w edit separator
+         }
  	if {[string compare $tcl_platform(platform) "unix"]} {
  	    catch {
  		$w delete sel.first sel.last
  	    }
  	}
  	$w insert insert [selection get -displayof $w -selection CLIPBOARD]
+         if { $oldSeparator } {
+             $w edit separator
+             $w configure -autoseparators 1
+         }
      }
  }
  
diff -c -r orig_2/tk8.4a2/library/tk.tcl try/tk8.4a2/library/tk.tcl
*** orig_2/tk8.4a2/library/tk.tcl	Tue Oct 31 02:12:38 2000
--- try/tk8.4a2/library/tk.tcl	Sat Jul  7 19:50:09 2001
***************
*** 281,286 ****
--- 281,288 ----
  	event add <<Copy>> <Control-Key-c> <Key-F16>
  	event add <<Paste>> <Control-Key-v> <Key-F18>
  	event add <<PasteSelection>> <ButtonRelease-2>
+ 	event add <<Undo>> <Control-Key-z>
+ 	event add <<Redo>> <Control-Key-Z>
  	# Some OS's define a goofy (as in, not <Shift-Tab>) keysym
  	# that is returned when the user presses <Shift-Tab>.  In order for
  	# tab traversal to work, we have to add these keysyms to the 
***************
*** 302,307 ****
--- 304,311 ----
  	event add <<Copy>> <Control-Key-c> <Control-Key-Insert>
  	event add <<Paste>> <Control-Key-v> <Shift-Key-Insert>
  	event add <<PasteSelection>> <ButtonRelease-2>
+   	event add <<Undo>> <Control-Key-z>
+ 	event add <<Redo>> <Control-Key-y>
      }
      "macintosh" {
  	event add <<Cut>> <Control-Key-x> <Key-F2> 
***************
*** 309,314 ****
--- 313,320 ----
  	event add <<Paste>> <Control-Key-v> <Key-F4>
  	event add <<PasteSelection>> <ButtonRelease-2>
  	event add <<Clear>> <Clear>
+ 	event add <<Undo>> <Control-Key-z>
+ 	event add <<Redo>> <Control-Key-Z>
      }
  }
  
diff -c -r orig_2/tk8.4a2/mac/tkMacDefault.h try/tk8.4a2/mac/tkMacDefault.h
*** orig_2/tk8.4a2/mac/tkMacDefault.h	Fri Jul 28 18:34:55 2000
--- try/tk8.4a2/mac/tkMacDefault.h	Sat Jul  7 19:46:34 2001
***************
*** 419,424 ****
--- 419,425 ----
   * Defaults for texts:
   */
  
+ #define DEF_TEXT_AUTO_SEPARATORS	"1"
  #define DEF_TEXT_BG_COLOR		NORMAL_BG
  #define DEF_TEXT_BG_MONO		WHITE
  #define DEF_TEXT_BORDER_WIDTH		"0"
***************
*** 453,458 ****
--- 454,460 ----
  #define DEF_TEXT_STATE			"normal"
  #define DEF_TEXT_TABS			""
  #define DEF_TEXT_TAKE_FOCUS		(char *) NULL
+ #define DEF_TEXT_UNDO    		"0"
  #define DEF_TEXT_WIDTH			"80"
  #define DEF_TEXT_WRAP			"char"
  #define DEF_TEXT_XSCROLL_COMMAND	""
diff -c -r orig_2/tk8.4a2/tests/text.test try/tk8.4a2/tests/text.test
*** orig_2/tk8.4a2/tests/text.test	Tue Jul 25 02:05:40 2000
--- try/tk8.4a2/tests/text.test	Sat Jul  7 20:00:20 2001
***************
*** 51,56 ****
--- 51,57 ----
  text .t2
  set i 0
  foreach test {
+     {-autoseparators yes 1 nah}
      {-background #ff00ff #ff00ff <gorp>}
      {-bd 4 4 foo}
      {-bg blue blue #xx}
***************
*** 83,88 ****
--- 84,90 ----
      {-spacing3 -10 0 bogus}
      {-state d disabled foo}
      {-tabs {1i 2i 3i 4i} {1i 2i 3i 4i} bad_tabs}
+     {-undo 1 1 eh}
      {-width 73 73 2.4}
      {-wrap w word bad_wrap}
  } {
***************
*** 111,117 ****
  	lappend result [lindex $i 4]
      }
      set result
! } {blue {} {} 7 watch 0 {} fixed #012 5 #123 #234 0 green 45 100 47 2 3 82 raised #ffff01234567 21 yellow 0 0 0 0 disabled {1i 2i 3i 4i} {any old thing} 73 word {x scroll command} {test command}}
  
  test text-2.1 {Tk_TextCmd procedure} {
      list [catch {text} msg] $msg
--- 113,119 ----
  	lappend result [lindex $i 4]
      }
      set result
! } {1 blue {} {} 7 watch 0 {} fixed #012 5 #123 #234 0 green 45 100 47 2 3 82 raised #ffff01234567 21 yellow 0 0 0 0 disabled {1i 2i 3i 4i} {any old thing} 1 73 word {x scroll command} {test command}}
  
  test text-2.1 {Tk_TextCmd procedure} {
      list [catch {text} msg] $msg
***************
*** 150,156 ****
  } {1 {wrong # args: should be ".t option ?arg arg ...?"}}
  test text-3.2 {TextWidgetCmd procedure} {
      list [catch {.t gorp 1.0 z 1.2} msg] $msg
! } {1 {bad option "gorp": must be bbox, cget, compare, configure, debug, delete, dlineinfo, dump, get, image, index, insert, mark, scan, search, see, tag, window, xview, or yview}}
  
  test text-4.1 {TextWidgetCmd procedure, "bbox" option} {
      list [catch {.t bbox} msg] $msg
--- 152,158 ----
  } {1 {wrong # args: should be ".t option ?arg arg ...?"}}
  test text-3.2 {TextWidgetCmd procedure} {
      list [catch {.t gorp 1.0 z 1.2} msg] $msg
! } {1 {bad option "gorp": must be bbox, cget, compare, configure, debug, delete, dlineinfo, dump, edit, get, image, index, insert, mark, scan, search, see, tag, window, xview, or yview}}
  
  test text-4.1 {TextWidgetCmd procedure, "bbox" option} {
      list [catch {.t bbox} msg] $msg
***************
*** 218,224 ****
  } {1 {bad comparison operator "z": must be <, <=, ==, >=, >, or !=}}
  test text-6.14 {TextWidgetCmd procedure, "compare" option} {
      list [catch {.t co 1.0 z 1.2} msg] $msg
! } {1 {bad option "co": must be bbox, cget, compare, configure, debug, delete, dlineinfo, dump, get, image, index, insert, mark, scan, search, see, tag, window, xview, or yview}}
  
  # "configure" option is already covered above
  
--- 220,226 ----
  } {1 {bad comparison operator "z": must be <, <=, ==, >=, >, or !=}}
  test text-6.14 {TextWidgetCmd procedure, "compare" option} {
      list [catch {.t co 1.0 z 1.2} msg] $msg
! } {1 {bad option "co": must be bbox, cget, compare, configure, debug, delete, dlineinfo, dump, edit, get, image, index, insert, mark, scan, search, see, tag, window, xview, or yview}}
  
  # "configure" option is already covered above
  
***************
*** 227,233 ****
  } {1 {wrong # args: should be ".t debug boolean"}}
  test text-7.2 {TextWidgetCmd procedure, "debug" option} {
      list [catch {.t de 0 1} msg] $msg
! } {1 {bad option "de": must be bbox, cget, compare, configure, debug, delete, dlineinfo, dump, get, image, index, insert, mark, scan, search, see, tag, window, xview, or yview}}
  test text-7.3 {TextWidgetCmd procedure, "debug" option} {
      .t debug true
      .t deb
--- 229,235 ----
  } {1 {wrong # args: should be ".t debug boolean"}}
  test text-7.2 {TextWidgetCmd procedure, "debug" option} {
      list [catch {.t de 0 1} msg] $msg
! } {1 {bad option "de": must be bbox, cget, compare, configure, debug, delete, dlineinfo, dump, edit, get, image, index, insert, mark, scan, search, see, tag, window, xview, or yview}}
  test text-7.3 {TextWidgetCmd procedure, "debug" option} {
      .t debug true
      .t deb
***************
*** 310,316 ****
  } {1 {wrong # args: should be ".t index index"}}
  test text-10.3 {TextWidgetCmd procedure, "index" option} {
      list [catch {.t in a b} msg] $msg
! } {1 {bad option "in": must be bbox, cget, compare, configure, debug, delete, dlineinfo, dump, get, image, index, insert, mark, scan, search, see, tag, window, xview, or yview}}
  test text-10.4 {TextWidgetCmd procedure, "index" option} {
      list [catch {.t index @xyz} msg] $msg
  } {1 {bad text index "@xyz"}}
--- 312,318 ----
  } {1 {wrong # args: should be ".t index index"}}
  test text-10.3 {TextWidgetCmd procedure, "index" option} {
      list [catch {.t in a b} msg] $msg
! } {1 {bad option "in": must be bbox, cget, compare, configure, debug, delete, dlineinfo, dump, edit, get, image, index, insert, mark, scan, search, see, tag, window, xview, or yview}}
  test text-10.4 {TextWidgetCmd procedure, "index" option} {
      list [catch {.t index @xyz} msg] $msg
  } {1 {bad text index "@xyz"}}
***************
*** 369,375 ****
      list [.t get 1.0 1.end] [.t tag ranges bold] [.t tag ranges silly]
  } {{First second} {1.0 1.5} {1.5 1.12}}
  
! # Mark, scan, search, see, tag, window, xview, and yview actions are tested elsewhere.
  
  test text-12.1 {ConfigureText procedure} {
      list [catch {.t2 configure -state foobar} msg] $msg
--- 371,377 ----
      list [.t get 1.0 1.end] [.t tag ranges bold] [.t tag ranges silly]
  } {{First second} {1.0 1.5} {1.5 1.12}}
  
! # Edit, mark, scan, search, see, tag, window, xview, and yview actions are tested elsewhere.
  
  test text-12.1 {ConfigureText procedure} {
      list [catch {.t2 configure -state foobar} msg] $msg
***************
*** 1365,1370 ****
--- 1367,1485 ----
      tkTextSetCursor .t 3.0
      .t search -backward -regexp "\$" insert 1.0
  } {2.6}
+ 
+ test text-25.1 {TextEditCmd procedure, argument parsing} {
+     list [catch {.t edit} msg] $msg
+ } {1 {wrong # args: should be ".t edit option ?arg arg ...?"}}
+ 
+ test text-25.2 {TextEditCmd procedure, argument parsing} {
+     list [catch {.t edit gorp} msg] $msg
+ } {1 {bad edit option "gorp": must be modified, redo, reset, separator or undo}}
+ 
+ test text-25.3 {TextEditUndo procedure, undoing changes} {
+     catch {destroy .t}
+     text .t -undo 1
+     pack .t
+     .t insert end "line 1\n"
+     .t delete 1.4 1.6
+     .t insert end "should be gone after undo\n"
+     .t edit undo
+     .t get 1.0 end
+ } "line\n\n"
+ 
+ test text-25.4 {TextEditRedo procedure, redoing changes} {
+     catch {destroy .t}
+     text .t -undo 1
+     pack .t
+     .t insert end "line 1\n"
+     .t delete 1.4 1.6
+     .t insert end "should be back after redo\n"
+     .t edit undo
+     .t edit redo
+     .t get 1.0 end
+ } "line\nshould be back after redo\n\n"
+ 
+ test text-25.5 {TextEditUndo procedure, resetting stack} {
+     catch {destroy .t}
+     text .t -undo 1
+     pack .t
+     .t insert end "line 1\n"
+     .t delete 1.4 1.6
+     .t insert end "should be back after redo\n"
+     .t edit reset
+     catch {.t edit undo} msg
+     set msg
+ } "nothing to undo"
+ 
+ test text-25.6 {TextEditCmd procedure, insert separator} {
+     catch {destroy .t}
+     text .t -undo 1
+     pack .t
+     .t insert end "line 1\n"
+     .t edit separator
+     .t insert end "line 2\n"
+     .t edit undo
+     .t get 1.0 end
+ } "line 1\n\n"
+ 
+ test text-25.7 {-autoseparators configuration option} {
+     catch {destroy .t}
+     text .t -undo 1 -autoseparators 0
+     pack .t
+     .t insert end "line 1\n"
+     .t delete 1.4 1.6
+     .t insert end "line 2\n"
+     .t edit undo
+     .t get 1.0 end
+ } "\n"
+ 
+ test text-25.8 {TextEditCmd procedure, modified flag} {
+     catch {destroy .t}
+     text .t
+     pack .t
+     .t insert end "line 1\n"
+     .t edit modified
+ } {1}
+ 
+ test text-25.9 {TextEditCmd procedure, reset modified flag} {
+     catch {destroy .t}
+     text .t
+     pack .t
+     .t insert end "line 1\n"
+     .t edit modified 0
+     .t edit modified
+ } {0}
+ 
+ test text-25.10 {TextEditCmd procedure, set modified flag} {
+     catch {destroy .t}
+     text .t
+     pack .t
+     .t edit modified 1
+     .t edit modified
+ } {1}
+ 
+ test text-25.11 {<<Modified>> virtual event} {
+     set ::retval unmodified
+     catch {destroy .t}
+     text .t -undo 1
+     pack .t
+     bind .t <<Modified>> "set ::retval modified"
+     update idletasks
+     .t insert end "nothing special\n"
+     set ::retval
+ } {modified}
+ 
+ test text-25.12 {<<Selection>> virtual event} {
+     set ::retval no_selection
+     catch {destroy .t}
+     text .t -undo 1
+     pack .t
+     bind .t <<Selection>> "set ::retval selection_changed"
+     update idletasks
+     .t insert end "nothing special\n"
+     .t tag add sel 1.0 1.1
+     set ::retval
+ } {selection_changed}
  
  eval destroy [winfo child .]
  option clear
Only in try/tk8.4a2/unix: Makefile
Only in try/tk8.4a2/unix: config.cache
Only in try/tk8.4a2/unix: config.log
Only in try/tk8.4a2/unix: config.status
Only in try/tk8.4a2/unix: tkConfig.sh
diff -c -r orig_2/tk8.4a2/unix/tkUnixDefault.h try/tk8.4a2/unix/tkUnixDefault.h
*** orig_2/tk8.4a2/unix/tkUnixDefault.h	Fri Jul 28 18:34:55 2000
--- try/tk8.4a2/unix/tkUnixDefault.h	Sat Jul  7 19:46:05 2001
***************
*** 409,414 ****
--- 409,415 ----
   * Defaults for texts:
   */
  
+ #define DEF_TEXT_AUTO_SEPARATORS	"1"
  #define DEF_TEXT_BG_COLOR		NORMAL_BG
  #define DEF_TEXT_BG_MONO		WHITE
  #define DEF_TEXT_BORDER_WIDTH		"2"
***************
*** 443,448 ****
--- 444,450 ----
  #define DEF_TEXT_STATE			"normal"
  #define DEF_TEXT_TABS			""
  #define DEF_TEXT_TAKE_FOCUS		(char *) NULL
+ #define DEF_TEXT_UNDO    		"0"
  #define DEF_TEXT_WIDTH			"80"
  #define DEF_TEXT_WRAP			"char"
  #define DEF_TEXT_XSCROLL_COMMAND	""
diff -c -r orig_2/tk8.4a2/win/tkWinDefault.h try/tk8.4a2/win/tkWinDefault.h
*** orig_2/tk8.4a2/win/tkWinDefault.h	Fri Jul 28 18:34:56 2000
--- try/tk8.4a2/win/tkWinDefault.h	Sat Jul  7 19:46:57 2001
***************
*** 414,419 ****
--- 414,420 ----
   * Defaults for texts:
   */
  
+ #define DEF_TEXT_AUTO_SEPARATORS	"1"
  #define DEF_TEXT_BG_COLOR		"SystemWindow"
  #define DEF_TEXT_BG_MONO		WHITE
  #define DEF_TEXT_BORDER_WIDTH		"2"
***************
*** 448,453 ****
--- 449,455 ----
  #define DEF_TEXT_STATE			"normal"
  #define DEF_TEXT_TABS			""
  #define DEF_TEXT_TAKE_FOCUS		(char *) NULL
+ #define DEF_TEXT_UNDO    		"0"
  #define DEF_TEXT_WIDTH			"80"
  #define DEF_TEXT_WRAP			"char"
  #define DEF_TEXT_XSCROLL_COMMAND	""

TIP:            26
Title:          Enhancements for the Tk Text Widget
Version:        $Revision: 1.8 $
Author:         Ludwig Callewaert <[email protected]>
Author:         Ludwig Callewaert <[email protected]>
State:          Accepted
Type:           Project
Vote:           Done
Created:        20-Feb-2001
Post-History:   
Discussions-To: news:comp.lang.tcl
Obsoletes:      19
Tcl-Version:    8.4

~ Abstract

This TIP proposes several enhancements for the Tk text widget.  An
unlimited undo/redo mechanism is proposed, with several user available
customisation features.  Related to this, a text modified indication
is proposed.  This means that the user can set, query or receive a virtual
event when the content of the text widget is modified.  And finally a
virtual event is added that is generated whenever the selection
changes in the text widget.

~ Rationale

The text widget provides a lot of features that make it ideally suited
to create a text editor from it.  The vast number of editors that are
based on this widget are a proof of this.  Yet some basic features are
missing from the text widget and need to be re-invented over and over
again by the authors of the various editors.  This TIP adds a number
of the missing features.

A first missing feature is an undo/redo mechanism.  The mechanism
proposed here is simple yet powerful enough to accommodate a very
reasonable undo/redo strategy.  It also provides sufficient user
control, so that the actual strategy can be refined and tailored to
the users need.

A second missing feature is a notification if the text in the widget
has been modified with respect to a reference point.  [19] deals
partly with this.  This implementation takes it some steps further.
First of all, there is a link with the undo/redo mechanism, since
undoing or redoing changes can take you to or away from the reference
point, and as such changes the modified state of the widget.
Secondly, with this implementation, a virtual event is generated
whenever the modified state of the widget changes, allowing the user
to bind to that event and for instance give a visual indication of the
modified state of the widget.

Finally, a virtual event has been added that is triggered whenever the
selection in the widget changes.  At first it may seem not so useful,
but there are a number of situations where this functionality is
needed.  A couple of examples where I ran into the need for this may
clarify this.  On Windows, if the text widget does not have the focus,
the selection tag is not visible.  This is consistent with other
Windows applications.  However, when implementing a search mechanism,
the found string needs to be tagged with the selection tag.  (You want
it to be selected).  The search (and replace) dialog box has the focus
however, so this selection tag is invisible.  To make it visible,
another tag was used to duplicate the selection tag.  This is very
easy when the functionality described here is available.  Otherwise it
is very difficult to do this consistently.  Another occasion was when
I was implementing a rectangular cut and paste for the text widget.
This was based on adding spaces on the fly, while selecting the
rectangle.  If for some reason the selection changes (for instance on
Unix another application gets the selection) these spaces need to be
removed again.  Doing this is virtually impossible without this
functionality.  With it, it becomes trivial.  The functionality itself
adds little or no overhead to the text widget.

~ Specification

The undo/redo mechanism operates by adding two stacks of edit actions
to the text widget.  Every insert or delete operation is added to the
undo stack in normal operation.  At certain times a separator is added 
onto the stack.  All insert and delete actions in between two separators
are considered to be one edit action, and will be undone or redone as one.  
The insertion of the separators is under user control.  There is a 
default operation however.  This will insert separators whenever the 
mode changes from insertion to deletion, or vise versa.  Separators are
also inserted when the keyboard or the mouse are used to move the insert
mark. Finally, pressing the <Return> key also inserts a separator. 
By turning the autoseparators off and inserting them at the desired 
points, compound actions, such as search and replace, can be created.  
The default paste function is an example of such an action.

Undoing an action, will re-apply in reverse order all inserts and
deletes in between two separators.  These inserts and deletes will now
move to the redo stack.  Redoing a change re-applies the inserts and
deletes, and moves them again to the undo stack.  Normal insertions or
deletions will clear the redo stack.

It is also possible to clear the undo stack, giving the user some control
over the depth of the stack.

Currently only text inserts and deletes can be undone. All other changes
to the widget, such as the adding or deleting of tags, cannot be undone.

The modified state of the widget is implemented using a counter.
Every insert or delete action, and every time such an action is redone,
increments this counter. Every undone insert or delete decrements this 
counter.  The widget is considered to be modified if the counter is not
zero.  A virtual event ''<<Modified>>'' is generated whenever this 
counter changes from zero to non-zero or vice versa.  A mechanism is 
provided to reset the counter to zero. The modified state can also be 
explicitely set by the user. In that case, the counter mechanism is not 
operational until the modified state has been reset again.

   1.  ''pathName configure -undo 0|1'' - this enables or disables the
       undo/redo mechanism.  The default is zero.

   2.  ''pathName configure -autoseparators 0|1'' - when one inserts
       a separator automatically whenever insert changes to delete or
       vice versa. Separators are also inserted when the keyboard or
       the mouse is used to move the insert mark, or when the <Return>
       key is pressed. When off, no separators are inserted, except by
       the user (See 6).  The default is one.

   3.  ''pathName edit undo'' - undoes the last edit action if undo is
       enabled (See 1). The insert mark will be positioned at the last
       undone edit action. When undo deletes text, that is the index
       where the text was. When undo inserts text, the insert mark
       will be positioned at the end of the inserted text. The view will
       be adapted to make the insert mark visible. Raises an exception 
       if there is nothing to undo. Does nothing if undo is disabled.

   4.  ''pathName edit redo'' - redoes the last edit action if undo is
       enabled (See 1). The insert mark and widget view will be updated
       similar to what is done for the edit undo command. Raises an 
       exception if there is nothing to redo.  Does nothing if undo is 
       disabled.

   5.  ''pathName edit reset'' - resets the undo and redo stacks
       (clears them).

   6.  ''pathName edit separator'' - inserts a separator on
       the undo stack, indicating an undo boundary.  If a separator is
       already present, this will do nothing.  This means that it is
       safe to issue the command several times, without any inserts or
       deletes occurring in between.

   7.  ''pathName edit modified ?boolean?'' - If boolean is not 
       specified returns the modified state of the widget 
       (either 1 or zero).
       If boolean is specified, sets the modified state of the widget 
       to that value.

   8.  ''<<Modified>>'' - this virtual event is generated whenever the
       modified state of the widget changes from modified to not
       modified or vice versa.

   9.  ''<<Selection>>'' - this virtual event is generated whenever
       the range tagged with the selection tag changes.

  10. ''<<Undo>>'' - this virtual event calls pathName edit undo.

  11. ''<<Redo>>'' - this virtual event calls pathName edit redo.

  12.  ''<Control-z>'' - is bound to the <<Undo>> virtual event.

  13.  ''<Control-Z>'' - is bound to the <<Redo>> virtual event on all
       platforms except Win32.

  14.  ''<Control-y>'' - is bound to the <<Redo>> virtual event on Win32.

~ Example

  The following code illustrates how the new features are intended to
  be used.

|   global fileName
|   global modState
|   global undoVar
|   
|   set fileName "None"
|   set modState ""
|   set undoVar  0
|   
|   
|   text .t -background white -wrap none
|   # Example 1: The Modified event will update a text label
|   bind .t <<Modified>>  updateState
|   # Example 2: The Selection event will create a tag that
|   #            duplicates the selection
|   bind .t <<Selection>> duplicateSelection
|   
|   frame .l
|   label .l.l -text "File: "
|   label .l.f -textvariable fileName
|   label .l.m -textvariable modState
|   
|   grid .l.l -sticky w   -column 0 -row 0
|   grid .l.f -sticky w   -column 1 -row 0
|   grid .l.m -sticky e   -column 2 -row 0
|   
|   grid columnconfigure .l 1 -weight 1
|   
|   frame .b
|   button .b.l -text "Load"   -width 8 -command loadFile
|   button .b.s -text "Save"   -width 8 -command saveFile
|   button .b.i -text "Indent" -width 8 -command blockIndent
|   
|   checkbutton .b.e -text "Enable Undo" -onvalue 1 -offvalue 0 -|   |   variable undoVar
|   trace variable undoVar w setUndo
|   button .b.u -text "Undo"     -width 8 -command "undo"
|   button .b.r -text "Redo"     -width 8 -command "redo"
|   button .b.m -text "Modified" -width 8 -command ".t edit modified on"
|   
|   grid .b.l -row 0 -column 0
|   grid .b.s -row 0 -column 1
|   grid .b.i -row 0 -column 2
|   grid .b.e -row 0 -column 3
|   grid .b.u -row 0 -column 4
|   grid .b.r -row 0 -column 5
|   grid .b.m -row 0 -column 6
|   
|   grid columnconfigure .b 0 -weight 1
|   grid columnconfigure .b 1 -weight 1
|   grid columnconfigure .b 2 -weight 1
|   grid columnconfigure .b 3 -weight 1
|   grid columnconfigure .b 4 -weight 1
|   grid columnconfigure .b 5 -weight 1
|   
|   
|   grid .l -sticky ew   -column 0 -row 0
|   grid .t -sticky news -column 0 -row 1
|   grid .b -sticky ew   -column 0 -row 2
|   
|   grid rowconfigure    . 1 -weight 1
|   grid columnconfigure . 0 -weight 1
|   
|   
|   
|   proc updateState {args} {
|      global modState
|      
|      # Check the modified state and update the label
|      if { [.t edit modified] } {
|         set modState "Modified"
|      } else {
|         set modState ""
|      }
|   }
|   
|   
|   proc setUndo {args} {
|      global undoVar
|      
|      # Turn undo on or off
|      if { $undoVar } {
|         .t configure -undo 1
|      } else {
|         .t configure -undo 0
|      }
|   }
|   
|   proc undo {} {
|      # edit undo throws an exception when there is nothing to
|      # undo. So catch it.
|      if { [catch {.t edit undo}] } {
|         bell
|      }
|   }
|   
|   proc redo {} {
|      # edit redo throws an exception when there is nothing to
|      # undo. So catch it.
|      if { [catch {.t edit redo}] } {
|         bell
|      }
|   }
|   
|   proc loadFile {} {
|      
|      set file [tk_getOpenFile]
|      if { ![string equal $file ""] } {
|         set fileName $file
|         set f [open $file r]
|         set content [read $f]
|         set oldUndo [.t cget -undo]
|         
|         # Turn off undo. We do not want to be able to undo
|         # the loading of a file
|         .t configure -undo 0
|         .t delete 1.0 end
|         .t insert end $content
|         # Reset the modified state
|         .t edit modified 0
|         # Clear the undo stack
|         .t edit reset
|         # Set undo to the old state
|         .t configure -undo $oldUndo
|      }
|   }
|   
|   proc saveFile {} {
|      # The saving bit is not actually done
|      # So the contents in the file are not updated
|   
|      # Saving clears the modified state
|      .t edit modified 0
|      # Make sure there is a separator on the undo stack
|      # So we can get back to this point with the undo
|      .t edit separator
|   }
|   
|   proc blockIndent {} {
|      set indent "   "
|      
|      # Block indent should be treated as one operation from
|      # the undo point of view
|      
|      # if there is a selection
|      if { ![catch {.t index sel.first} ] } {
|         scan [.t index sel.first] "%d.%d" startline startchar
|         scan [.t index sel.last]  "%d.%d" stopline  stopchar
|         if { $stopchar == 0 } {
|            incr stopline -1
|         }
|         
|         # Get the original autoseparators state
|         set oldSep [.t cget -autoseparators]
|         # Turn of automatic insertion of separators
|         .t configure -autoseparators 0
|         # insert a separator before the edit operation
|         .t edit separator
|         for {set i $startline} { $i <= $stopline} {incr i} {
|            .t insert "$i.0" $indent
|         }
|         .t tag add sel $startline.0 "$stopline.end + 1 char"
|         # insert a separator after the edit operation
|         .t edit separator
|         # put the autoseparators back in their original state
|         .t configure -autoseparators $oldSep
|      }
|   }
|   
|   proc duplicateSelection {args} {
|      .t tag configure dupsel -background tomato
|      .t tag remove dupsel 1.0 end
|      
|      if { ![catch {.t index sel.first} ] } {
|         eval .t tag add dupsel [.t tag ranges sel]
|      }
|   }
|   

~ Reference Implementation

http://www.cs.man.ac.uk/fellowsd-bin/TIP/26.patch

''The patch has received little testing so far, so any testing is
encouraged.''

~ Copyright

This document has been placed in the public domain.

TIP:            27
Title:          CONST Qualification on Pointers in Tcl API's
Version:        $Revision: 1.5 $
Author:         Kevin Kenny <[email protected]>
State:          Accepted
Type:           Project
Vote:           Done
Created:        25-Feb-2001
Post-History:   
Discussions-To: news:comp.lang.tcl,mailto:[email protected]
Tcl-Version:    8.4

~ Abstract

Many of the C and C++ interfaces to the Tcl library lack a CONST
qualifier on the parameters that accept pointers, even though they do
not, in fact, modify the data that the pointers designate.  This lack
causes a persistent annoyance to C/C++ programmers.  Not only is the
code needed to work around this problem more verbose than required; it
also can lead to compromises in type safety.  This TIP proposes that
the C interfaces for Tcl be revised so that functions that accept
pointers to constant data have type signatures that reflect the fact.
The new interfaces will remain backward-compatible with the old,
except that a few must be changed to return pointers to CONST data.
(Changes of this magnitude, in the past, have been routine in minor
releases; the author of this TIP does not see a compelling reason to
wait for Tcl 9.0 to clean up these API's.)

~ Rationale

When the Tcl library was originally written, the ANSI C standard had
yet to be widely accepted, and the ''de facto'' standard language did
not support a ''const'' qualifier.  For this reason, none of the older
Tcl API's that accept pointers have CONST qualifiers, even when it is
known that the objects will not be modified.

In interfacing with other systems whose API's were designed after the
ANSI C standard, this limitation becomes annoying.  Code like:

| const char* const string = " ... whatever ... ";
| Tcl_SetStringObj( Tcl_GetObjResult( interp ),
|                   (char*) string, /* Have to cast away
|                                    * const-ness here
|                                    * even though the string
|                                    * will only be copied
|                                    */
|                   -1 );

is more verbose than necessary.  It is also unsafe: the cast allows a
number of unsafe type conversions (the author of this TIP has had to
debug at least one extension where an integer was cast to a character
pointer in this context).

In an C++ environment where engineering practice forbids using C-style
cast syntax, the syntax gets even more annoying, although it provides
improved safety.  C++ code analogous to the above snippet looks like:

| const char* const string = "...whatever...";
| Tcl_SetStringObj( Tcl_GetObjResult( interp ),
|                   const_cast< char* >( string ), -1 );

This code is hardly a paragon of readability.

The popular Gnu C compiler also has a problem with the ''char *''
declaration of so many of the parameters.  With the default set of
compilation options, a call like:

| Tcl_SetStringObj( Tcl_GetObjResult( interp ),
|                   "Hello world!", -1 );

results in an error; suppressing this message requires either using
the obscure option ''-fwritable-strings'' on the compiler command
line, or else applying awkward (and unsafe) cast syntax:

| Tcl_SetStringObj( Tcl_GetObjResult( interp ),
|                   const_cast< char* >( "Hello, world!" ), -1 );

Introducing CONST on parameters, however, does not bring in any
incompatibility; as long as there is a prototype in scope, any
ANSI-compliant compiler will implicitly cast non-CONST arguments to be
type-compatible with CONST formal parameters.

~ Specification

This TIP proposes that, wherever possible, Tcl API's that accept
pointers to constant data have their signatures in ''tcl.decls'' and
the corresponding source files adjusted to add the CONST qualifier.

The change introduces a potential incompatibility in that code
compiled on a (hypothetical) architecture where pointers to constant
data have a different representation from those to non-constant
data will not load against the revised stub table.  This incompatibility
is, in fact, not thought to be a problem, since no known port of
Tcl has encountered such an architecture.

If we confine the scope of this TIP to adding CONST only to
parameters, we preserve complete compatibility with existing
implementations.  It is neither possible nor desirable, however, to
preserve drop-in compatibility across all the API's.  The earliest
example in the stub table is the ''Tcl_PkgRequireEx'' function.  This
function is declared to return ''char *''; the pointer it returns,
however, is into memory managed by the Tcl library.  Any attempt by an
extension to scribble on this memory or free it will result in
corruption of Tcl's internal data structures; it is therefore safer
and more informative to return ''CONST char *''.  (This particular
example is also highly unlikely to break any existing extension; the
author of this TIP has yet to see one actually use the return value.)

Some of the API's, such as ''Tcl_GetStringFromObj'', will continue to
return pointers into writable memory inside the Tcl library.
''Tcl_GetStringFromObj'', for instance, deals with memory that is
managed co-operatively between extensions and the Tcl library; one
simply must trust extensions to do the right thing (for instance, not
overwrite the string representation of a shared object).

Some of the API's will not be modified, even though they appear to
accept constant strings.  For instance, ''Tcl_Eval'' modifies its
string argument while it is parsing it, even though it restores its
initial content when it returns.  This behavior has sufficient impact
on performance that it is probably not desirable to change it.  The
cases where the Tcl library does this sort of temporary modification,
however, must be documented in the programmers' manual.  They affect
thread safety and positioning of data in read-only memory.  One can
foresee that cleaning up the API's that do not suffer from
this problem will mean that programmers will be  less tempted
to use unsafe casts on the ones that remain.

Finally, there are a handful of API's that are essentially impossible
to clean up portably; the ones that accept variable arguments come to
mind.  These will be left alone.  One particular case in point is
''Tcl_SetResult'': its third argument determines whether its second
argument is constant or non-constant.  In an environment without
writable strings, a call like:

|    Tcl_SetResult( interp, "Hello, world!", TCL_STATIC );

or

|    Tcl_SetResult( interp, "Hello, world!", TCL_VOLATILE );

cannot be handled without unsafe casting.  Fortunately, several
alternatives are available.  The most attractive appears to be:

|    Tcl_SetObjResult( interp, 
|                      Tcl_NewStringObj( "Hello, world!", -1 ) );

which is also more informative about what is really going on.  Note
that ''TCL_STATIC'' no longer actually carries the static pointer
around.  Although ''Tcl_SetResult'' appears to do so, as soon as the
command returns, code in ''tclExecute.c'' converts the string result
into an object result by calling ''Tcl_GetObjResult''.  The code using
''Tcl_SetObjResult'' therefore carries no greater performance cost
than the original ''Tcl_SetResult''.

~ Reference Implementation

The changes described in this TIP cut across too many functional areas
to be implemented effectively all at once.  Several people have
pointed out that implementing this cleanup all at once appears to be
necessary to avoid "CONST pollution," where the library becomes full
of code that casts away the CONST qualifier.  To study this issue, the
author has conducted the experiment of imposing CONST strings on the
first API in the stubs table: ''Tcl_PkgProvideEx''.

The first concern that arose was that several other functions used the
CONST strings passed as parameters, and these functions also needed to
be updated. Fortunately, all were static within ''tclPkg.c''.  Next,
when updating the documentation, the author discovered that five other
functions were documented in the same man page, and shared a common
defintion of the ''package'' and ''version'' parameters.  They, too,
were included in the change, and once again, the change was propagated
forward into the functions that they called.  (This activity is where
the issue of replacing ''Tcl_SetResult'' with ''Tcl_SetObjResult'' was
detected.)

When replacing ''Tcl_SetResult'' with ''Tcl_SetObjResult'', the author
discovered that the ''file'' parameter to ''Tcl_DbNewStringObj'' was
also a constant string.  With more enthusiasm than caution, he decided
to attack the corresponding parameter in all the ''TCL_MEM_DEBUG''
interfaces.  (In retrospect, it would probably have been easier to
tackle this issue separately.)  This change wound up
cutting across virtually all of the external interfaces to
''tclStringObj.c'' and ''tclBinary.c'' and the associated
documentation.

The author expects that many of the other API's will be much less
closely coupled than the one studied. In particular, now that the
interfaces of ''tclStringObj.c'' have been done once, they don't need
to be done again!  In fact, starting with the interfaces, like
''tclStringObj.c'', that are used pervasively throughout the library
and working outward would certainly have been a better course of
action than tracing the dependencies forward from one function chosen
almost at random.

The result of the experimental change was that twenty-eight external
APIs, plus about a dozen static functions, needed to have the CONST
qualifier added to at least one pointer.  After these changes were
made, the test suite compiled, linked, and passed all regression tests
with all combinations of the NODEBUG and TCL_MEM_DEBUG options.  It
was nowhere necessary to cast away CONST-ness.  

Possible incompatibility with existing extensions was present
only in that the return values from the four functions,
''Tcl_PkgPresent'', ''Tcl_PkgPresentEx'', ''Tcl_PkgRequire'', and
''Tcl_PkgRequireEx'' had the CONST qualifier added.
 These four functions return pointers to memory
that must not be modified nor freed by the caller, so the CONST
qualifier is desirable, but existing extensions may depend on storing
the pointer in a variable that lacks the qualifier.
This level of incompatibility in a minor release has been
thought acceptable in the past; changes required to extensions
are trivial, and once changed, the extensions continue to back-port
cleanly to older releases.

An earlier version of these changes was uploaded to the SourceForge
patch manager as patch number 404026.  The revised version will be
added under the same patch number as soon as the author's technical
problems with uploading patches are resolved.  (The major difference
between the two patches is that the first patch implements the
two-Stub approach described under "Rejected alternatives" below.

The success of this change has convinced the author of this TIP that
the rest of the changes can be implemented in a staged manner, with
little source-level incompatibility being introduced for
extensions (and absolutely no incompatibility for stubs-enabled
extensions compiled and linked against earlier versions of the
library).

~ Rejected alternatives

The initial version of this TIP attempted to preserve backward
compatibility of stubs-enabled extensions, even on a hypothetical
architecture where pointer-to-constant and pointer-to-nonconstant
have different representations.

If this level of backward compatibility is desired,
it will be necessary to provide entries in the existing
stub table slots corresponding to the API's that lack the CONST
qualifiers.

The slots in the stub table corresponding to the non-CONST API's can
be filled with wrapper functions.  For example, the following function
definition of ''Tcl_SetStringObj_NONCONST'' will use the implicit
casting inherent in C to call the function with the new API.

|void
|Tcl_SetStringObj_NONCONST(Tcl_Obj* obj, /* Object to set */
|                          char* bytes,  /* String value to assign */
|                          int length)   /* Length of the string */
|{
|    Tcl_SetStringObj( obj, bytes, length );
|}

This sort of definition is so simple that ''tools/genStubs.tcl''
was extended in the original patch accompanying this TIP
to generate it.  For example, the declaration of
''Tcl_SetStringObj'' that once appeared as:

|declare 65 generic {
|    void Tcl_SetStringObj( Tcl_Obj* objPtr, char* bytes, int length )
|}

was replaced with:

|declare 458 -nonconst 65 generic {
|    void Tcl_SetStringObj( Tcl_Obj* objPtr, CONST char* bytes, int length )
|}

declaring that slot 458 in the stubs table is to be used for the new
API accepting a CONST char* for the string, while slot 65 remains used
for the legacy implementation.

The difficulty with this approach, which caused it to be
rejected, is that it introduces ''forward'' incompatibility.
Any extension compiled against header files from after the change
will fail to load against the stubs table from before the change.
This incompatibility would require extension authors to maintain
sets of header files for (at least) the earliest version of Tcl
that they intend to support, rather than always being able to compile
against the most current set.  This problem was thought to be worse
than the hypothetical and possibly non-existent problem of differing
pointer representations.

~ Procedural note

The intent of this TIP is that, if approved, it will empower
maintainers of individual modules to add ''CONST'' to any API
where it is appropriate, provided that:

   * the change does not introduce "CONST poisoning", that is,
     does not require type casts that remove CONST-ness;

   * the documentation of the API is updated to reflect the
     addition of the CONST qualifier; and

Individual TIP's detailing the changes to particular APIs shall
''not'' be required, provided that the changes comply with these
guidelines.

~ Change history

12 March 2001: Rejected the two-Stubs alternative and reworked
the patches to use only one Stub per modified function.

~ Copyright

This document has been placed in the public domain.

TIP:            28
Title:          How to be a good maintainer for Tcl/Tk
Version:        $Revision: 1.9 $
Author:         Don Porter <[email protected]>
Author:          <[email protected]>
State:          Draft
Type:           Informative
Vote:           Pending
Created:        23-Feb-2001
Post-History:   

~ Abstract

This document presents information and advice to maintainers in the
form of a Frequently Asked Questions (FAQ) list.

~ Preface

Notice in the header above that this is a Draft document.  It won't be
the ''official'' word of the TCT unless/until it is accepted by the
TCT.  Meanwhile, it should still be a helpful guide to those serving
or considering service as maintainers.  At the very least it's a
useful straw man to revise into something better.  Help us make it
even more useful by using the [[Edit]] link at the bottom of this page
(if any) to add/revise the questions and answers, or add your
comments.

~ Background

TCT procedures (see [0]) calls for one or more ''maintainers'' to take
responsibility for each functional area of the Tcl ([16]) or Tk ([23])
source code.  Every source code patch to Tcl or Tk will be committed
to the official branches of the appropriate CVS repository only after
approval by an appropriate set of maintainers.

~ Can I be a Tcl/Tk maintainer?

Most likely.  To be a maintainer, you should have...

 * ...an interest in Tcl/Tk.

 * ...access to the Internet (Web and e-mail).

 * ...some volunteer time to contribute.

 * ...the ability and the support software to code in C and/or Tcl,
   use CVS, use SourceForge facilities, and familiarity with a portion
   of the Tcl/Tk source code to be maintained, or the willingness to
   acquire these things.

For the most part, if you are reading this document, you probably have
what it takes to be a Tcl/Tk maintainer.

~ What can I maintain?

The Tcl Core Team (TCT) has divided up the Tcl/Tk source code into
functional areas as described in [16] and [23].  You can volunteer to
help maintain as many areas as you think you can handle.  Select those
you have experience with or an interest in.

~ What does a maintainer do?

Maintainers are the people who make changes to the files that make up
the source code distribution of Tcl or Tk -- code, documentation, and
tests.  That's what a maintainer does: check in changes to the
official source code in the area he/she maintains.

The source code can be changed for several reasons: to correct a bug,
to add a new feature, or to re-implement an existing feature in a new
way.  The reason for a change controls how much oversight the
maintainer must have while making the change.  More on this below.

~ How do I prepare to be a maintainer?

The official repositories of Tcl and Tk source code are kept at
SourceForge, so you need to register for a SourceForge account
(https://sourceforge.net/account/register.php).  As part of the
registration, you will select a login name.  When you volunteer as a
maintainer, the administrators of the Tcl or Tk projects will need
that name to give you write access to the appropriate repository.

Once you have a SourceForge account, get familiar with the tools it
provides.  Most important is that you get set up to use CVS over SSH
to access the repository.  This can be difficult.  There are some
notes on how other Developers on the Tcl and Tk projects have been
able to successfully get this done at http://tcltk.org/sourceforge

This document does not include instructions on how to use CVS.  See
the following references for assistance with learning CVS.

  http://cvsbook.red-bean.com/cvsbook.html

  >	''Add more references here please.''

~ How do I volunteer to be a maintainer?

Send a message to <[email protected]> telling the TCT
your SourceForge login name and what area(s) you want to help
maintain.  Someone will add you to the list of ''Developers'' on the
Tcl or Tk projects and enable your access to SourceForge features like
the Bug Tracker and Patch Manager.  As a Developer, you will have
write access to the appropriate repository of official source code.

~ Write access!  So I can just start changing Tcl/Tk?!

For some purposes, yes.  For others, you'll need to get approval from
the TCT first.  Read on...

~ What Internet resources does a maintainer use?

A maintainer uses the SourceForge Bug Tracker for Tcl or Tk to learn
what bugs are reported in his area (browse by Category).

   http://sourceforge.net/bugs/?group_id=10894

   http://sourceforge.net/bugs/?group_id=12997

A maintainer uses the SourceForge Patch Manager for Tcl or Tk to learn
what patches make changes in his area (browse by Category).

   http://sourceforge.net/patch/?group_id=10894

   http://sourceforge.net/patch/?group_id=12997

A maintainer uses CVS via SSH to access, track, and modify the various
branches of development in the repository of official Tcl or Tk source
code.

|cvs -d :ext:[email protected]:/cvsroot/tcl \
|   checkout -r $BRANCH_TAG -d $LOCAL_DIR tcl
|
|cvs -d :ext:[email protected]:/cvsroot/tktoolkit \
|   checkout -r $BRANCH_TAG -d $LOCAL_DIR tk

A maintainer examines the state of Tcl Improvement Proposals (TIPs) and
adds his comments to them at the TIP Document Collection.

   http://purl.org/tcl/home/cgi-bin/tct/tip/

A maintainer may follow and participate in TCT discussions about TIPs
and other matters concerning Tcl/Tk development on the TCLCORE mailing
list.

   http://lists.sourceforge.net/lists/listinfo/tcl-core

A maintainer may receive e-mail notification every time any change is
made to any entry in Tcl's or Tk's Bug Tracker or Patch Manager by
subscribing to the TCLBUGS mailing list.

   http://lists.sourceforge.net/lists/listinfo/tcl-bugs

~ There are multiple maintainers in my area.  What do I do?

The maintainer tasks are the same; you just have more hands to get the
job done.  It is up to the maintainers of an area to decide among
themselves how they will divide the tasks.  They might each take on a
particular subset of files.  Or they might let some maintainers fix
bugs while others review new features.  Or they might appoint one
maintainer as the ''lead'' and let him assign tasks to the others.
Whatever works for you, and gets the work done.

~ I found a bug in my area.  What do I do?

Bug finding and reporting is a job for the whole community, so when
you find a bug, take off your maintainer hat.  Report it to the Bug
Tracker just like anyone would.  If you recognize that the bug is in
your area, go ahead and assign it to the Category for your area and to
yourself or one of the other maintainers who share responsibility for
that area.

~ Why do I report the bug to myself?

So that the bug appears in the database.  Someone else may find it
too, and when they go to report it to the Bug Tracker, they should
discover that it's an already reported problem.  A registered bug
report is also the place where progress on fixing the bug can be
recorded for all to see.

~ There's a bug reported in the Category for the area I maintain. What do I do?

First, understand the bug report.  The best bug reports are clear and
come with a demonstration script, but not all reports are so well
crafted.  You may need to exchange messages with the person who
reported the bug.  If the reporter logged in to SourceForge as
''username'' before submitting a report, then you can write back to
''[email protected]''.  If the bug was reported by
''nobody'', the best you can do is post a followup comment to the bug
asking for more information, and hope the reporter comes back to
check.

Next, confirm that the bug report is valid, original, and that it
belongs in your area.  Does it correctly assert that some public
interface provided by your area behaves differently from its
documented behavior?  If not, then you should take the appropriate
action:

  1. If the bug report notes a problem in another project, assign it
     to a Developer who is an Admin of the other project.  Add a
     comment asking them to reassign to the correct project.  Assigned
     To: ''an Admin of the other project''.

  >  If no Developer is an Admin of the other project, or the other
     project isn't hosted by SourceForge, note the error in a comment,
     and mark the report invalid.  Resolution: Invalid; Status:
     Closed; Assigned To: ''yourself''.

  1. If the bug report notes a problem due to a bug in another area,
     reassign it to the appropriate Category.  Category: ''correct
     category''

  1. If the reporter's expectations are incorrect, point them to the
     documentation.  You may also want to revise the documentation if
     it is not clear.  Resolution: Invalid; Status: Closed; Assigned
     To: ''yourself''.

  1. If the bug report notes a problem already noted by another bug
     report, note the duplication.  Resolution: Duplicate; Status:
     Closed; Assigned To: ''yourself''.

  1. If the bug report acknowledges that the code is behaving as
     documented, but argues that the documented behavior should be
     revised, then the report is a feature request rather than a bug
     report.  More on handling feature requests below.  Group: Feature
     Request.

Valid, original bug reports in your area should be assigned to a
maintainer of your area.  If you are the only maintainer of your area,
assign the bug to yourself.  If there are multiple maintainers, you
should decide among yourselves how to divide up the bug report
assignments.

~ There's a bug assigned to me.  What do I do?

Now we get the the heart of what a maintainer does.  This is where you
unleash the energies and talents you bring to the table.  So, the best
answer is "Do what works best for you." The rest of this answer should
be read as additional guidelines and tips that have worked well for
others and might help you, but not as a mandatory checklist you must
follow.  If some advice below seems more burdensome than helpful, fall
back to "Do what works best for you."  The goal is to register a patch
that fixes the bug with the SourceForge Patch Manager.  Do whatever
helps you accomplish that goal.

Try to enlist the assistance of the person who reported the bug.  This
is especially important if the problem is platform-specific on a
platform you do not have access to.  Gaining the participation of the
person who reported the bug can have many other benefits too.  They
see that progress is being made.  They can offer additional insights
they have, but left out of their original report.  They can see how
better bug reports lead to faster, better solutions, so their next
reports may be of higher quality.  They may even gain enough
experience that their next report may come with the correction already
attached.  Eventually, they may even become maintainers themselves.

First, try to develop a test that demonstrates the bug and add it to
the section of the test suite for your area.  If the original bug
report contained a demonstration script, perhaps you can adapt that.
The new test will help you verify when you have fixed the bug.

If a fix for the bug is offered with the report, give it a try.
Otherwise develop a fix yourself.  Take care that while fixing the
bug, you do not create new bugs by changing the correct behavior of
other parts of the code in your section.  The test suite for your area
is very helpful.  Use it.

It may become apparent that the best fix for your bug can only be
accomplished after another bug is fixed first, or perhaps after a new
feature is added to Tcl/Tk.  In those cases, add a comment to the
original bug report so those interested will know what is causing the
delay.  SourceForge may offer a way to denote these dependencies as
well.

If you have trouble fixing the bug, ask for help.  Try the other
maintainers of your area first.  Then try posting comments attached to
the original bug report.  Using ''cvs log'', you can get a list of
developers who've recently made changes to the files you maintain.
They might be able to offer advice, or explanations about why the code
is the way it is.  If none of these focused searches for help bears
fruit, then try broader requests to the TCLCORE mailing lists, or the
news:comp.lang.tcl newsgroup.

At any time, you may have several bugs assigned to you.  It will help
guide the expectations of the Tcl community if you can assign priority
values to the bugs indicating the importance you assign to them.  Try
to work on fixing higher priority bugs before lower priority bugs.
Some reasons you might give a bug a higher priority include:

    1. The bug causes a panic or core dump.

    1. Documentation is missing or incorrect.

    1. Other bug fixes are waiting on this bug fix.

    1. Several duplicate reports or "me too" comments about the bug
       are coming in from the community.

Some reasons you might give a bug a lower priority include:

    1. A workaround is identified (add it as a comment attached to the
       bug report).

    1. Feature requests tend to get lower priority since they should
       be handled through the TIP process.

Once you have crafted a fix for the bug, create a patch to the
official source code (including the new tests that test for the fixed
bug) and register it with the SourceForge Patch Manager.  Note the
number of the bug report fixed by the patch somewhere in the summary
or comments associated with the patch.  Assign the patch to yourself.
Assign the Category to the area you maintain.

~ There's a patch registered under the Category I maintain.  What do I do?

The SourceForge Patch Manager is used to review and revise patches
before they are committed to the official source code.  Your actions
depend on what the patch does to your area, and who the patch is
assigned to.  The patch may change the public interface provided by
your area (feature change); or the change may be completely internal
(bug fix, or re-implementation) within your area.  The patch may be
assigned to you, to someone else, or to nobody.  The person the patch
is assigned to is the person who is leading the effort to integrate
the patch into the official source code.

~ What if the patch is assigned to nobody?

The patch has probably been contributed by someone not on the list of
Developers.  It may be a contributed bug fix, or a contributed
implementation of a TIP.  Assign contributed bug fixes to the same
maintainer who is assigned the corresponding bug report.  If there is
no corresponding bug report, add one.  Assign TIP implementations to
the Developer identified in the TIP as the one responsible for
implementation of that TIP, or the TCT member who sponsored the TIP.

If the patch changes only your area (and shared or generated files),
then leave the Category in your area.  If the patch changes other
areas as well as yours, change the category to None.

~ What if the patch is assigned to me?

Presumably you've assigned it to yourself to indicate that you're
taking charge of integrating that patch into the official sources.  If
that's a mistake, treat the patch as if it were assigned to nobody.
If you are the one leading the integration effort, see below (How do I
integrate a patch into the official sources?).

~ What if the patch is assigned to someone else?

If the patch is assigned to another maintainer in your area, let him
handle it.  Leave it alone.

If the patch makes no changes in your area, change the Category of the
patch to None.

If the patch makes changes in your area, and is assigned to a
Developer who is not a maintainer of your area, that Developer is
asking for review of the patch's changes to your area.  You or one of
the other maintainers of your area should review the patch and accept
or reject it.  Read on...

~ What special review does a "feature change" patch require?

Changes to the public interface of your section must be proposed to
and accepted by the TCT through the TIP process before they can be
added to the official Tcl source code.  If the patch changes the
public interface of your section, then there should be an associated
TIP describing the new feature(s) that patch implements.  Until there
is such a TIP, and that TIP has been accepted by the TCT (check the
value of the State header), you should not approve the patch.

Once there is an approved TIP corresponding to the patch, you should
confirm that the patch correctly implements the accepted feature as
described by the TIP.  If not, you should not approve the patch.

After confirming that the patch correctly implements the feature
change described in an accepted TIP, you should still review the
technical merit of the patch's changes to your area before approving
it.

~ How do I review the technical merits of a patch?

Apply the patch and run the test suites that cover your area.  Check
that the patch does not add any new test failures.  If the patch is a
bug fix, check that it actually fixes the bug.  Think five times
before approving a patch that causes new test failures or incompletely
fixes a bug or incompletely implements an approved TIP.

Keep in mind that once the patch is integrated into the official
sources, you'll be expected to maintain it.  It is not in your
interest to approve patches that make your job harder.  Think four
times before approving a patch that you do not understand.

Check that the patch keeps the features offered on different platforms
consistent.  If not, be certain that the documentation properly notes
the platform-specific behavior.  Think three times before approving a
patch that causes the capabilities of Tcl/Tk to further diverge on
different platforms.

Check that the patch follows Tcl's established coding conventions.
See the Tcl/Tk Engineering Manual
(http://purl.org/tcl/home/doc/engManual.pdf) and the Tcl Style Guide
(http://purl.org/tcl/home/doc/styleGuide.pdf) for details.  This is
especially important when accepting contributed patches.  Think twice
before approving a patch that doesn't conform to these conventions.

Check the effect of the patch on the performance of Tcl/Tk.  Use the
tclbench set of benchmarks.

|cvs -d :pserver:[email protected]:/cvsroot/tcllib \
|      checkout tclbench

Think carefully before approving a patch that significantly degrades
the performance of important operations.

Finally, while examining the patch, you may see a better way to
accomplish the effect of the changes in your area.  If you can provide
that alternative implementation reasonably quickly, then propose it as
a revision to the patch.  However, be careful not to let the perfect
be the enemy of the good.  If a patch works, do not reject just
because you can imagine a better way it could be done.  Provide the
better way, or accept the less good way in the patch, and leave
migration to the better way for later when you have the time.

To approve the patch's changes to your area, simply note your approval
in a followup comment on the patch.  Indicate in your comment the
Category of the area for which you approve the changes.  If the patch
changes multiple areas, set the Category of the patch back to None.

To reject the patch, you also indicate your rejection in a followup
comment.  You should explain the reasons for your rejection so that
the patch can be revised with the goal of gaining your approval.  If
you can supply the needed revisions with reasonable effort, do so.  If
the patch changes multiple areas, set the Category of the patch back
to None.

Unless the patch is assigned to you, do not change the Status of the
patch.  Leave that to the Developer assigned to the patch.

~ How do I integrate a patch into the official sources?

First you need the approval of at least one maintainer of each section
changed by the patch.

~ How do I get approval for integration?

First, assign the patch to yourself to indicate that you are leading
the integration effort.  Next, determine the list of categories
corresponding to the areas changed by the patch.  It may help if you
list them in a comment attached to the patch.

For each category in the list, assign the Category of the patch to
that category.  Then wait for a maintainer for that area to review the
patch.  If one approves it, then assign the next Category in the list.
If maintainers for all areas on the list approve the same patch, you
may integrate the patch into the official sources.

If a maintainer rejects the patch, revise the patch to address his
concerns.  Then start the review again.  Start with the maintainer who
rejected the first patch to be sure his concerns are addressed first.

Note that if the patch changes only the area you maintain, then you
may immediately integrate the patch into the official sources once you
are satisfied with it and it is registered in the Patch Manager.

~ The patch is approved.  How should it be integrated?

Get a CVS working directory that is up to date with the HEAD branch of
the official source repository.  Apply the patch to your working
directory, and then 'cvs commit' the changes to the HEAD branch.

At the same time you commit the patch, be sure to add an entry to the
ChangeLog file describing the change.  Follow the established format,
which is derived from the GNU coding conventions.  The description
should be brief, but should describe the change reasonably completely.
Include the SourceForge Bug and Patch ID numbers in the ChangeLog
entry, but do not assume that the reader will have access to the Bug
Tracker and Patch Manager to be able to understand the entry.  You may
assume the reader has access to the documentation.

Finally, with the patch integrated, change the Status of the patch in
the Patch Manager to Accepted.  If any bugs were fixed by the patch,
change their Resolution to Fixed, and their Status to Closed.

~ I want a patch review even though the patch changes only my area.

Keep in mind that integrating a patch into the official sources is not
an irreversible act.  Commits to the HEAD branch will be checked out
and tested by members of the Tcl community who are tracking Tcl/Tk
development.  Alpha and beta releases of Tcl/Tk that include your
patch will also get your changes reviewed in practical settings.

That said, if you really want a pre-commit review of your patch, you
can add a comment to the patch asking for review.  Someone will
probably respond.  It's up to your judgment how long to wait, keeping
in mind that you are the maintainer, so your judgment on the quality
of patches in your area is implicitly trusted.

~ What about CVS branches?

When you integrate a patch into the official source code, you will
usually 'cvs commit' the patch onto the HEAD branch.  If the patch
includes a feature change, it must (except in unusual circumstances
approved by the TCT) be committed to the HEAD branch.  The HEAD branch
is the development branch from which alpha releases of Tcl/Tk are
generated.

At any time, there is also one or more ''stable'' branches of
development.  As of February, 2001, the branch 'core-8-3-1-branch'
indicates the sequence of revisions from which the 8.3.x releases of
Tcl/Tk are generated.

Since the Tcl Core Team took over development of Tcl/Tk, no changes
have been committed to a stable branch, so we really have not
established procedures on how we will decide what bug fixes should and
should not be applied to the stable branch.  It is possible that
maintainers will be involved, though.  It is also possible that a
special team will be appointed to update the stable branch in
preparation for the next stable release.  In the case that you as a
maintainer are asked to commit to the stable branch, be aware that the
only patches that should be committed to a stable branch are those
that fix bugs.  No new features should be committed here.

The other kind of branch is a ''feature'' branch.  This is a
development branch on which a sequence of several revisions may be
committed as work in progress on a new feature, or re-implementation
of existing features.  Typically a feature branch will be created if
the effort...

   * ...touches on several functional areas;

   * ...is worked on jointly by several Developers;

   * ...is complex enough to require several revisions;

   * ...needs prototyping to determine the best TIP proposal to make;
     or

   * ...makes an incompatible change to Tcl/Tk that properly belongs
     on the next major version of Tcl/Tk before the HEAD branch has
     been designated for work toward the next major version.

As a Developer, feel free to create a feature branch if you have a
reason to use one.  Make a note of your branch tags in [31].  Avoid
the use of a branch tag matching core-* .
Save the core-* branch tags for the tags of official stable branches
and releases.  To avoid conflict with other Developers, consider using
your SourceForge login name as a prefix on the feature branch tags you
create.  Try to also make the branch tag descriptive of the purpose of
the branch.

One big advantage of a feature branch is that any Developer may commit
changes to a feature branch without all the publication, review, and
approval overhead required when committing patches to the HEAD or
stable branches.  On the feature branches you can go through multiple
revisions reasonably quickly and spend the administrative overhead
only at the end when it is time to apply the finished product to the
official branches.

~ What other things does a maintainer do?

The tasks of fixing bugs and approving and committing patches to the
official source code of Tcl and Tk are the core tasks that maintainers
perform.  That's all the job actually requires.

You will probably want to keep an eye on the TCT's plans for Tcl/Tk
development as well.  If a TIP proposes a new feature in your area, it
is in your interest to know about it, and propose revisions and
improvements to it.  Ultimately you will be asked to approve the patch
that implements the new feature, and then you will be expected to
maintain it, so if you have concerns about a proposal, it's best to
make them known early.  TCT members will probably ask your opinion on
TIPs that propose changes to your area for this reason.

~ Comments

Please add your comments here.

   > Well, since I drafted this SourceForge has replaced the
     Bug Tracker and Patch Manager with a ''Tracker''.  This
     TIP ''really'' needs revision now.

~ Copyright

This document has been placed in the public domain.

TIP:            29
Title:          Allow array syntax for Tcl lists
Version:        $Revision: 1.7 $
Author:         Kevin Kenny <[email protected]>
Author:         Donal K. Fellows <[email protected]>
State:          Rejected
Type:           Project
Vote:           Done
Created:        07-Mar-2001
Post-History:   
Discussions-To: news:comp.lang.tcl,mailto:[email protected]
Tcl-Version:    9.0

~ Abstract

Most popular programming languages provide some sort of indexed array
construct, where array subscripts are integers.  Tcl's lists are, in
fact, arrays, but the existing syntax obscures the fact.  Moreover,
the existing list commands make it difficult to manipulate lists as
arrays without running into peculiar performance issues.  This TIP
proposes that the syntax of ''variableName(value)'' be extended to
function as an array selector if ''variableName'' designates a list.
This change is upward compatible with existing Tcl scripts, because
the proposed syntax results in a runtime error in every extant Tcl
release.

~ Rationale

The implementation of lists in Tcl has evolved far beyond the original
conception.  While lists were originally conceived to be strings with
a particular syntax that allowed them to be parsed as lists, the
internal representation of a list is now an array of pointers to
''Tcl_Obj'' structures.

Tcl programmers, for the most part, have not taken advantage of this
evolution.  Code that uses hash tables for the purpose is still
extremely common.  Moreover, it is difficult to update lists in place,
even if their internal representations are known not to be shared.
One example of this difficulty is seen in the discussions
(http://purl.org/thecliff/tcl/wiki/941) of how best to shuffle a list
of items.  The discussion began with a na�ve implementation of Jon
Bentley's method of performing random swaps:

|  proc shuffle1 { list } {
|      set n [llength $list]
|      for { set i 0 } { $i < $n } { incr i } {
|          set j [expr {int(rand()*$n)}]
|          set temp [lindex $list $j]
|          set list [lreplace $list $j $j [lindex $list $i]]
|          set list [lreplace $list $i $i $temp]
|      }
|      return $list
|  }

Aside from the fact that the syntax obscures what the program is
doing, the implementation suffers from an obscure performance problem.
When the ''lreplace'' calls in the ''shuffle1'' procedure are
executed, the internal representation of ''list'' has two references:
the value of the variable, and the parameter passed to ''lreplace''.
The multiple references force ''lreplace'' to copy the list, leading
to quadratic performance when large lists are shuffled.

It is possible, albeit difficult, to alleviate this problem by careful
management of the lifetime of ''Tcl_Obj'' structures, but this change
complicates the code.  The simplest way to fix the performance is
probably to use Donal Fellows's implementation of the ''K''
combinator:

| proc K { x y } { set x }

which allows the caller of ''lreplace'' to extract the value of
''list'', change the value of ''list'' so that the extracted value is
unshared, and then pass the extracted value as a parameter to
''lreplace:''

|  proc shuffle1a { list } {
|      set n [llength $list]
|      for { set i 0 } { $i < $n } { incr i } {
|          set j [expr {int(rand()*$n)}]
|          set temp1 [lindex $list $j]
|          set temp2 [lindex $list $i]
|          set list [lreplace [K $list [set list {}]] $j $j $temp2]
|          set list [lreplace [K $list [set list {}]] $i $i $temp1]
|      }
|      return $list
|  }

Now the performance of the code is ''O(n)'' where ''n'' is the length
of the list, but the programmer's intent has been seriously obscured!

These drawbacks have led prominent individuals such as Richard
Stallman (http://www.vanderburg.org/Tcl/war/0000.html) to assert that
Tcl lacks arrays.

''This proposal includes the absolute minimum of functionality needed
to provide array-style indexing for variables containing Tcl list
objects.''  The reason for this limitation is that omitted
functionality can be added later without breaking existing scripts.
On the other hand, ill-considered extensions may turn into something
that we're doomed to support forever.

~ Specification

This TIP's proposed change can be stated succinctly:

 > Wherever the notation ''a(x)'' may be used to refer to an array
   element in the language, allow it also to refer to an element of a
   list, provided that the variable ''a'' is scalar and the value
   ''x'' is an index suitable for the ''lindex'' command.

   ''Exception:'' Traces, ''unset'' and ''upvar'' calls designating
   individual list elements shall not be supported.  (As a consequence
   of this rule, list elements may also not appear as linked variables
   in C code, implying that they also cannot appear as ''-variable''
   or ''-textvariable'' options on Tk widgets.)

Note that this change is backward compatible with existing Tcl
scripts!  If a notation like ''a(x)'' is used to refer to a scalar
variable in today's Tcl, the result is an error:

| % set a [list foo bar grill]
| foo bar grill
| % set a(2)
| can't read "a(2)": variable isn't array
| % puts $a(2)
| can't read "a(2)": variable isn't array
| % set a(2) zot
| can't set "a(2)": variable isn't array

The default behavior, if ''a'' is not set, and a script executes

| set a(2) zot

will still be to create an associative array.  If a script wishes to
perform such actions on a list, it will be necessary first to
initialize the variable:

| set a [list]
| set a(0) foo

Note that in the example above, there is no requirement that the
internal representation of ''a'' be a list; the line,

| set a [list]

could have been replaced with

| set a {}

with the only impact being the run-time cost of shimmering the empty
string into an empty list.  Nowhere does this proposal introduce
behavior that depends on a specific internal representation for any
variable.

This proposal the syntax of the subscript shall be precisely those
values that are accepted as the second argument to the ''lindex'' command.
In other words, the subscript may be an integer ''N'', or the string
''end'' or ''end-N''.  The value of ''N'' may not be less than zero
nor greater than nor equal to the length of the list on any usage that
reads a list element.  

A usage that writes a list element may use an integer equal to
 the length of the list, or the string ''end+1'', to designate
the element one past the end.  In other words,

|  set a(end+1) foo

will have the same effect as:

|  lappend a foo

With the proposed change in syntax, the procedure to shuffle a list
becomes much more straightforward:

|  proc shuffle1 { list } {
|      set n [llength $list]
|      for { set i 0 } { $i < $n } { incr i } {
|          set j [expr {int(rand()*$n)}]
|          set temp $list($j)
|          set list($j) $list($i)
|          set list($i) $temp
|      }
|      return $list
|  }

The given implementation copies the list only once, the first time
that the line:

|          set list($j) $list($i)

is executed.  Thereafter, the list is an unshared object, and the
replacements are performed in place.

It shall be illegal to pass a list element as the parameter to
''upvar;'' that is, the following usage:

|  proc increment { varName } {
|      upvar 1 $varName v
|      incr v
|  }
|  set x [list 1 2 3]
|  increment x(0)

will ''not'' be supported.  However, the commoner form:

|  proc incrementElement { arrayName index } {
|      upvar 1 $arrayName array
|      incr array($index)
|  }
|  set x [list 1 2 3]
|  incrementElement x 0

will, of course, work as expected.

~ Discussion

Several reviewers expressed concern about the reuse of array syntax.
In particular, the alternative syntax $a<$element> was proposed
repeatedly.  Alas, there is no good alternative syntax that will not
break at least some existing scripts.  The proposed syntax using
angle-brackets is a poor choice, because Tcl scripts that generate
Web pages frequently have code like:

|  puts "<$tag>$text</$tag>

that would be broken horribly by such a change.

There are several obvious extensions to the proposal that are not
addressed, and these omissions are intentional.

   * The proposal makes no attempt to deal with multiple subscripts
     as a means of accessing nested lists.

Use of multiple subscripts is closely related to the withdrawn [22]
(which the author of this TIP intends to revive).  If the related TIP
is accepted, the syntax for the subscript could readily be expanded
so that it could be a Tcl list giving the subscripts in lexicographic
sequence.  For example

| set a(2 3) foo

could be used to set the fourth element of the third sublist.

   * The proposal allows the ''set'' command (or any other use of
     ''Tcl_SetVar2Ex'') to set only the elements that are in the list
     already plus the one one beyond the end.

Tcl lists are fundamentally dense arrays.  Allowing non-contiguous
elements, that is, sparse arrays, is a fundamental change to their
semantics.  Such a change is not contemplated at this time.

   * The proposal does not allow the ''unset'' command (or any
     other command that arrives at ''Tcl_UnsetVar2'') to delete members
     of a list.

Earlier versions of the proposal had proposed to permit:

|  unset a([expr { [llength $a] - 1}])

or equivalently:

|  unset a(end)

to reduce the length of the list by one.  In subsequent discussions,
the reviewers found it distasteful that the proposed syntax did not
permit unsetting interior elements of a list.  Alas, the discussion
did not arrive at a consensus on what the precise semantics of such
an operation ought to be.  Some reviewers favored attempting to emulate
sparse arrays (again, a fundamental change to the semantics of
Tcl lists that is not contemplated at this time).  Others preferred
the semantics of shifting the remaining elements, so that

|   unset a($n)

would always be equivalent to

|   set a [lreplace $a $n $n]

except for performance.  Both camps found it overly restrictive to
limit the semantics of ''unset'' to those of the original proposal.
Because the two groups failed to achieve a consensus, the author of
this TIP finds it prudent to forbid ''unset'' altogether in the
initial implementation.

   * The ''array'' command continues to operate only on associative
     arrays.

Lists are a simple enough structure that the full power of the
''array'' command is not required to deal with them, and having it
work on lists as well as arrays seems like needless effort.  Moreover,
existing code may well depend on a combination of ''[array exists]''
and ''[info exists]'' to distinguish associative arrays from scalar
variables (including lists).

   * The ''upvar'' command cannot address individual list elements.

Extending the syntax in this fashion would make ''upvar'' more
consistent in its behavior, but appears to be expensive, in terms of
both performance (tracking down the linked references if a list is
rebuilt) and the effort required for implementation (the author of
this TIP is unlikely to have the time required to implement the
necessary changes to ''struct Var'' and the associated code).

   * No traces on list elements shall be supported.  List elements
     cannot function as linked variables in C code.

The original proposal had specified how write and unset, but not read,
traces could be implemented.  The original proposed functionality is
described in the Appendix.  The author of this TIP had proposed it
primarily so that list elements could function as linked variables
(for instance, in the ''-variable'' and ''-textvariable'' options
of Tk widgets).

Once again, this part of the original proposal failed for lack of
consensus among the reviewers.  Some felt that supporting read traces
in one context but not another would be overly confusing.  Moreover,
the proposal as written would cause write traces on the elements to fire
if the internal representation of a variable shimmered between a list
and something else.  Some reviewers found the excess trace callbacks
to be objectionable.  

At least one reviewer proposed a separate ''trace add element'' syntax
for list-element traces.  This syntax would address some of the
concerns about the lack of read traces (there's no reason that ''trace
add element'' should function the same as ''trace add variable'').
Alas, it would not address the problem of linked variables, which was
the main reason for having the traces in the first place.

Given the lack of consensus, the author of this TIP finds it prudent
to withdraw or postpone this portion of the proposal.

~ See Also

[22] - withdrawn.

~ Reference Implementation

No reference implementation has yet been developed; the author of this
TIP wishes to solicit the opinions of the Tcl community before
spending a lot of time implementing a possibly bad idea.

~ Change history

''12 March 2001:'' Added detailed discussion of the specific subscript
ranges supported by read, write and unset operations.  Changed the discussion
to reject the alternative of padding an array when setting an index beyond
the end.  Added discussion of the details of write and unset traces, and
rejecting read traces as being infeasible to implement.  Clarified the
example of creating an empty list so as to avoid any misapprehension that
these changes depend on list variables' having a particular representation
at any given time; in fact, every detail of this proposal is tolerant of
shimmering.

''13 March 2001:'' Fixed a copy-and-paste error in the 'incrementElement'
example, and added to the discussion the fact that all operations will
throw errors in the event of a malformed list.

''30 March 2001:'' Revised yet again, in an attempt to remove as
much controversial functionality as possible and reduce the TIP to the
minimum useful subset, on the grounds that it is prudent to avoid
supporting functionality that may later prove ill-considered.

~ Summary of objections

''DeJong,'' ''English'' (non-voting), ''Flynt'' (non-voting),
''Harrison,'' ''Ingham,'' ''Lehenbauer,'' ''Polster,'' (non-voting),
''Porter,'' and ''Sofer'' (non-voting), expressed concern that the
proposed syntax is confusing, since the target object could be either
an associative array or a linear array (that is, a Tcl list).
These objections varied in stridency from "yes, it is a risk, and
I'm prepared to accept it," to "this will just be too confusing, and I
can't countenance this proposal."

''Hobbs'' found the original proposal's omission of reverse indexing
distasteful.  The current version of the proposal embraces his
suggested change.

''Cuthbert'' (non-voting), ''Hobbs'', and ''Porter'' expressed concern
over the semantics of ''unset.'' Since consensus was not achieved, the
current version of the proposal defers implementation of ''unset.''

Several reviewers, most notably ''Ousterhout,'' found the proposed
''trace'' semantics distasteful.  The current version of the proposal
eliminates ''trace'' on list elements.

Several reviewers appeared to labor under the misconception that this
TIP introduces behavior that is dependent at run time upon the
internal representation of a Tcl object.  It does not; it is tolerant
of shimmering in all cases.

Several reviewers objected to the proposal on the grounds that it does
not specify a general object system and how such a system would allow
for generic containers with array syntax.  The author's intention in
writing it was not to propose such a system, but only to propose a
small piece of syntactic sugar, implementable here and now, that is
compatible with that broader vision.

~ Appendix: Possible implementation of read and unset traces.

The original proposal contained the following language, which could
be used as a guide if traces on list elements are contemplated at a
future time.

Write and unset traces on list elements shall be supported; it shall
be permissible to write:

|    trace add variable x(1) write writeCallback

or

|    trace add variable x(1) unset unsetCallback

The ''write'' callback shall be invoked whenever the given list
element changes value; the ''unset'' callback shall be invoked
whenever the variable is unset or when its length shrinks to the point
that it no longer has a member with the given index.

Read traces on list elements shall ''not'' be supported.  It is
too difficult at this point to define what their semantics should be.
For instance, if a program executes the following code:

|   trace add variable x(0) read readCallback
|   set x [list foo bar grill]
|   set y [string range $x 4 end]

should the callback fire?  By one argument, the program has not
read element zero of the list; by another, using the list as a string
has read every element, and all read traces should fire.  In any case,
the read trace on a variable fires before its usage is known; it appears
impossible in existing code to implement selective read tracing on list
elements.

The implementation of write and unset traces on list elements will be
done by establishing a C-level write trace on the variable as a whole.
The client data of the trace will designate a structure containing the
ordinal number of the element being traced, and a ''Tcl_Obj'' pointer
designating its old value.  The reference count of the ''Tcl_Obj''
will be incremented when this pointer is stored.  Note that this
increment operation makes the object shared.  Any change to the
designated element will thus need to copy the object.

When the write trace fires, the list representation of the variable
will be extracted, reconstituting it from the string representation if
necessary.  If extracting the list representation fails, the trace
will be considered to have failed as well, and the trace callback will
return ''TCL_ERROR''.  If extracting the list representation succeeds,
the list length will be compared with the ordinal number of the
element being traced.  If the element number is no longer within the
list, an unset trace fires if one exists.  If the element number is
within the list, the two ''Tcl_Obj'' pointers are compared.  If they
are identical, the list element in question is unchanged, and nothing
need be done.  Otherwise, the write trace fires.  

This behavior is conservative in that an operation that spoils the
list representation of the object is considered to have written every
element of the list.  This rule is consistent with the rule that write
traces on ordinary Tcl variables fire whenever the variable is set,
even if it is being set to an identical value.

In any event, after the conclusion of a trace callback, the saved
Tcl_Obj will have its reference count decremented and be replaced with
the current element of the list (with reference count appropriately
incremented, of course).

~ Copyright

This document has been placed in the public domain.

TIP:            3
Title:          TIP Format
Version:        $Revision: 1.3 $
Version:        $Revision: 1.2 $
Author:         Andreas Kupries <[email protected]>
Author:         Donal K. Fellows <[email protected]>
State:          Accepted
Type:           Process
Vote:           Done
Created:        14-Sep-2000
Post-History:

   Title:
	Defines the title of the document using plain text. May change
	during the discussion and review phases.

   Version:
	Specifies the version of the document.  Usually something like
	$Revision: 1.3 $. (Initially $Revision: 1.3 $ should be used, which
	$Revision: 1.2 $. (Initially $Revision: 1.2 $ should be used, which
	is then changed by the version control to contain the actual
	revision number.

   Author:
	Contact information (email address) for each author. The email
	address has to contain the real name of the author.  If there
	are multiple authors of the document, this header may occur

|
|#index: long
|
|#image:3example This is a test caption
|
|This is an example long TIP reference tip:3 that should be expanded in
|a renderer-specific way...
|
|This is an example non-reference - ''index[[3]]'' - that should not
|be rendered as a link (to this document or anywhere else) at all.
|Note that the dashes in the previous sentence (with whitespace on
|each side) are candidates for rendering as long dashes (em-dashes) on
|output-media which support this.
|
| Supported URLs: should be http, https, mailto, news, newsrc, ftp and
|   gopher.  Test here...
|
| > HTTP URL - http://purl.org/thecliff/tcl/wiki/
|
| > HTTPS URL - https://sourceforge.net/
|
| > FTP URL - ftp://src.doc.ic.ac.uk/packages/tcl/tcl/
|
| > NEWS URL - news:comp.lang.tcl
|
| > MAILTO URL - mailto:[email protected]?subject=TIP3
| 
| > Others (might not be valid links!) - gopher://info.mcc.ac.uk,
|   newsrc:2845823825

and here is the rendered result.

#index:

#index:short

#index: long

#image:3example This is a test caption

This is an example long TIP reference tip:3 that should be expanded in
a renderer-specific way...

This is an example non-reference - ''index[[3]]'' - that should not
be rendered as a link (to this document or anywhere else) at all.
Note that the dashes in the previous sentence (with whitespace on
each side) are candidates for rendering as long dashes (em-dashes) on
output-media which support this.

 Supported URLs: should be http, https, mailto, news, newsrc, ftp and
   gopher.  Test here...

 > HTTP URL - http://purl.org/thecliff/tcl/wiki/

 > HTTPS URL - https://sourceforge.net/

 > FTP URL - ftp://src.doc.ic.ac.uk/packages/tcl/tcl/

 > NEWS URL - news:comp.lang.tcl

 > MAILTO URL - mailto:[email protected]?subject=TIP3
 
 > Others (might not be valid links!) - gopher://info.mcc.ac.uk,
   newsrc:2845823825

----

~ Copyright

This document has been placed in the public domain.

TIP:            30
Title:          Tk Toolkit Maintainer Assignments
Version:        $Revision: 1.27 $
Author:         Don Porter <[email protected]>
Author:         Donal K. Fellows <[email protected]>
Author:         Jan Nijtmans <[email protected]>
Author:         Todd M. Helfter <[email protected]>
Author:         Chengye Mao <[email protected]>
Author:         George B. Smith <[email protected]>
Author:         Miguel Ba��n <[email protected]>
Author:         Daniel Steffen <[email protected]>
Author:         Peter Spjuth <[email protected]>
Author:         Jeff Hobbs <[email protected]>
State:          Draft
Type:           Informative
Vote:           Pending
Created:        09-Mar-2001
Post-History:   

~ Abstract

This document keeps a record of who maintains each functional area
of Tk ([23]).

~ Assignments

Listed below are Tk's 86 functional units, in the same order as in
[23].  See [23] for the precise definition of what code belongs to
what area, and how maintainers designate their support for
platform-specific portions of the code.  The area names listed below
are also the Categories in the SourceForge Tracker for the Tk Toolkit
(http://sourceforge.net/tracker/?group_id=12997).

For each of Tk's functional units, the following maintainers are 
assigned:

   1. ''Bindings'' - Jeff Hobbs <[email protected]>

   2. ''Appearance'' - Jeff Hobbs <[email protected]>

   3. ''[*button] and [label]'' - Allen Flick <[email protected]>, Jeff Hobbs <[email protected]>, Daniel Steffen <[email protected]> (Mac)

   4. ''Canvas Basics'' - Jeff Hobbs <[email protected]>, Jan Nijtmans <[email protected]>

   5. ''Canvas Items'' - Jeff Hobbs <[email protected]>, Jan Nijtmans <[email protected]>

   6. ''Canvas PostScript'' - Jeff Hobbs <[email protected]>

   7. ''[entry]'' - Allen Flick <[email protected]>, Jeff Hobbs <[email protected]>

   8. ''[frame] and [toplevel]'' - Jeff Hobbs <[email protected]>,
	Peter Spjuth <[email protected]>

   9. ''[listbox]'' - Allen Flick <[email protected]>, Jeff Hobbs <[email protected]>

   10. ''Generic Menus'' - Jeff Hobbs <[email protected]>, Todd Helfter <[email protected]>

   11. ''Mac Menus'' - George B. Smith <[email protected]>, Daniel Steffen <[email protected]>

   12. ''Unix Menus'' - Jeff Hobbs <[email protected]>, Todd Helfter <[email protected]>

   13. ''Win Menus'' - Jeff Hobbs <[email protected]>, Todd Helfter <[email protected]>

   14. ''[message]'' - Jeff Hobbs <[email protected]>

   15. ''[scale]'' - Jeff Hobbs <[email protected]>, Daniel Steffen <[email protected]> (Mac)

   16. ''[scrollbar]'' - Jeff Hobbs <[email protected]>, Daniel Steffen <[email protected]> (Mac)

   17. ''[spinbox]'' - Jeff Hobbs <[email protected]>

   18. ''[text]'' - Jeff Hobbs <[email protected]>

   19. ''Menubars (obsolete)'' - Jeff Hobbs <[email protected]>

   20. ''[tk_optionMenu]'' - Jeff Hobbs <[email protected]>

   21. ''Option Parsing'' - Jeff Hobbs <[email protected]>, Daniel Steffen <[email protected]> (Mac)

   22. ''Relief'' - Jeff Hobbs <[email protected]>, Fr�d�ric Bonnet <[email protected]>

   23. ''Built-in Bitmaps'' - Jeff Hobbs <[email protected]>, Jan Nijtmans <[email protected]>, Daniel Steffen <[email protected]> (Mac)

   24. ''Conversions From String'' - Jeff Hobbs <[email protected]>

   25. ''Objects'' -  Jeff Hobbs <[email protected]>

   26. ''Utility Functions'' - Jeff Hobbs <[email protected]>

   27. ''Colormaps and Visuals'' - Jeff Hobbs <[email protected]>

   28. ''Color Names'' - Jeff Hobbs <[email protected]>, Daniel Steffen <[email protected]> (Mac)

   29. ''Cursor Names'' - Jeff Hobbs <[email protected]>, Daniel Steffen <[email protected]> (Mac)

   30. ''Key Symbols'' - Jeff Hobbs <[email protected]>, Daniel Steffen <[email protected]> (Mac)

   31. ''Generic Dialog Support'' - Donal K. Fellows <[email protected]>, Jeff Hobbs <[email protected]>

   32. ''[tk_chooseColor]'' - Donal K. Fellows <[email protected]> ''(Unix)'', Jeff Hobbs <[email protected]>

   33. ''[tk_dialog]'' - Donal K. Fellows <[email protected]> ''(Unix)'', Jeff Hobbs <[email protected]>, Daniel Steffen <[email protected]> (Mac)

   34. ''[tk_chooseDirectory]'' - Donal K. Fellows <[email protected]> ''(Unix)'', Jeff Hobbs <[email protected]>

   35. ''[tk_get*File]'' - Donal K. Fellows <[email protected]> ''(Unix)'', Jeff Hobbs <[email protected]>

   36. ''[tk_messageBox]'' - Donal K. Fellows <[email protected]> ''(Unix)'', Jeff Hobbs <[email protected]>

   37. ''Image Basics'' - Jan Nijtmans <[email protected]>

   38. ''Bitmap Images'' - Jan Nijtmans <[email protected]>,
			   Kevin Griffin <[email protected]>

   39. ''Photo Images'' - Jan Nijtmans <[email protected]>

   40. ''Photo Image|GIF'' - Jan Nijtmans <[email protected]>

   41. ''Photo Image|PPM'' - Jan Nijtmans <[email protected]>

   42. ''Generic Fonts'' - Jeff Hobbs <[email protected]>

   43. ''Mac Fonts'' - George B. Smith <[email protected]>, Daniel Steffen <[email protected]>

   44. ''Unix Fonts'' - Jeff Hobbs <[email protected]>

   45. ''Win Fonts'' - Jeff Hobbs <[email protected]>

   46. ''Geometry Management'' - Jeff Hobbs <[email protected]>, Chengye Mao <[email protected]>

   47. ''[grid]'' - Jeff Hobbs <[email protected]>, Peter Spjuth <[email protected]>

   48. ''[pack]'' - Jeff Hobbs <[email protected]>, Peter Spjuth <[email protected]>

   49. ''[place]'' - Jeff Hobbs <[email protected]>, Peter Spjuth <[email protected]>

   50. ''[clipboard]'' - Jeff Hobbs <[email protected]>
		         Joe English <[email protected]> (Unix), Daniel Steffen <[email protected]> (Mac)

   51. ''[selection]'' - Jeff Hobbs <[email protected]>,
		         Joe English <[email protected]> (Unix)

   52. ''[console]'' - Jeff Hobbs <[email protected]>, Chengye Mao <[email protected]>

   53. ''[focus]'' - Jeff Hobbs <[email protected]>

   54. ''[grab]'' - Jeff Hobbs <[email protected]>

   55. ''[option]'' - Allen Flick <[email protected]>, Jeff Hobbs <[email protected]>

   56. ''[send]'' - Allen Flick <[email protected]>, Jeff Hobbs <[email protected]>, Daniel Steffen <[email protected]> (Mac)

   57. ''[tk_focus*]'' - Jeff Hobbs <[email protected]>

   58. ''[tk_setPalette]'' - Jeff Hobbs <[email protected]>

   59. ''Safe Tk'' - Jeff Hobbs <[email protected]>

   60. ''Geometry Functions'' - Jeff Hobbs <[email protected]>, Chengye Mao <[email protected]>

   61. ''Tk_Win Functions'' - Jeff Hobbs <[email protected]>

   62. ''Graphic Contexts'' - Jeff Hobbs <[email protected]>

   63. ''Generic Window Operations'' - Jeff Hobbs <[email protected]>

   64. ''Mac Window Operations'' - George B. Smith <[email protected]>, Daniel Steffen <[email protected]>

   65. ''Unix Window Operations'' - Jeff Hobbs <[email protected]>,
				    Joe English <[email protected]>

   66. ''Win Window Operations'' - Jeff Hobbs <[email protected]>, Chengye Mao <[email protected]>

   67. ''Events'' - Jeff Hobbs <[email protected]>

   68. ''Event Loop'' - Jeff Hobbs <[email protected]>, Jan Nijtmans <[email protected]>

   69. ''Error Handling'' - Jeff Hobbs <[email protected]>

   70. ''Atoms'' - Jeff Hobbs <[email protected]>

   71. ''Argv Parsing'' - Jeff Hobbs <[email protected]>

   72. ''Application Embedding'' - Daniel Steffen <[email protected]> (Mac)

   73. ''wish'' - Daniel Steffen <[email protected]> (Mac)

   74. ''Mac DND Tclets'' - Daniel Steffen <[email protected]>

   75. ''Widget Tour'' - Donal K. Fellows <[email protected]>, Jeff Hobbs <[email protected]>

   76. ''Square Demo'' - Jeff Hobbs <[email protected]>

   77. ''Other Demos'' - Donal K. Fellows <[email protected]>, Jeff Hobbs <[email protected]>

   78. ''L10N'' - Jan Nijtmans <[email protected]>, Miguel Ba��n <[email protected]>

   79. ''Release Notes'' - Jeff Hobbs <[email protected]>

   80. ''Portability'' - Jeff Hobbs <[email protected]>

   81. ''X11 Emulation'' - Jeff Hobbs <[email protected]>

   82. ''Mac Build'' - George B. Smith <[email protected]>, Daniel Steffen <[email protected]>

   83. ''Unix Build'' - Jeff Hobbs <[email protected]>,
			Mo DeJong <[email protected]>,
			Lloyd Lim <[email protected]>

   84. ''Win Build'' - Jeff Hobbs <[email protected]>,
			Mo DeJong <[email protected]>

   85. ''Test Tools'' - Allen Flick <[email protected]>, Jeff Hobbs <[email protected]>, Daniel Steffen <[email protected]> (Mac)

   86. ''Logos'' - Jeff Hobbs <[email protected]>

~ General Categories

The  following categories in Tk's SourceForge Tracker do not refer to any
specific portion of Tk.  Reports in these categories should be mapped to
categories corresponding to a maintained area of Tk, when seeking the
appropriate maintainer:

   1. ''Other'' - Reports that span multiple categories.

~ Areas Without Maintainers

Those funcational areas without a maintainer are maintained by the Tcl 
Core Team with each change requiring TYANNOTT review.

~ Copyright

This document has been placed in the public domain.

TIP:            31
Title:          CVS tags in the Tcl and Tk repositories
Version:        $Revision: 1.6 $
Author:         Don Porter <[email protected]>
Author:         miguel sofer <[email protected]>
Author:         Jeff Hobbs <[email protected]>
Author:         Kevin Kenny <[email protected]>
State:          Draft
Type:           Informative
Vote:           Pending
Created:        12-Mar-2001
Post-History:   

~ Abstract

This document keeps a record of the CVS tags used in the Tcl and Tk
repositories and their meanings.

~ Background

CVS uses tags to collectively label a particular set of revisions of a
particular set of files.  With a tag, one may easily request all the
revisions of all the files that correspond to something meaningful,
such as an official release of a project.

There are two kinds of tags provided by CVS.  First is the release tag
that simply marks a set of revisions as belonging together as a unit.
Each release of a project should be tagged with a release tag.  Other
development milestones may also receive a release tag.  Release tags
are useful for marking any point in development that will be useful to
return to or compare against.

The second kind of tag is a branch tag.  It does not mark a single
revision of a file, but an entire branch of development of a file.
Branch tags are the means by which different working directories can
track different branches of development.

A tag may be used in a CVS repository only once, so we must keep track
of what tags have already been used, and what they mean.  The
remaining sections of this TIP record the tags in use.  This TIP
should be kept up to date by adding any new tags here as they are
added to the CVS repository.

~ Release Tags

The following tags in the Tcl and Tk CVS repositories correspond to
the following releases of Tcl/Tk:

   * core-8-3-3 - Tcl/Tk 8.3.3

   * core-8-4-a2 - Tcl/Tk 8.4a2

   * core-8-4-a1 - Tcl/Tk 8.4a1

   * core-8-3-2 - Tcl/Tk 8.3.2

   * core-8-3-1 - Tcl/Tk 8.3.1

   * core-8-3-0 - Tcl/Tk 8.3.0

   * core-8-3-b2 - Tcl/Tk 8.3b2

   * core-8-3-b1 - Tcl/Tk 8.3b1

   * core-8-2-3 - Tcl/Tk 8.2.3

   * core-8-2-2 - Tcl/Tk 8.2.2

   * core-8-2-1 - Tcl/Tk 8.2.1

   * core-8-2-0 - Tcl/Tk 8.2.0

   * core-8-2-b3 - Tcl/Tk 8.2b3

   * core-8-2-b2 - Tcl/Tk 8.2b2

   * core-8-2-b1 - Tcl/Tk 8.2b1

   * core-8-1-1 - Tcl/Tk 8.1.1

   * core-8-1-0 - Tcl/Tk 8.1.0

   * core-8-1-b3 - Tcl/Tk 8.1b3

   * core-8-1-b2 - Tcl/Tk 8.1b2

   * core-8-1-b1 - Tcl/Tk 8.1b1

   * core-8-0-5 - Tcl/Tk 8.0.5

   * core-8-0-4 - Tcl/Tk 8.0.4

   * core-8-0-3 - Tcl/Tk 8.0.3

   * core-8-0-2 - Tcl/Tk 8.0p2

~ Branch Tags - Official Development

The following branch tags label branches of development from which
releases of Tcl/Tk are generated:

   * HEAD - current development of new features; spawns 8.4aX
     releases.

   * core-8-3-1-branch - bug fix branch; spawns 8.3.X releases.

~ Branch Tags - Features

The following branch tags label branches on which features are being
devloped and tested.  No releases of Tcl/Tk will be spawned from these
branches.  As the features mature, they will be merged onto the HEAD
branch, or they may be rejected.

   * core-8-4-win-speedup (Tk) - Work on improving performance of Tk
     on the Windows platforms.

   * kennykb-tip-22-33 (Tcl) - Work on implementing the changes
     described in TIP's #22 and #33.

   * msofer-bcEngine (Tcl) - Work on improving performance of the bytecode engine.

~ Dead Branches

The following branch tags label branches that are no longer being
developed.  Some are old official branches from which releases are no
longer being spawned.  Others are feature development branches that
have been merged into an official branch, or rejected.

   * dgp-privates-into-namespace (Tk) - Work on moving Tk's private
     commands and variables into the ::tk namespace and its children.
     Merged into Tk 8.4a3.

   * core-8-3-1-io-rewrite (Tcl) - Work rewriting Tcl's IO Channels to
     correct problems with the implementation of stacked channels.
     Merged into Tcl 8.3.2 and Tcl 8.4a2.

   * core-8-2-1-branch - Spawned Tcl/Tk 8.2.X releases.

   * core-8-1-branch-old - Spawned Tcl/Tk 8.1bX releases.

   * dev-stubs-branch, dev-8-1-stubs-branch - Two branches on which
     the stubs interfaces were developed.  Merged into Tcl 8.1.

~ Copyright

This document has been placed in the public domain.

TIP:            32
Title:          Add Tcl_Obj support to traces
Version:        $Revision: 1.3 $
Author:         David Cuthbert <[email protected]>
Author:         Kevin Kenny <[email protected]>
State:          Draft
Type:           Project
Vote:           Pending
Created:        23-Mar-2001
Post-History:   
Discussions-To: news:comp.lang.tcl
Keywords:       trace,Tcl_Obj
Tcl-Version:    8.4a2

~ Abstract

This document proposes to add Tcl_Obj support for trace procedures written
in C.

~ Rationale

The ''Tcl_Obj'' system was introduced in version 8.0, making
computations (potentially) much more efficient by eliminating many
type conversions to and from strings.  However, the trace API
continues to require character strings in both command and variable
traces.

~ Specification

Add the following functions to the Tcl core:

 * Tcl_Trace ''Tcl_CreateObjTrace''(interp, level, objProc,
   clientData)

 > ''Tcl_CreateObjTrace'' behaves in the same manner as
   ''Tcl_CreateTrace'', except the trace procedure (objProc) should
   have arguments and result that match type type
   ''Tcl_CmdObjTraceProc'':

|typedef void Tcl_CmdObjTraceProc(
|    ClientData clientData,
|    Tcl_Interp *interp,
|    int level,
|    char *command,
|    Tcl_ObjCmdProc *cmdProc,
|    ClientData cmdClientData,
|    int objc,
|    Tcl_Obj * CONST objv[] );

 > Trace tokens returned by ''Tcl_CreateObjTrace'' can be used in
   ''Tcl_DeleteTrace'' to remove the trace.

 * int ''Tcl_ObjTraceVar2''(interp, part1Ptr, part2Ptr, flags,
   objProc, clientData)

 > ''Tcl_ObjTraceVar2'' behaves in the same manner as
   ''Tcl_TraceVar2'', except the variable name is passed as Tcl_Obj
   pointers (in the same manner as ''Tcl_ObjSetVar2'', q.v.), and the
   trace procedure (objProc) should have arguments and result that
   match the type ''Tcl_VarObjTraceProc'':

|typedef Tcl_Obj *Tcl_VarObjTraceProc(
|    ClientData clientData,
|    Tcl_Interp *interp,
|    Tcl_Obj *part1Ptr,
|    Tcl_Obj *part2Ptr,
|    int flags );

 > Under normal conditions, the trace procedure should return NULL,
   indicating successful completion.  If objProc returns a value other
   than NULL it signifies that an error occurred.  Upon return,
   the reference count of the Tcl_Obj should be at least one;
   ownership of this reference is transferred to the Tcl interpreter.

 * void ''Tcl_ObjUntraceVar2''(interp, part1Ptr, part2Ptr, flags,
   objProc, clientData)

 > ''Tcl_ObjUntraceVar2'' behaves in the same manner as
   ''Tcl_UntraceVar2'', except it is used to remove trace procedures
   registered with ''Tcl_ObjTraceVar2''.

 * ClientData ''Tcl_ObjVarTraceInfo2''(interp, part1Ptr, part2Ptr,
   flags, objProc, prevClientData)

 > ''Tcl_ObjVarTraceInfo2'' behaves in the same manner as
   ''Tcl_VarTraceInfo2'', except it is used to iterate through trace
   procedures registered with ''Tcl_ObjTraceVar2''.

~ Change History

30 March 2001 - Changed return value of objProc to a Tcl_Obj * instead
of int (and using the interpreter result to indicate an error).  This
is more consistent with the current behavior (but without the bug).  -dac

~ See Also

Tcl manual pages ''Tcl_TraceVar'' and ''Tcl_CreateTrace''.

~ Copyright

Copyright � 2000 by David Cuthbert.  Distribution in whole or part,
with or without annotations, is unlimited.

~ Comments

Kevin Kenny (2 April 2001):

This proposal is detailing functionality that I've wanted for
quite some time.  Given, however, that it allows us to make a
partial break with the past, I'd like to make some minor changes
to ''Tcl_CmdObjTraceProc.''

In place of the type signature,

|  typedef void Tcl_CmdObjTraceProc(
|      ClientData clientData,
|      Tcl_Interp *interp,
|      int level,
|      char *command,
|      Tcl_ObjCmdProc *cmdProc,
|      ClientData cmdClientData,
|      int objc,
|      Tcl_Obj * CONST objv[] );

may I suggest that since the interpreter has the ''Command'' structure
in hand, it simply deliver a ''Tcl_Command'' with the command's
information, in place of the command procedure and client data?
Also, the command name is redundant, since the same information
is present in ''objv[ 0 ]''.

The signature would then be:

|  typedef void Tcl_CmdObjTraceProc(
|      ClientData clientData,  /* Client data from Tcl_CreateObjTrace */
|      Tcl_Interp* interp,     /* Tcl interpreter */
|      int level,              /* Execution level */
|      Tcl_Command cmdInfo,    /* Command information */
|      int objc,               /* Parameter count */
|      Tcl_Obj *CONST objv[]   /* Parameter vector */
|  );

This would allow the trace procedure to do interesting things like
replace the command's ''objCmdProc'' and client data temporarily,
before the interpreter uses them.  I have a profiler that works
that way, using the existing API's.  It's awkward at the moment,
because it needs to use ''Tcl_FindCommand'' to get at the command
object (''Tcl_GetCommandInfo'' would also work in current releases,
but I'm in the position of needing bugward compatibility with 8.0).
It also is a horrible performance drain because of the shimmering
that's needed to support tracing currently, and the fact that
tracing defeats the bytecode compiler.

If this change gets approved, and I can get ''TclpGetTime'' exported,
I'll definitely release the profiler.  (I don't care to release code
that depends on tclInt.h, because I don't want to track APIs
that the maintainers don't consider 'stable'.)

By the way, this change should be easier from a political standpoint
than it was a year ago, when any extension that used this mechanism
was presumably a competitor of the TclPro tools.

TIP:            33
Title:          Add 'lset' Command to Assign to List Elements.
Version:        $Revision: 1.11 $
Author:         Kevin Kenny <[email protected]>
State:          Accepted
Type:           Project
Vote:           Done
Created:        15-May-2001
Post-History:   
Discussions-To: news:comp.lang.tcl,mailto:[email protected]
Tcl-Version:    8.4

~ Abstract

Most popular programming languages provide some sort of indexed array
construct, where array subscripts are integers.  Tcl's lists are
implemented internally as indexed arrays, but it is difficult to use
them as such because there is no convenient way to assign to
individual elements.  This TIP proposes a new command, ''lset'', to
rectify this limitation.

~ Rationale

The implementation of lists in Tcl has evolved far beyond the original
conception.  While lists were originally conceived to be strings with
a particular syntax that allowed them to be parsed as lists, the
internal representation of a list is now an array of pointers to
''Tcl_Obj'' structures.

Tcl programmers, for the most part, have not taken advantage of this
evolution.  Code that uses hash tables where linear arrays would be a
more appropriate structure is still extremely common.  Moreover, it is
difficult to update lists in place, even if their internal
representations are known not to be shared.  One example of this
difficulty is seen in the discussions
(http://purl.org/thecliff/tcl/wiki/941)
of how best to shuffle a list of items.  The discussion began with a
na�ve implementation of Jon Bentley's method of performing random
swaps:

|  proc shuffle1 { list } {
|      set n [llength $list]
|      for { set i 0 } { $i < $n } { incr i } {
|          set j [expr {int(rand()*$n)}]
|          set temp [lindex $list $j]
|          set list [lreplace $list $j $j [lindex $list $i]]
|          set list [lreplace $list $i $i $temp]
|      }
|      return $list
|  }

Aside from the fact that the syntax obscures what the program is
doing, the implementation suffers from an obscure performance problem.
When the ''lreplace'' calls in the ''shuffle1'' procedure are
executed, the internal representation of ''list'' has two references:
the value of the variable, and the parameter passed to ''lreplace''.
The multiple references force ''lreplace'' to copy the list, leading
to quadratic performance when large lists are shuffled.

It is possible, albeit difficult, to alleviate this problem by careful
management of the lifetime of ''Tcl_Obj'' structures, but this change
complicates the code.  The simplest way to fix the performance is
probably to use Donal Fellows's implementation of the ''K''
combinator:

| proc K { x y } { set x }

which allows the caller of ''lreplace'' to extract the value of
''list'', change the value of ''list'' so that the extracted value is
unshared, and then pass the extracted value as a parameter to
''lreplace:''

|  proc shuffle1a { list } {
|      set n [llength $list]
|      for { set i 0 } { $i < $n } { incr i } {
|          set j [expr {int(rand()*$n)}]
|          set temp1 [lindex $list $j]
|          set temp2 [lindex $list $i]
|          set list [lreplace [K $list [set list {}]] $j $j $temp2]
|          set list [lreplace [K $list [set list {}]] $i $i $temp1]
|      }
|      return $list
|  }

Now the performance of the code is ''O(n)'' where ''n'' is the length
of the list, but the programmer's intent has been seriously obscured!
Moreover, the performance is still rather poor: Tcl makes an atrocious
showing, for instance, in Doug Bagley's 'Great Computer Language
Shootout' (http://www.bagley.org/~doug/shootout/).

~ Specification

This TIP proposes an 'lset' command with the syntax:

|  lset varName indexList value

or

|  lset varName index1 index2... value

where:

 > ''varName'' is the name of a variable in the caller's scope.

 > If ''objc==4'', then the ''indexList'' parameter is interpreted as
   a list of ''index'' arguments; if ''objc>4'', then the ''index''
   arguments are inline on the command line.

 > In either case, Each ''index'' argument is an index in the content
   of ''varName'' or one of its sublists (see below).  The format of
   ''index'' is either an integer whose value is at least zero and
   less than the length of the corresponding list, or else the literal
   string ''end'', optionally followed with a hyphen and an integer
   whose value is at least zero and less than the length of the
   corresponding list.

 > ''value'' is a value that is to be stored as a list element.

The return value of the command, if successful, is the new value
of ''varName.''

The simplest form of the command:

|  lset varName index value

replaces, in place, the ''index'' element of ''varName'' with the
specified ''value''.  For example, the code:

|  set x {a b c}
|  lset x 1 d

results in ''x'' having the value ''a d c''.  The result, except
for performance considerations and the details of error reporting,
is roughly the same as the Tcl code:

|  proc lset { varName index value } {
|      upvar 1 $varName list
|      set list [lreplace $list $index $index $value]
|      return $list
|  }

except that where the ''lreplace'' command permits indices outside the
existing list elements, the proposed ''lset'' command forbids them.

If multiple ''index'' arguments are supplied to the ''lset'' command,
they refer to successive sublists in a hierarchical fashion.  Thus,

|   lset varName $i $j value

or, equivalently,

|   lset varName [list $i $j] value

asks to change the value of the ''j''th element in the ''i''th sublist
of ''varName''.  Hence, the code:

|   set x {{a b c} {d e f} {g h i}}
|   lset x 1 1 j; # -or- lset x {1 1} j

changes the value of ''x'' to

|   {a b c} {d j f} {g h i}

and the code

|   set y {{{a b} {c d}} {{e f} {g h}}}
|   lset y 1 0 1 i; # -or- lset y {1 0 1} i

changes the value of ''y'' to

|   {{a b} {c d}} {{e i} {g h}}

This notation also dovetails prettily with the extension of the
''lindex'' command proposed in [22].  The command

|   lindex $y 1 0 1; # -or- lindex y {1 0 1}

will extract the element that is set by the command

|   lset $y 1 0 1 $value

The ''lset'' command will throw an error and leave the variable
unchanged if it is presented with fewer than three arguments, if any
of the ''index'' arguments is out of range or ill-formed, or if any of
the data being manipulated cannot be converted to lists.  It will
throw an error after modifying the variable if any write trace on the
variable fails.

With the proposed ''lset'' command, the procedure to shuffle a list
becomes much more straightforward:

|  proc shuffle1b { list } {
|      set n [llength $list]
|      for { set i 0 } { $i < $n } { incr i } {
|          set j [expr {int(rand()*$n)}]
|          set temp [lindex $list $j]
|          lset list $j [lindex $list $i]
|          lset list $i $temp
|      }
|      return $list
|  }

The given implementation copies the list only once, the first time
that the line:

|          lset list $j [lindex $list $i]

is executed.  Thereafter, the list is an unshared object, and the
replacements are performed in place.

~ Reference Implementation

The author has implemented a simpler variant of the proposed command
as an object command, and also proposes to bytecode compile it,
although the implementation of bytecode compilation is incomplete.
The reference implementation also does not yet expand ''objv[[2]]''
as a list in the case where ''objc==4,'' and is known to have memory
leaks where ill-formed index arguments are presented.  It is given
here as ''concept code'' and to present its impact on performance of
some common list operations.  (Obviously, it will be completed and
reviewed with the relevant maintainers prior to being committed to the
Core.)

The core of the implementation is the following procedure:

|int
|Tcl_LsetObjCmd( clientData, interp, objc, objv )
|    ClientData clientData;      /* Not used. */
|    Tcl_Interp *interp;         /* Current interpreter. */
|    int objc;                   /* Number of arguments. */
|    Tcl_Obj *CONST objv[];      /* Argument values. */
|{
|
|    Tcl_Obj* listPtr;           /* Pointer to the list being altered. */
|    Tcl_Obj* subListPtr;        /* Pointer to a sublist of the list */
|    Tcl_Obj* finalValuePtr;     /* Value finally assigned to the variable */
|    int index;                  /* Index of the element being replaced */
|    int result;                 /* Result to return from this function */
|    int listLen;                /* Length of a list being examined */
|    Tcl_Obj** elemPtrs;         /* Pointers to the elements of a
|                                 * list being examined */
|    int i;
|
|    /* Check parameter count */
|
|    if ( objc < 4 ) {
|        Tcl_WrongNumArgs( interp, 1, objv, "listVar index ?index...? value" );
|        return TCL_ERROR;
|    }
|
|    /* Look up the list variable */
|
|    listPtr = Tcl_ObjGetVar2( interp, objv[ 1 ], (Tcl_Obj*) NULL,
|                              TCL_LEAVE_ERR_MSG );
|    if ( listPtr == NULL ) {
|        return TCL_ERROR;
|    }
|
|    /* Make sure that the list value is unshared. */
|
|    if ( Tcl_IsShared( listPtr ) ) {
|        listPtr = Tcl_DuplicateObj( listPtr );
|    }
|
|    finalValuePtr = listPtr;
|
|    /*
|     * If there are multiple 'index' args, handle each arg except the
|     * last by diving into a sublist.
|     */
|
|    for ( i = 2; ; ++i ) {
|
|        /* Take apart the list */
|
|        result = Tcl_ListObjGetElements( interp, listPtr,
|                                         &listLen, &elemPtrs );
|        if ( result != TCL_OK ) {
|            return result;
|        }
|
|        /* Derive the index of the requested sublist */
|
|        result = TclGetIntForIndex( interp, objv[i], (listLen - 1), &index );
|        if ( result != TCL_OK ) {
|            return result;
|        }
|
|        if ( ( index < 0 ) || ( index >= listLen ) ) {
|
|            Tcl_SetObjResult( interp,
|                              Tcl_NewStringObj( "list index out of range",
|                                                -1 ) );
|            return TCL_ERROR;
|        }
|
|        /* Break out of the loop if we've extracted the innermost sublist. */
|
|        if ( i >= ( objc - 2 ) ) {
|            break;
|        }
|
|        /*
|         * Extract the appropriate sublist, and make sure that it is unshared.
|         */
|
|        subListPtr = elemPtrs[ index ];
|        if ( Tcl_IsShared( subListPtr ) ) {
|            subListPtr = Tcl_DuplicateObj( subListPtr );
|            result = Tcl_ListObjSetElement( interp, listPtr, index,
|                                            subListPtr );
|            if ( result != TCL_OK ) {
|                return TCL_ERROR;
|            }
|        } else {
|            Tcl_InvalidateStringRep( listPtr );
|        }
|
|        listPtr = subListPtr;
|    }
|
|    /* Store the result in the list element */
|
|    result = Tcl_ListObjSetElement( interp, listPtr, index, objv[objc-1] );
|    if ( result != TCL_OK ) {
|        return result;
|    }
|
|    /* Finally, update the variable so that traces fire. */
|
|    listPtr = Tcl_ObjSetVar2( interp, objv[1], NULL, finalValuePtr,
|                              TCL_LEAVE_ERR_MSG );
|    if ( listPtr == NULL ) {
|        return TCL_ERROR;
|    }
|       
|    Tcl_SetObjResult( interp, listPtr );
|    return result;
|
|}

The procedure depends on a new service function,
''Tcl_ListObjSetElement'':

|int
|Tcl_ListObjSetElement( interp, listPtr, index, valuePtr )
|    Tcl_Interp* interp;         /* Tcl interpreter; used for error reporting
|                                 * if not NULL */
|    Tcl_Obj* listPtr;           /* List object in which element should be
|                                 * stored */
|    int index;                  /* Index of element to store */
|    Tcl_Obj* valuePtr;          /* Tcl object to store in the designated
|                                 * list element */
|{
|    int result;                 /* Return value from this function */
|    List* listRepPtr;           /* Internal representation of the list
|                                 * being modified */
|    Tcl_Obj** elemPtrs;         /* Pointers to elements of the list */
|    int elemCount;              /* Number of elements in the list */
|
|    /* Ensure that the listPtr parameter designates an unshared list */
|
|    if ( Tcl_IsShared( listPtr ) ) {
|        panic( "Tcl_ListObjSetElement called with shared object" );
|    }
|    if ( listPtr->typePtr != &tclListType ) {
|        result = SetListFromAny( interp, listPtr );
|        if ( result != TCL_OK ) {
|            return result;
|        }
|    }
|    listRepPtr = (List*) listPtr->internalRep.otherValuePtr;
|    elemPtrs = listRepPtr->elements;
|    elemCount = listRepPtr->elemCount;
|
|    /* Ensure that the index is in bounds */
|
|    if ( index < 0 || index >= elemCount ) {
|        if ( interp != NULL ) {
|            Tcl_SetObjResult( interp,
|                              Tcl_NewStringObj( "list index out of range",
|                                                -1 ) );
|            return TCL_ERROR;
|        }
|    }
|
|    /* Add a reference to the new list element */
|
|    Tcl_IncrRefCount( valuePtr );
|
|    /* Remove a reference from the old list element */
|
|    Tcl_DecrRefCount( elemPtrs[ index ] );
|
|    /* Stash the new object in the list */
|
|    elemPtrs[ index ] = valuePtr;
|
|    /* Invalidate and free any old string representation */
|
|    Tcl_InvalidateStringRep( listPtr );
|
|    return TCL_OK;
|    
|}

Even without bytecode compilation, the performance improvement of
array-based applications that can be achieved by the ''lset'' command
is substantial.  The following table shows run times in microseconds
(on a 550 MHz Pentium III laptop, running a modified Tcl 8.4 on
Windows NT 4.0, Service Pack #6) of the three implementations of
''shuffle'' that appear in this TIP.

|                    RUN TIMES IN MICROSECONDS
|
|                                Version
|                     shuffle1       shuffle1a       shuffle1b
|                     (Naive)      (K combinator)  (lset command)
| List length
|        1                 26               32              27            
|       10                108              152             101
|      100               1627             1462             936
|     1000             117831            14789            9574
|    10000       Test stopped           152853           96912

Similar (30-50%) improvements are observed on many of the array
related benchmarks that have been proposed.  Bytecode compilation is
expected to produce even greater improvements.

Another area where ''lset'' can achieve a major performance gain is in
memory usage.  The author of this TIP has benchmarked competing
implementations of heapsort, one using Tcl arrays, and the other using
''lset'' to manipulate lists as linear arrays.  When sorting 80000
elements, the Tcl-array-based implementation used 12.7 megabytes of
memory; the list-based implementation was faster and used only 5.6
megabytes.  The explanation is simple: each entry in the hash table
requires an allocated block of twenty bytes of memory, plus the space
required for the hash key.  The hash key is a string, and requires at
least six bytes.  When both of these objects are aligned and padded
with the overheads imposed by ''ckalloc'', they require about 80 bytes of
memory on the Windows NT platform.  The memory cost of an element of a
Tcl list, by comparison, is four bytes to hold the pointer to the
object.

~ Discussion

There are several objections that can be foreseen to this proposal.

   * ''Why implement the command in the Core and not as an extension?''

   > In a word, ''performance.''  At the present state of Tcl
     development, only Core commands can be bytecoded.  The cost of
     the hash table lookups in the ''Tcl_ObjGetVar2'' and
     ''Tcl_ObjSetVar2'' calls is significant, and can be eliminated
     from many common usages by the bytecode compiler.  Since this
     command is likely to appear in inner loops, it is important to
     squeeze every bit of possible performance out of it.

   * ''Why a new command in the global namespace?''

   > The author of this TIP feels that having a single added command
     that is parallel to the existing list commands is not polluting
     the namespace excessively.  It would be a shame if this proposal
     founders upon the Naming of Names.

   * ''Why a new command, rather than including this functionality in
     the proposed functionality of an extensible command for list
     manipulation?''

   > The author of this TIP has yet to see a formal proposal of any
     extensible list manipulation command; the closest thing appears
     to be Andreas Kupries's ''listx'' package
     (http://www.oche.de/~akupries/tcltk.html).  Given the size and
     complexity of any such modification, it is unlikely that it will
     be available in the Core in time for an 8.4 release.  The
     performance improvements achievable by the ''lset'' command are
     needed urgently.

   * ''Isn't this [29] warmed over?''

   > Several objectors to [29] indicated that they were willing to
     consider list element assignment implemented as a new command.

   * ''Doesn't this proposal depend on multiple ''index'' arguments to
     ''lindex'' ([22])?

   > This proposal can stand alone.  If multiple ''index'' arguments
     to ''lindex'' are also accepted, the resulting symmetry is
     pleasing.  Having multiple ''index'' args to ''lset'' is much
     more important, because it is horribly difficult to implement
     equivalent functionality in pure Tcl without introducing
     excessive calls to ''Tcl_DuplicateObj''.  In fact, the reference
     implementation of ''lset'' presented in this TIP was motivated by
     the fact that its author gave up on the task and resorted to C.

~ Implementation Notes

Having two versions of the syntax for the ''lset'' command is perhaps
unattractive, but neither can be left out effectively.

The syntax where the indices are packaged as a single list allows a
''cursor'' into complex list structure to be maintained in a single
variable.  The list element that the cursor designates can be altered
with a single call to the ''lset'' command, without needing to resort
to ''eval'' (a command that is both expensive and dangerous) to expand
the indices inline.

The syntax where each index is a first-class object is motivated by
the performance of array-based algorithms.  Programmers who are using
lists as arrays know exactly how many subscripts they have, and in
fact are generally iterating through them.  A typical sort of usage
might be the na�ve matrix multiplication shown below.

| # Construct a matrix with 'rows' rows and 'columns' columns
| # having an initial value of 'initCellValue' in each cell.
| 
| proc matrix { rows columns { initCellValue {} } } {
|     set oneRow {}
|     for { set i 0 } { $i < $columns } { incr i } {
|         lappend oneRow $initCellValue
|     }
|     set matrix {}
|     for { set i 0 } { $i < $rows } { incr i } {
|         lappend matrix $oneRow
|     }
|     return $matrix
| }
| 
| # Multiply two matrices
| 
| proc matmult { x y } {
| 
|     set m [llength $x];                 # Number of rows of left matrix
|     set n [llength [lindex $x 0]];      # Number of columns of left matrix
| 
|     if { $n != [llength $y] } {
|         return -code error "rank error: left operand has $n columns\
|                             while right operand has [llength $y] rows"
|     }
| 
|     set k [llength [lindex $y 0]];      # Number of columns of right matrix
| 
|     # Construct a matrix to hold the product
| 
|     set product [matrix $m $k]
| 
|     for { set i 0 } { $i < $m } { incr i } {
|         for { set j 0 } { $j < $k } { incr j } {
|             lset product $i $j 0.0
|             for { set r 0 } { $r < $n } { incr r } {
|                 set term [expr { [lindex $x $i $r] * [lindex $y $r $j] }]
|                 lset product $i $j [expr { [lindex $product $i $j] + $term }]
|             }
|         }
|     }
| 
|     return $product
| }

Note how we have an [[lset]] operation in the innermost loop, executed
(m*n*k) times.

If in this instance, we have to write:

|                 set indices [list $i $j]
|                 lset product $indices \
|                     [expr { [lindex $product $indices] + $term }]

in place of the [[lset]] shown above, we add the cost of forming the
list of indices to the cost of the inner loop.  This cost is not to be
sneezed at -- it's two expensive calls to ''ckalloc.''  (The cost can
be avoided, at some cost in readability, by maintaning a variable
containing the index list, and altering its elements with other uses
of [[lset]].)

Richard Suchenwirth suggested the compromise that appears in this
proposal.  This scheme will perilous to performance if implemented
naively.  If the implementation of [[lset]] simply calls
''Tcl_ListObjGetElements'', look what happens to the inner loop of our
''shuffle1b'' procedure:

|      for { set i 0 } { $i < $n } { incr i } {
|          set j [expr {int(rand()*$n)}]
|          set temp [lindex $list $j]
|          lset list $j [lindex $list $i]
|          lset list $i $temp
|      }

   * Initially, {set i 0} sets i to the constant "0"; it is a string.

   * Evaluating the conditional {$i < $n} will shimmer i to an integer;
     now it's an integer.  (We had to do a call to strtol here.)

   * The [[lindex $list $i]] call now has to consider $i as a list of
     indices, and shimmers it to the list.  This discards the internal
     rep, parses the string rep into a list, and then reconverts its
     first element to an integer.

   * OK, now the 'lset' is happy, and no further shimmering occurs...

   * ... until we get to the {incr i}.  Now we go back to the string rep
     once again, shimmer it to an integer (yet another call to strtol),
     and invalidate the string rep because we've incremented the integer.

   * Now we get back into the [[lindex]] once again, and need a list
     rep.  This time, we have to format the integer as a string, parse
     it as a list, take the object representing element 0, and reparse
     that as an integer.

This sequence has converted the integer to and from a string, and
performed four calls to ''ckalloc'', but resulted in the same integer
that we started with!

It is possible for a sufficiently smart compromise implementation
to avoid all this shimmering.  In the case where ''objc==4'', the
''lset'' command must:

 1. Test whether ''objv[[2]]'' designates an object whose internal
    representation holds an integer.  If so, simply use it as an index.

 2. Test whether ''objv[[2]]'' designates an object whose internal
    representation holds a list.  If so, perform the recursive
    extraction of indexed elements from sublists described above.

 3. Form the string representation of ''objv[[2]]'' and test whether
    it is ''end'' or ''end-'' followed by an integer.  If so, use it
    as an index.

 4. Attempt to coerce ''objv[[2]]'' to an integer; if successful, use
    the result as an integer.

 5. Attempt to coerce ''objv[[2]]'' to a list; if successful, use
    the result as an index list.

 6. Report a malformed ''index'' argument; the ''indexList'' parameter
    is not a well-formed list.

This logic handles all the cases of singleton lists transparently; it
is effectively a simple-minded type inference that optimizes away
needless conversions.  With it in place, none of the ''lset'' examples
shown in this TIP will suffer from type shimmering.

In the event that the related [22] is approved, the logic for parsing
an index list will likely be combined with that used in the ''lindex''
command.

Bytecoding variadic commands like ''lset'' presents some interesting
technical challenges; a discussion in progress on the Tcl'ers Wiki
(http://purl.org/thecliff/tcl/wiki/1604) is recording the design
decisions being made for bytecoding ''lset'' so that they can be
applied to similar commands in the future.

~ See Also

[22], [29].

~ Change History

This TIP has undergone several revisions by the original author.
The most significant was made on 20 May 2001, where the syntax was
revised to allow for either several indices inline on the command line
or a list of indices.

~ Copyright

This document has been placed in the public domain.