Doc changes for the big Tkinter rename.

7 files changed, 156 insertions, 92 deletions

diff --git a/Doc/library/idle.rst b/Doc/library/idle.rst
index 8209aa9..7a5bebd 100644
--- a/Doc/library/idle.rst
+++ b/Doc/library/idle.rst
@@ -10,11 +10,11 @@ IDLE
    single: Python Editor
    single: Integrated Development Environment
 
-IDLE is the Python IDE built with the :mod:`Tkinter` GUI toolkit.
+IDLE is the Python IDE built with the :mod:`tkinter` GUI toolkit.
 
 IDLE has the following features:
 
-* coded in 100% pure Python, using the :mod:`Tkinter` GUI toolkit
+* coded in 100% pure Python, using the :mod:`tkinter` GUI toolkit
 
 * cross-platform: works on Windows and Unix (on Mac OS, there are currently
   problems with Tcl/Tk)
diff --git a/Doc/library/othergui.rst b/Doc/library/othergui.rst
index 2d4ea37..d2fad3e 100644
--- a/Doc/library/othergui.rst
+++ b/Doc/library/othergui.rst
@@ -3,13 +3,13 @@
 Other Graphical User Interface Packages
 =======================================
 
-There are an number of extension widget sets to :mod:`Tkinter`.
+There are an number of extension widget sets to :mod:`tkinter`.
 
 .. seealso::
 
    `Python megawidgets <http://pmw.sourceforge.net/>`_
       is a toolkit for building high-level compound widgets in Python using the
-      :mod:`Tkinter` module.  It consists of a set of base classes and a library of
+      :mod:`tkinter` package.  It consists of a set of base classes and a library of
       flexible and extensible megawidgets built on this foundation. These megawidgets
       include notebooks, comboboxes, selection widgets, paned widgets, scrolled
       widgets, dialog windows, etc.  Also, with the Pmw.Blt interface to BLT, the
diff --git a/Doc/library/tk.rst b/Doc/library/tk.rst
index 944687b..56f5265 100644
--- a/Doc/library/tk.rst
+++ b/Doc/library/tk.rst
@@ -12,19 +12,20 @@ Graphical User Interfaces with Tk
 
 Tk/Tcl has long been an integral part of Python.  It provides a robust and
 platform independent windowing toolkit, that is available to Python programmers
-using the :mod:`Tkinter` module, and its extension, the :mod:`Tix` module.
+using the :mod:`tkinter` package, and its extension, the :mod:`tkinter.tix` 
+module.
 
-The :mod:`Tkinter` module is a thin object-oriented layer on top of Tcl/Tk. To
-use :mod:`Tkinter`, you don't need to write Tcl code, but you will need to
+The :mod:`tkinter` package is a thin object-oriented layer on top of Tcl/Tk. To
+use :mod:`tkinter`, you don't need to write Tcl code, but you will need to
 consult the Tk documentation, and occasionally the Tcl documentation.
-:mod:`Tkinter` is a set of wrappers that implement the Tk widgets as Python
+:mod:`tkinter` is a set of wrappers that implement the Tk widgets as Python
 classes.  In addition, the internal module :mod:`_tkinter` provides a threadsafe
 mechanism which allows Python and Tcl to interact.
 
-:mod:`Tkinter`'s chief virtues are that it is fast, and that it usually comes
+:mod:`tkinter`'s chief virtues are that it is fast, and that it usually comes
 bundled with Python. Although its standard documentation is weak, good 
 material is available, which includes: references, tutorials, a book and 
-others. :mod:`Tkinter` is also famous for having an outdated look and feel, 
+others. :mod:`tkinter` is also famous for having an outdated look and feel, 
 which has been vastly improved in Tk 8.5. Nevertheless, there are many other 
 GUI libraries that you could be interested in. For more information about 
 alternatives, see the :ref:`other-gui-packages` section.
@@ -32,9 +33,9 @@ alternatives, see the :ref:`other-gui-packages` section.
 .. toctree::
    
    tkinter.rst
-   tix.rst
-   scrolledtext.rst
-   turtle.rst
+   tkinter.tix.rst
+   tkinter.scrolledtext.rst
+   tkinter.turtle.rst
    idle.rst
    othergui.rst
 
