Merge branch 'master' into 3.6

Author: slozier

Documentation/differences-from-c-python.md

@@ -132,7 +132,7 @@ $ source test.sh
 $ export NAME
 ```
 
-This creates an environment variable that is encoded using Latin-1 encoding, thather than the system encoding. CPython will escape the invalid byte 0xe9 (letter 'é' in Latin-1) in a lone surrogate 0xdce9, which is still an invalid Unicode character.
+This creates an environment variable that is encoded using Latin-1 encoding, rather than the system encoding. CPython will escape the invalid byte 0xe9 (letter 'é' in Latin-1) in a lone surrogate 0xdce9, which is still an invalid Unicode character.
 
 _CPython_
 ```
@@ -158,7 +158,7 @@ Andr�
 '0xfffd'
 ```
 
-The CPython's representation is not printable, but can be safely encoded back to the original form using `'surrogateescape'` (default when dealing with the OS environment):
+The CPython representation is not printable, but can be safely encoded back to the original form using `'surrogateescape'` (default when dealing with the OS environment):
 
 _CPython_
 ```
@@ -170,7 +170,7 @@ b'/bin:/usr/bin:/usr/local/bin:/home/Andr\xe9/bin'
 b'Andr\xe9'
 ```
 
-The IronPython's representation is printable, but the original byte value is lost:
+The IronPython representation is printable, but the original byte value is lost:
 
 _IronPython_
 ```
@@ -180,7 +180,7 @@ b'Andr\xef\xbf\xbd'
 
 # Codecs
 
