small rewording/reorganization of architecture and modules sections

Author: roseman

Doc/library/tkinter.rst

@@ -12,7 +12,7 @@
 
 The :mod:`tkinter` package ("Tk interface") is the standard Python interface to
 the Tcl/Tk GUI toolkit. Tcl/Tk and :mod:`tkinter` are available on most Unix
-platforms, as well as on Windows systems.
+platforms (including macOS), as well as on Windows systems.
 
 Running ``python -m tkinter`` from the command line should open a window
 demonstrating a simple Tk interface, letting you know that :mod:`tkinter` is
@@ -24,68 +24,62 @@ without thread support. The official Python binary release bundles Tcl/Tk 8.6
 threaded. See the source code for the :mode:`_tkinter` module
 for more information about supported versions.
 
-Tkinter is not a thin wrapper, it adds a fair amount of own logic to
-make the experience more pythonic. This documentation will concentrate on this
-added and changed logic and refer to the official Tcl/Tk documentation for
-details that are unchanged.
+Tkinter is not a thin wrapper, but adds a fair amount of its own logic to
+make the experience more pythonic. This documentation will concentrate on these
+additions and changes, and refer to the official Tcl/Tk documentation for
+descriptions of underlying features.
 
 
 Architecture
 ------------
 
-Unlike most other GUI toolkits, Tcl/Tk is not a monolithic product providing a
-consolidated API. Instead, it's a bundle of libraries, each with its
-distinct functionality and separate documentation.
+Tkinter provides a unified interface to several separate and distinct libraries.
 
 Tcl
-   Tcl is a dynamic interpreted programming language. Though it can be used
-   as a general-purpose programming language, it's primary developed to be and
-   used as an embedded scripting engine for applications (same as Lua) and as
-   an interface to the Tk toolkit. The Tcl engine library has a C interface to
-   create and operate interpreter instances, run Tcl commands and scripts with
-   them and add custom commands that can be implemented in either Tcl or C.
-   It also implements a per-thread event queue (see `Threading model`_ for
-   details).
-   Each :class:`Tk` object embeds its own interpreter instance.
-   Though :mod:`_tkinter` allows to execute entire Tcl scripts, the Python
-   bindings typically only run single commands.
+   Like Python, Tcl is a dynamic interpreted programming language. It is most
+   commonly used by C applications to embed a scripting language, or as an
+   interface to the Tk toolkit. The Tcl library has a C interface to
+   create and manage one or more instances of a Tcl interpreter, run Tcl
+   commands and scripts in those instances, and add custom commands
+   implemented in either Tcl or C. Each interpreter instance also provides
+   an event queue, used for I/O, timers, and by modules.
 
 Tk
-   Tk is a Tcl module implemented in C that adds custom commands to create and
-   manipulate GUI widgets. The interpreter's event queue is used to generate
-   and process events for all widgets created by it.
-   Tcl can be used without Tk (and Tk needs to be explicitly loaded to make it
-   available; :mod:`tkinter` does this automatically), though they are
-   typically provided together, "Tcl/Tk" being the name for the bundle.
-   Tk also implements the Themed Tk (Ttk) family of widgets, though `tkinter`
-   provides Python bindings for them in a separate module, :mod:`tkinter.ttk`.
-   Tk has its own C interface that duplicates the custom Tcl commands though
-   `tkinter` mostly uses the latter.
+   Tk is a module that can be loaded into a Tcl interpreter instance. It adds
+   Tcl commands (implemented in C) to create and manipulate GUI widgets. Each
+   :class:`Tk` object embeds its own Tcl interpreter instance with Tk loaded into
+   it. Tk's widgets are very customizable, though at the cost of a dated appearance.
+   Tk uses the interpreter's event queue to generate and process GUI events. Note
+   that unlike some GUI libraries, each interpreter uses only a single thread,
+   which has implications for :mod:`tkinter` users (see `Threading model`_).
+
+Ttk
+   Themed Tk (Ttk) is a newer family of Tk widgets that provide a much better
+   appearance on different platforms than many of the classic Tk widgets.
+   Ttk is distributed as part of Tk, starting with Tk version 8.5. Python
+   bindings are provided in a separate module, :mod:`tkinter.ttk`.
 
 Tix
-   `Tix`<https://core.tcl.tk/jenglish/gutter/packages/tix.html>_ is a
-   third-party Tcl module, an addon for Tk that adds several new widgets.
-   `tkinter.tix` provides bindings for it, and official Python binary releases
-   come with it bundled. It's deprecated in favor of Ttk.
+   `Tix`<https://core.tcl.tk/jenglish/gutter/packages/tix.html>_ is an older
+   third-party Tcl module, adding several new widgets to Tk. Python bindings
+   are found in :mod:`tkinter.tix`. It has been deprecated in favor of Ttk.
 
 
 Tkinter Modules
 ^^^^^^^^^^^^^^^
 
-:mod:`tkinter` has the core functionality and the bindings for regular Tk
-widgets. Unless you're using the additional widgets, this will be all
-that you really need.
+Most applications will directly use the features provided by :mod:`tkinter`.
+Unless compatibility with very old versions of Tcl/Tk is required, Ttk widgets
+found in :mod:`tkinter.ttk` should also be favoured over their classic Tk
+counterparts.
 
-:mod:`tkinter.ttk` and :mod:`tkinter.tix` have classes for extra
-widgets from those families. Ttk is intended to be the new standard widget
-set with a more modern look, but as of this writing, it doesn't yet have
-replacements for all the classical widgets. 
+The :mod:`_tkinter` module provides low-level access to Tcl interpreters in Python,
+using the C interface to the Tcl library. It should rarely be used directly by
+application programmers. It may be needed to access features in very new versions
+of Tcl/Tk without an existing Python binding, though this reduces compatibility.
+It is usually a shared library (or DLL) but may be statically linked with the
+Python interpreter.
 
-The core Tcl/Tk interface is located in a C module named :mod:`_tkinter`.
-This module directly interfaces with Tcl/Tk via their C interfaces and
-shouldn't be used directly by application programmers save for a few functions.
-It is usually a shared library (or DLL), but might in some cases be statically
-linked with the Python interpreter.
 
 
 Threading model