diff --git a/Doc/library/tkinter.rst b/Doc/library/tkinter.rst
index d393341..3bc1c69 100644
--- a/Doc/library/tkinter.rst
+++ b/Doc/library/tkinter.rst
@@ -1,16 +1,26 @@
-:mod:`Tkinter` --- Python interface to Tcl/Tk
+:mod:`tkinter` --- Python interface to Tcl/Tk
 =============================================
 
 .. module:: Tkinter
+   :synopsis: Old name for the tkinter module.
+
+.. module:: tkinter
    :synopsis: Interface to Tcl/Tk for graphical user interfaces
 .. moduleauthor:: Guido van Rossum <guido@Python.org>
 
 
-The :mod:`Tkinter` module ("Tk interface") is the standard Python interface to
-the Tk GUI toolkit.  Both Tk and :mod:`Tkinter` are available on most Unix
+The :mod:`tkinter` package ("Tk interface") is the standard Python interface to
+the Tk GUI toolkit.  Both Tk and :mod:`tkinter` are available on most Unix
 platforms, as well as on Windows and Macintosh systems.  (Tk itself is not part
 of Python; it is maintained at ActiveState.)
 
+.. note::
+   The :mod:`Tkinter` module has been renamed to a :mod:`tkinter` package in
+   Python 3.0.  All other Tkinter-related modules have been moved to submodules
+   within that package (see their individual descriptions).
+
+   All modules are importable under both names in Python 2.6 and the rest of the
+   2.x series.
 
 .. seealso::
 
@@ -34,23 +44,23 @@ of Python; it is maintained at ActiveState.)
 Tkinter Modules
 ---------------
 
-Most of the time, the :mod:`Tkinter` module is all you really need, but a number
+Most of the time, the :mod:`tkinter` is all you really need, but a number
 of additional modules are available as well.  The Tk interface is located in a
 binary module named :mod:`_tkinter`. This module contains the low-level
 interface to Tk, and should never be used directly by application programmers.
 It is usually a shared library (or DLL), but might in some cases be statically
 linked with the Python interpreter.
 
-In addition to the Tk interface module, :mod:`Tkinter` includes a number of
-Python modules. The two most important modules are the :mod:`Tkinter` module
-itself, and a module called :mod:`Tkconstants`. The former automatically imports
-the latter, so to use Tkinter, all you need to do is to import one module::
+In addition to the Tk interface module, :mod:`tkinter` includes a number of
+Python modules, :mod:`tkinter.constants` being one of the most important. 
+Importing :mod:`tkinter` will automatically import :mod:`tkinter.constants`,
+so, usually, to use Tkinter all you need is a simple import statement::
 
-   import Tkinter
+   import tkinter
 
 Or, more often::
 
-   from Tkinter import *
+   from tkinter import *
 
 
 .. class:: Tk(screenName=None, baseName=None, className='Tk', useTk=1)
@@ -79,41 +89,67 @@ Or, more often::
 
 Other modules that provide Tk support include:
 
-:mod:`ScrolledText`
+:mod:`tkinter.scrolledtext`
    Text widget with a vertical scroll bar built in.
 
-:mod:`tkColorChooser`
+   .. versionchanged:: 2.6
+      Renamed from ``ScrolledText``.
+
+:mod:`tkinter.colorchooser`
    Dialog to let the user choose a color.
 
-:mod:`tkCommonDialog`
+   .. versionchanged:: 2.6
+      Renamed from ``tkColorChooser``.
+
+:mod:`commondialog`
    Base class for the dialogs defined in the other modules listed here.
 
-:mod:`tkFileDialog`
+   .. versionchanged:: 2.6
+      Renamed from ``tkCommonDialog``.
+
+:mod:`filedialog`
    Common dialogs to allow the user to specify a file to open or save.
 
-:mod:`tkFont`
+   .. versionchanged:: 2.6
+      Renamed from ``tkFileDialog``.
+
+:mod:`tkinter.font`
    Utilities to help work with fonts.
 
-:mod:`tkMessageBox`
+   .. versionchanged:: 2.6
+      Renamed from ``tkFont``.
+
+:mod:`tkinter.messagebox`
    Access to standard Tk dialog boxes.
 