-* Some single-byte codecs may have unused positions in their codepage. There are differences how CPython and IronPython (and .NET) handle such cases.
+* Some single-byte codecs may have unused positions in their codepage. There are differences between how CPython and IronPython (and .NET) handle such cases.
 
 A simple example is encoding Windows-1252. According to the information on Microsoft's and the Unicode Consortium's websites, positions 81, 8D, 8F, 90, and 9D are unused; however, the Windows API `MultiByteToWideChar` maps these to the corresponding C1 control codes. The Unicode "best fit" mapping [documents this behavior](https://www.unicode.org/Public/MAPPINGS/VENDORS/MICSFT/WindowsBestFit/bestfit1252.txt). CPython will treat those bytes as invalid, while IronPython will map them to the "best fit" Unicode character:
 

Documentation/getting-the-sources.md

@@ -15,7 +15,7 @@ The following links include resources for installing and using GIT:
 
 ### Creating a local GIT repository
 
-You will first need to fork the IronPython3 project. [Creating a fork](https://help.github.com/fork-a-repo/) is recommended as it will allow you to contribute patches back easily. Click the "Fork" button on [https://github.com/IronLanguages/ironpython3/](https://github.com/IronLanguages/ironpython3/). This should create your personal fork, with a website like http://github.com/janedoe/ironpython3 (where janedoe is your github username). 
+You will first need to fork the IronPython3 project. [Creating a fork](https://help.github.com/fork-a-repo/) is recommended as it will allow you to contribute patches back easily. Click the "Fork" button on [https://github.com/IronLanguages/ironpython3/](https://github.com/IronLanguages/ironpython3/). This should create your personal fork, with a web URL like http://github.com/janedoe/ironpython3 (where janedoe is your github username). 
 
 You can now use the git command-line client with many Linux distributions, Mac OS, Cygwin, and Windows (msysgit) to get the sources onto your local computer using the following commands:
 

Documentation/installing.md

@@ -8,7 +8,7 @@ Since .NET is a cross-platform framework, the instructions in this section apply
 
 ### .NET SDK
 
-If the target system has already a full .NET SDK installed, the most straightforward method to install a standalone IronPython interpreter is by using [`dotnet tool`](https://learn.microsoft.com/en-us/dotnet/core/tools/global-tools).
+If the target system already has a full .NET SDK installed, the most straightforward method to install a standalone IronPython interpreter is by using [`dotnet tool`](https://learn.microsoft.com/en-us/dotnet/core/tools/global-tools).
 
 #### _Global Tool_
 
@@ -18,7 +18,7 @@ If the target system has already a full .NET SDK installed, the most straightfor
 dotnet tool install --global ironpython.console
 ```
 
-The switch `--global` can be abbreviated to `-g`. The `ipy` program will be installed in `~/.dotnet/tools`, together with the Python Standard Library for IronPython. The directory `~/.dotnet/tools` should have been added to the search path for the user (a.k.a. `PATH` environment variable), if not yet done.
+The switch `--global` can be abbreviated to `-g`. The `ipy` program will be installed in `~/.dotnet/tools`, together with the Python Standard Library for IronPython. The directory `~/.dotnet/tools` should be added to the search path for the user (AKA `PATH` environment variable), if not yet done.
 
 Note that any additional Python packages installed using `ipy -m pip` from this location will be installed inside that directory, hence being "global" for the user.
 
@@ -125,12 +125,26 @@ dpkg -i ~/Downloads/ironpython_3.X.Y.deb
 
 On macOS (AKA OSX, Darwin), Mono provides the necessary .NET Framework. First install Mono following installation instructions from the [Mono Project page](https://www.mono-project.com/download/stable/#download-mac).  After installation, verify that command `mono` is available at the shell prompt, with, e.g. `mono --version`.
 
-Then download the `.pkg` installer from the project's [release page](https://github.com/IronLanguages/ironpython3/releases/latest) and execute it.
+Then download the `.pkg` installer from the project's [release page](https://github.com/IronLanguages/ironpython3/releases/latest) and execute it. The IronPython installation is placed in `/Library/Frameworks/IronPython.framework/Versions/3.X.Y` (`X` and `Y` being the minor and patch version numbers). It can be run with:
 
+```
+mono /Library/Frameworks/IronPython.framework/Versions/3.X.Y/bin/ipy.exe
+```
+
+Note that Mono comes with its own (old, obsolete, and unsupported) version of IronPython and a launcher script `ipy` in Mono's commands directory (`/Library/Frameworks/Mono.framework/Versions/Current/Commands/ipy`). Since Mono's command directory is by default added to the command search path, simply running `ipy` from the command line will most likely pick up the Mono version. This version reports version number 3.0.0.0 and is backed by Python StdLib 2.7. To verify if this is the case, run:
+
+```shell
+$ which ipy
+/Library/Frameworks/Mono.framework/Versions/Current/Commands/ipy
+$ ipy -V
+IronPython 3.0 3.0.0.0 on 6.12.0.188 (2020-02/ca8abcb6bc4 Thu Oct 13 14:26:22 EDT 2022)
+```
+
+It is recommended to create one's own launcher script launching the newer IronPython version and to put it before Mono's `ipy` on the search path.
 
 # Installing Non-Released Versions
 
-After a release, the development of IronPython continues so it is possible that a bug or a feature that is important to you got handled after the latest release. As each commit to the main project branch creates precompiled artifacts, it is still possible to install the relevant (or latest development) version of IronPython without the need to compile the whole project from scratch.
+After a release, the development of IronPython continues so it is possible that a bug or a feature that is important to you was handled after the latest release. As each commit to the main project branch creates precompiled artifacts, it is still possible to install the relevant (or latest development) version of IronPython without the need to compile the whole project from scratch.
 
 Go to the project's [_Actions_ page](https://github.com/IronLanguages/ironpython3/actions) and find the commit you are interested in. Or simply find the topmost commit to `master` that has all tests passing. The _Status_ and _Branch_ filters in the top bar are helpful to narrow the list down. Then click on the commit hyperlink to access the CI run summary. At the bottom of that page there is artifact `packages`, which contains all binary artifacts the project produces. Download it and unzip. Choose the right package for your needs and follow instructions above for the officially released artifacts. For convenience, here is a table with usable packages:
 

Documentation/modifying-the-sources.md

@@ -14,7 +14,7 @@ Most PR's will not be accepted if there is not a test included.
  * Use `/*!*/` for method parameters and instance fields that should never be null. [Spec# annotations](http://research.microsoft.com/specsharp).
  * Do not use public fields (Base::algorithm, buffer). Use properties if it is necessary to expose the field or private/internal visibility otherwise.
  * Use `readonly` if the field is not mutated after the object is constructed.
- * Auto properties are to be used when possible instead of private fields with wrapping properties
+ * Auto properties are to be used when possible instead of private fields with wrapping properties.
  * String interpolation should use used instead of calls to `String.Format`
 
 # Validating the changes

Documentation/upgrading-from-ipy2.md

@@ -104,11 +104,11 @@ The creation of either `Int32` or `BigInteger` instances happens automatically b
 False
 ```
 
-In the opposite direction, if it is essential to create `Int32` objects, either use constructors for `int` or `Int32`. In the current implementation, the former converts an integer to `Int32` if the value fits in 32 bits, otherwise it leaves it as `BigInteger`. The latter throws an exception is the conversion is not possible. Although the behavior of the constructor `int` may or may not change in the future, it is always guaranteed to convert the value to the "canonical form" adopted for that version of IronPython.
+In the opposite direction, if it is essential to create `Int32` objects, either use constructors for `int` or `Int32`. In the current implementation, the former converts an integer to `Int32` if the value fits in 32 bits, otherwise it leaves it as `BigInteger`. The latter throws an exception if the conversion is not possible. Although the behavior of the constructor `int` may or may not change in the future, it is always guaranteed to convert the value to the "canonical form" adopted for that version of IronPython.
 
 ```pycon
 >>> # k is a BigInteger that fits in 32 bits
->>> isinstance(j, System.Int32)
+>>> isinstance(k, System.Int32)
 False
 >>> hex(k)
 '0x7fffffff'
@@ -150,7 +150,7 @@ When an `int` object is serialized using `pickle.dump(x, myfile)` and subsequent
 
 ### BigIntegerV2 API
 
-In IronPython 2, `long` type carries an obsolete `BigIntegerV2` API, accessible after importing `System`. In IronPython 3 this API is not available directly on `int` instances (regardless whether the instance is `Int32` or `BigInteger`), but is still accessible in some form through `Microsoft.Scripting.Utils.MathUtils` in `Microsoft.Dynamic.dll`.
+In IronPython 2, `long` type carries an obsolete `BigIntegerV2` API, accessible after importing `System`. In IronPython 3 this API is not available directly on `int` instances (regardless of whether the instance is `Int32` or `BigInteger`), but is still accessible in some form through `Microsoft.Scripting.Utils.MathUtils` in `Microsoft.Dynamic.dll`.
 
 ```pycon
 >>> # IronPython 2