From 7ac38813096336dbd1a18f8a1c48c102b8a7408d Mon Sep 17 00:00:00 2001
From: Karl Lehenbauer <karl@flightaware.com>
Date: Thu, 9 Sep 2021 12:47:01 -0500
Subject: [PATCH] update docs for 4.2 release

---
 Doc/reference/tohil_python_functions.rst |  6 ++
 Doc/tools/templates/indexcontent.html    |  2 +-
 Doc/whatsnew/4.2.rst                     | 70 ++++++++++++++++++++++++
 Doc/whatsnew/index.rst                   |  1 +
 4 files changed, 78 insertions(+), 1 deletion(-)
 create mode 100644 Doc/whatsnew/4.2.rst

diff --git a/Doc/reference/tohil_python_functions.rst b/Doc/reference/tohil_python_functions.rst
index 442d51e..acc7dbd 100644
--- a/Doc/reference/tohil_python_functions.rst
+++ b/Doc/reference/tohil_python_functions.rst
@@ -8,6 +8,12 @@ Tohil Python Functions
 Tohil has a number of functions and data types that it provides
 when the tohil package has been imported.
 
+.. function:: tohil.alias(name, callback)
+
+   Identical to `register_callback` and under consideration to replace it
+   as the command used to alias Tcl commands to Python commands, although
+   backwards compatibility would be maintained.
+
 .. function:: tohil.call(* args[, to=type])
 
    Invoke a Tcl command while specifying each argument explicitly,
diff --git a/Doc/tools/templates/indexcontent.html b/Doc/tools/templates/indexcontent.html
index 6a3aed1..ded1ece 100644
--- a/Doc/tools/templates/indexcontent.html
+++ b/Doc/tools/templates/indexcontent.html
@@ -5,7 +5,7 @@
 {% block body %}
   <h1>{{ docstitle|e }}</h1>
   <p>
-  {% trans %}Welcome! This is the documentation for Tohil {{ release }}. Tohil, a feathered serpent, joins Python and Tcl at the hip.{% endtrans %}
+  {% trans %}Welcome! This is the documentation for Tohil {{ release }}. Tohil, a feathered serpent, powerfully joins Python and Tcl.{% endtrans %}
   </p>
   <img src="_images/tohil-237px.png" width="247" height="240" alt="Tohil graphic">
   <p><strong>{% trans %}Parts of the documentation:{% endtrans %}</strong></p>
diff --git a/Doc/whatsnew/4.2.rst b/Doc/whatsnew/4.2.rst
new file mode 100644
index 0000000..b82b46d
--- /dev/null
+++ b/Doc/whatsnew/4.2.rst
@@ -0,0 +1,70 @@
+
+.. 4.2.rst:
+
+****************************
+  What's New In Tohil 4.2
+****************************
+
+Welcome to Tohil 4.2.
+
+4.2 is primarily a maintenance release, but includes at least one really
+nice new feature:
+
+===================================================================================
+Python code passed to tohil::exec is now unindented before being passed to Python
+===================================================================================
+
+Tohil's #1 new feature request!  Up until now, the argument to ``tohil::exec``
+had to obey Python indentation rules including there being no indentation at all
+for the top level, leading to ugly stuff like:
+
+::
+
+        tohil::exec {
+    def new_validate(self, data):
+         return json.loads(base64.b64decode(data))
+        }
+
+^ The "def" here has to occur at the beginning of the line, i.e. not be preceded
+by any spaces or
+tabs, or Python will raise an exception.  This nesting does not "read" well.
+
+To make it easier to make your code read well and comply with Python indentation rules,
+if the first nonblank line starts with whitespace, tohil::exec will un-indent the code block
+such that the first line is not indented at all and following lines are undented
+to match, all done lickety split, natively in C.
+
+So you can now nest your embedded Python code in a more standard way:
+
+::
+
+    tohil::exec {
+       def new_validate(self, data):
+            return json.loads(base64.b64decode(data))
+    }
+
+=======================================
+Additional Improvements
+=======================================
+
+* Added ``-nonevalue`` option to ``tohil::call``, allowing the "none" sentinel
+  to be specified arbitrarily (Retains the default value of ``tohil::NONE``.)
+* Cleaned up tohil namespace so ``dir(tohil)`` doesn't show modules tohil imported as
+  if it had created them.
+* Made ``package forget tohil`` work.
+* Added support for the Tcl ``unload`` command to be able to unload the Tohil shared
+  library. (Consider it risky, though.)
+
+========================================
+Bug Fixes
+========================================
+
+* Fixed crash when register_callback-registered functions raised a Python exception
+
+=====================================
+Improved Build Support
+=====================================
+
+* Added support for building tohil as a Debian package
+* Homebrew formula for building with homebrew
+
diff --git a/Doc/whatsnew/index.rst b/Doc/whatsnew/index.rst
index a736c14..e600def 100644
--- a/Doc/whatsnew/index.rst
+++ b/Doc/whatsnew/index.rst
@@ -10,6 +10,7 @@
 .. toctree::
    :maxdepth: 2
 
+   4.2.rst
    4.1.rst
    4.0.rst
    3.2.rst