-:mod:`tkSimpleDialog`
+   .. versionchanged:: 2.6
+      Renamed from ``tkMessageBox``.
+
+:mod:`tkinter.simpledialog`
    Basic dialogs and convenience functions.
 
-:mod:`Tkdnd`
-   Drag-and-drop support for :mod:`Tkinter`. This is experimental and should become
-   deprecated when it is replaced  with the Tk DND.
+   .. versionchanged:: 2.6
+      Renamed from ``tkSimpleDialog``.
+
+:mod:`tkinter.dnd`
+   Drag-and-drop support for :mod:`tkinter`. This is experimental and should 
+   become deprecated when it is replaced  with the Tk DND.
 
-:mod:`turtle`
+   .. versionchanged:: 2.6
+      Renamed from ``Tkdnd``.
+
+:mod:`tkinter.turtle`
    Turtle graphics in a Tk window.
 
+   .. versionchanged:: 2.6
+      Renamed from ``turtle``.
+
 
 Tkinter Life Preserver
 ----------------------
 
 .. sectionauthor:: Matt Conway
 
-
 This section is not designed to be an exhaustive tutorial on either Tk or
 Tkinter.  Rather, it is intended as a stop gap, providing some introductory
 orientation on the system.
@@ -145,7 +181,7 @@ handy reference.
 
 When trying to answer questions of the form "how do I do blah", it is often best
 to find out how to do"blah" in straight Tk, and then convert this back into the
-corresponding :mod:`Tkinter` call. Python programmers can often guess at the
+corresponding :mod:`tkinter` call. Python programmers can often guess at the
 correct Python command by looking at the Tk documentation. This means that in
 order to use Tkinter, you will have to know a little bit about Tk. This document
 can't fulfill that role, so the best we can do is point you to the best
@@ -161,8 +197,8 @@ documentation that exists. Here are some hints:
   the novice.  The book is not exhaustive, and for many details it defers to the
   man pages.
 
-* :file:`Tkinter.py` is a last resort for most, but can be a good place to go
-  when nothing else makes sense.
+* :file:`tkinter/__init__.py` is a last resort for most, but can be a good 
+  place to go when nothing else makes sense.
 
 
 .. seealso::
@@ -182,7 +218,7 @@ A Simple Hello World Program
 
 ::
 
-   from Tkinter import *
+   from tkinter import *
 
    class Application(Frame):
        def say_hi(self):
@@ -236,7 +272,7 @@ Notes:
 To make use of this reference material, there will be times when you will need
 to know how to read short passages of Tk and how to identify the various parts
 of a Tk command.   (See section :ref:`tkinter-basic-mapping` for the
-:mod:`Tkinter` equivalents of what's below.)
+:mod:`tkinter` equivalents of what's below.)
 
 Tk scripts are Tcl programs.  Like all Tcl programs, Tk scripts are just lists
 of tokens separated by spaces.  A Tk widget is just its *class*, the *options*
@@ -324,9 +360,9 @@ module. ::
 To give a widget to the packer (geometry manager), you call pack with optional
 arguments.  In Tkinter, the Pack class holds all this functionality, and the
 various forms of the pack command are implemented as methods.  All widgets in
-:mod:`Tkinter` are subclassed from the Packer, and so inherit all the packing
-methods. See the :mod:`Tix` module documentation for additional information on
-the Form geometry manager. ::
+:mod:`tkinter` are subclassed from the Packer, and so inherit all the packing
+methods. See the :mod:`tkinter.tix` module documentation for additional 
+information on the Form geometry manager. ::
 
    pack .fred -side left       =====>  fred.pack(side = "left")
 
@@ -337,11 +373,11 @@ How Tk and Tkinter are Related
 From the top down:
 
 Your App Here (Python)
-   A Python application makes a :mod:`Tkinter` call.
+   A Python application makes a :mod:`tkinter` call.
 
-Tkinter (Python Module)
+tkinter (Python Package)
    This call (say, for example, creating a button widget), is implemented in the
-   *Tkinter* module, which is written in Python.  This Python function will parse
+   *tkinter* package, which is written in Python.  This Python function will parse
    the commands and the arguments and convert them into a form that makes them look
    as if they had come from a Tk script instead of a Python script.
 
@@ -353,8 +389,8 @@ Tk Widgets (C and Tcl)
    This C function is able to make calls into other C modules, including the C
    functions that make up the Tk library.  Tk is implemented in C and some Tcl.
    The Tcl part of the Tk widgets is used to bind certain default behaviors to
-   widgets, and is executed once at the point where the Python :mod:`Tkinter`
-   module is imported. (The user never sees this stage).
+   widgets, and is executed once at the point where the Python :mod:`tkinter`
+   package is imported. (The user never sees this stage).
 
 Tk (C)
    The Tk part of the Tk Widgets implement the final mapping to ...
@@ -510,11 +546,11 @@ options are ``variable``, ``textvariable``, ``onvalue``, ``offvalue``, and
 ``value``.  This connection works both ways: if the variable changes for any
 reason, the widget it's connected to will be updated to reflect the new value.
 
-Unfortunately, in the current implementation of :mod:`Tkinter` it is not
+Unfortunately, in the current implementation of :mod:`tkinter` it is not
 possible to hand over an arbitrary Python variable to a widget through a
 ``variable`` or ``textvariable`` option.  The only kinds of variables for which
 this works are variables that are subclassed from a class called Variable,
-defined in the :mod:`Tkinter` module.
+defined in the :mod:`tkinter`.
 
 There are many useful subclasses of Variable already defined:
 :class:`StringVar`, :class:`IntVar`, :class:`DoubleVar`, and
@@ -558,7 +594,7 @@ The Window Manager
 
 In Tk, there is a utility command, ``wm``, for interacting with the window
 manager.  Options to the ``wm`` command allow you to control things like titles,
-placement, icon bitmaps, and the like.  In :mod:`Tkinter`, these commands have
+placement, icon bitmaps, and the like.  In :mod:`tkinter`, these commands have
 been implemented as methods on the :class:`Wm` class.  Toplevel widgets are
 subclassed from the :class:`Wm` class, and so can call the :class:`Wm` methods
 directly.
@@ -572,7 +608,7 @@ part of the implementation, and not an interface to Tk functionality.
 
 Here are some examples of typical usage::
 
-   from Tkinter import *
+   from tkinter import *
    class App(Frame):
        def __init__(self, master=None):
            Frame.__init__(self, master)
@@ -733,7 +769,7 @@ Entry widget, or to particular menu items in a Menu widget.
 
 Entry widget indexes (index, view index, etc.)
    Entry widgets have options that refer to character positions in the text being
-   displayed.  You can use these :mod:`Tkinter` functions to access these special
+   displayed.  You can use these :mod:`tkinter` functions to access these special
    points in text widgets:
 
    AtEnd()
@@ -785,7 +821,7 @@ Images
 ^^^^^^
 
 Bitmap/Pixelmap images can be created through the subclasses of
-:class:`Tkinter.Image`:
+:class:`tkinter.Image`:
 
 * :class:`BitmapImage` can be used for X11 bitmap data.
 
diff --git a/Doc/library/scrolledtext.rst b/Doc/library/tkinter.scrolledtext.rst
index 85456b9..1c5d761 100644
--- a/Doc/library/scrolledtext.rst
+++ b/Doc/library/tkinter.scrolledtext.rst
@@ -1,17 +1,27 @@
-:mod:`ScrolledText` --- Scrolled Text Widget
-============================================
+:mod:`tkinter.scrolledtext` --- Scrolled Text Widget
+====================================================
 
 .. module:: ScrolledText
+   :synopsis: Old name for the tkinter.scrolledtext module.
+
+.. module:: tkinter.scrolledtext
    :platform: Tk
    :synopsis: Text widget with a vertical scroll bar.
 .. sectionauthor:: Fred L. Drake, Jr. <fdrake@acm.org>
 
+.. note::
+   The :mod:`ScrolledText` module has been renamed to
+   :mod:`tkinter.scrolledtext` in Python 3.0.  It is importable under both names
+   in Python 2.6 and the rest of the 2.x series.
 
-The :mod:`ScrolledText` module provides a class of the same name which
+The :mod:`tkinter.scrolledtext` module provides a class of the same name which
 implements a basic text widget which has a vertical scroll bar configured to do
 the "right thing."  Using the :class:`ScrolledText` class is a lot easier than
 setting up a text widget and scroll bar directly.  The constructor is the same
-as that of the :class:`Tkinter.Text` class.
+as that of the :class:`tkinter.Text` class.
+
+.. versionchanged:: 2.6
+   Renamed from ``ScrolledText``.
 
 The text widget and scrollbar are packed together in a :class:`Frame`, and the
 methods of the :class:`Grid` and :class:`Pack` geometry managers are acquired
diff --git a/Doc/library/tix.rst b/Doc/library/tkinter.tix.rst
index ff2cfff..7ca9ff8 100644
--- a/Doc/library/tix.rst
+++ b/Doc/library/tkinter.tix.rst
@@ -1,20 +1,28 @@
-:mod:`Tix` --- Extension widgets for Tk
-=======================================
+:mod:`tkinter.tix` --- Extension widgets for Tk
+===============================================
 
 .. module:: Tix
+   :synopsis: Old name for the tkinter.tix module.
+
+.. module:: tkinter.tix
    :synopsis: Tk Extension Widgets for Tkinter
 .. sectionauthor:: Mike Clarkson <mikeclarkson@users.sourceforge.net>
 
+.. note::
+   The :mod:`Tix` module has been renamed to :mod:`tkinter.tix` in Python 3.0.
+   It is importable under both names in Python 2.6 and the rest of the 2.x
+   series.
 
 .. index:: single: Tix
 
-The :mod:`Tix` (Tk Interface Extension) module provides an additional rich set
-of widgets. Although the standard Tk library has many useful widgets, they are
-far from complete. The :mod:`Tix` library provides most of the commonly needed
-widgets that are missing from standard Tk: :class:`HList`, :class:`ComboBox`,
-:class:`Control` (a.k.a. SpinBox) and an assortment of scrollable widgets.
-:mod:`Tix` also includes many more widgets that are generally useful in a wide
-range of applications: :class:`NoteBook`, :class:`FileEntry`,
+The :mod:`tkinter.tix` (Tk Interface Extension) module provides an additional 
+rich set of widgets. Although the standard Tk library has many useful widgets, 
+they are far from complete. The :mod:`tkinter.tix` library provides most of the
+commonly needed widgets that are missing from standard Tk: :class:`HList`, 
+:class:`ComboBox`, :class:`Control` (a.k.a. SpinBox) and an assortment of 
+scrollable widgets. 
+:mod:`tkinter.tix` also includes many more widgets that are generally useful in
+a wide range of applications: :class:`NoteBook`, :class:`FileEntry`,
 :class:`PanedWindow`, etc; there are more than 40 of them.
 
 With all these new widgets, you can introduce new interaction techniques into
@@ -22,7 +30,6 @@ applications, creating more useful and more intuitive user interfaces. You can
 design your application by choosing the most appropriate widgets to match the
 special needs of your application and users.
 
-
 .. seealso::
 
    `Tix Homepage <http://tix.sourceforge.net/>`_
@@ -50,27 +57,27 @@ Using Tix
    Toplevel widget of Tix which represents mostly the main window of an
    application. It has an associated Tcl interpreter.
 
-   Classes in the :mod:`Tix` module subclasses the classes in the :mod:`Tkinter`
-   module. The former imports the latter, so to use :mod:`Tix` with Tkinter, all
-   you need to do is to import one module. In general, you can just import
-   :mod:`Tix`, and replace the toplevel call to :class:`Tkinter.Tk` with
-   :class:`Tix.Tk`::
+   Classes in the :mod:`tkinter.tix` module subclasses the classes in the 
+   :mod:`tkinter`. The former imports the latter, so to use :mod:`tkinter.tix` 
+   with Tkinter, all you need to do is to import one module. In general, you 
+   can just import :mod:`tkinter.tix`, and replace the toplevel call to 
+   :class:`tkinter.Tk` with :class:`tix.Tk`::
 
-      import Tix
-      from Tkconstants import *
-      root = Tix.Tk()
+      from tkinter import tix
+      from tkinter.constants import *
+      root = tix.Tk()
 
-To use :mod:`Tix`, you must have the :mod:`Tix` widgets installed, usually
+To use :mod:`tkinter.tix`, you must have the Tix widgets installed, usually
 alongside your installation of the Tk widgets. To test your installation, try
 the following::
 
-   import Tix
-   root = Tix.Tk()
+   from tkinter import tix
+   root = tix.Tk()
    root.tk.eval('package require Tix')
 
 If this fails, you have a Tk installation problem which must be resolved before
 proceeding. Use the environment variable :envvar:`TIX_LIBRARY` to point to the
-installed :mod:`Tix` library directory, and make sure you have the dynamic
+installed Tix library directory, and make sure you have the dynamic
 object library (:file:`tix8183.dll` or :file:`libtix8183.so`) in  the same
 directory that contains your Tk dynamic object library (:file:`tk8183.dll` or
 :file:`libtk8183.so`). The directory with the dynamic object library should also
@@ -85,8 +92,8 @@ Tix Widgets
 
 `Tix <http://tix.sourceforge.net/dist/current/man/html/TixCmd/TixIntro.htm>`_
 introduces over 40 widget classes to the :mod:`Tkinter`  repertoire.  There is a
-demo of all the :mod:`Tix` widgets in the :file:`Demo/tix` directory of the
-standard distribution.
+demo of all the :mod:`tkinter.tix` widgets in the :file:`Demo/tix` directory of
+the standard distribution.
 
 .. The Python sample code is still being added to Python, hence commented out
 
@@ -434,11 +441,11 @@ Manager Widgets
 Image Types
 ^^^^^^^^^^^
 
-The :mod:`Tix` module adds:
+The :mod:`tkinter.tix` module adds:
 
 * `pixmap <http://tix.sourceforge.net/dist/current/man/html/TixCmd/pixmap.htm>`_
-  capabilities to all :mod:`Tix` and :mod:`Tkinter` widgets to create color images
-  from XPM files.
+  capabilities to all :mod:`tkinter.tix` and :mod:`tkinter` widgets to create 
+  color images from XPM files.
 
   .. Python Demo of:
   .. \ulink{XPM Image In Button}{http://tix.sourceforge.net/dist/current/demos/samples/Xpm.tcl}
@@ -478,7 +485,7 @@ Miscellaneous Widgets
 Form Geometry Manager
 ^^^^^^^^^^^^^^^^^^^^^
 
-In addition, :mod:`Tix` augments :mod:`Tkinter` by providing:
+In addition, :mod:`tkinter.tix` augments :mod:`tkinter` by providing:
 
 
 .. class:: Form()
diff --git a/Doc/library/turtle.rst b/Doc/library/tkinter.turtle.rst
index 30cb729..1666555 100644
--- a/Doc/library/turtle.rst
+++ b/Doc/library/tkinter.turtle.rst
@@ -1,24 +1,34 @@
-
-:mod:`turtle` --- Turtle graphics for Tk
-========================================
+:mod:`tkinter.turtle` --- Turtle graphics for Tk
+================================================
 
 .. module:: turtle
+   :synopsis: Old name for the tkinter.turtle module.
+
+.. module:: tkinter.turtle
    :platform: Tk
    :synopsis: An environment for turtle graphics.
 .. moduleauthor:: Guido van Rossum <guido@python.org>
 
+.. note::
+   The :mod:`turtle` module has been renamed to :mod:`tkinter.turtle` in Python
+   3.0.  It is importable under both names in Python 2.6 and the rest of the 2.x
+   series.
+
 
 .. sectionauthor:: Moshe Zadka <moshez@zadka.site.co.il>
 
 
-The :mod:`turtle` module provides turtle graphics primitives, in both an
-object-oriented and procedure-oriented ways. Because it uses :mod:`Tkinter` for
+The :mod:`tkinter.turtle` module provides turtle graphics primitives, in both an
+object-oriented and procedure-oriented ways. Because it uses :mod:`tkinter` for
 the underlying graphics, it needs a version of python installed with Tk support.
 
+.. versionchanged:: 2.6
+   Renamed from ``turtle``.
+
 The procedural interface uses a pen and a canvas which are automagically created
 when any of the functions are called.
 
-The :mod:`turtle` module defines the following functions:
+The :mod:`tkinter.turtle` module defines the following functions:
 
 
 .. function:: degrees()