Improved markdown formatting

- Use code blocks
- Made the MAPI license actually readable
- Ran through Markdownlint
- Fixed encoding of mapi_headers/README.md but otherwise kept content as-is

README.md

@@ -31,13 +31,17 @@ closed. For such issues, please email the
 note that you must be subscribed to the list before posting.
 
 ## Binaries
+
 [Binary releases are deprecated.](https://mhammond.github.io/pywin32_installers.html)
 While they are still provided, [find them here](https://github.com/mhammond/pywin32/releases)
 
 ## Installing via PIP
 
 You should install pywin32 via pip - eg,
-> python -m pip install --upgrade pywin32
+
+```shell
+python -m pip install --upgrade pywin32
+```
 
 There is a post-install script (see below) which should *not* be run inside virtual environments;
 it should only be run in "global" installs.
@@ -50,7 +54,9 @@ choose any "workflow" from the `main` branch and download its "artifacts")
 Outside of a virtual environment you might want to install COM objects, services, etc. You can do
 this by executing:
 
-> python Scripts/pywin32_postinstall.py -install
+```shell
+python Scripts/pywin32_postinstall.py -install
+```
 
 From the root of your Python installation.
 
@@ -69,9 +75,10 @@ the service has access to the installation and is able to load `pywintypesXX.dll
 to your local `%USER%` directory structure.
 
 ## Troubleshooting
+
 If you encounter any problems when upgrading like the following:
 
-```
+```text
 The specified procedure could not be found
 Entry-point not found
 ```
@@ -81,25 +88,27 @@ It usually means one of 2 things:
 * You've upgraded an install where the post-install script has previously run.
 So you should run it again:
 
-    > python Scripts/pywin32_postinstall.py -install
+    ```shell
+    python Scripts/pywin32_postinstall.py -install
+    ```
 
     This will make some small attempts to cleanup older conflicting installs.
 
 * There are other pywin32 DLLs installed in your system,
 but in a different location than the new ones. This sometimes happens in environments that
 come with pywin32 pre-shipped (eg, anaconda?).
 
-    The possible solutions here are:
-
-    * Run the "post_install" script documented above.
+  The possible solutions here are:
 
-    * Otherwise, find and remove all other copies of `pywintypesXX.dll` and `pythoncomXX.dll`
+  * Run the "post_install" script documented above.
+  * Otherwise, find and remove all other copies of `pywintypesXX.dll` and `pythoncomXX.dll`
   (where `XX` is the Python version - eg, "39")
 
 ## Building from source
 
 Install Visual Studio 2019 (later probably works, but options might be different),
 select "Desktop Development with C++", then the following options:
+
 * Windows 10 SDK (latest offered I guess? At time of writing, 10.0.18362)
 * "C++ for MFC for ..."
 * ARM build tools if necessary.
@@ -108,11 +117,15 @@ select "Desktop Development with C++", then the following options:
 
 `setup.py` is a standard distutils build script, so you probably want:
 
-> python setup.py install
+```shell
+python setup.py install
+```
 
 or
 
-> python setup.py --help
+```shell
+python setup.py --help
+```
 
 Some modules need obscure SDKs to build - `setup.py` should succeed, gracefully
 telling you why it failed to build them - if the build actually fails with your
@@ -121,7 +134,7 @@ configuration, please [open an issue](https://github.com/mhammond/pywin32/issues
 ## Release process
 
 The following steps are performed when making a new release - this is mainly
-to form a checklist so mhammond doesn't forget what to do :)
+to form a checklist so @mhammond doesn't forget what to do :)
 
 * Ensure CHANGES.txt has everything worth noting. Update the header to reflect
   the about-to-be released build and date, commit it.

build_env.md

@@ -13,28 +13,33 @@ by default.
 
 In the Visual Studio Installer:
 
-## For Visual Studio 2017:
+## For Visual Studio 2017
 
 Locate the "Desktop development with C++" section:
 
 Ensure the following components are installed:
-* VC++ 2015.3 v14.00 (v140) toolset for desktop
-* Windows 8.1 SDK and UCRT SDK
-* Visual C++ MFC for x86 and x64
+
+- VC++ 2015.3 v14.00 (v140) toolset for desktop
+- Windows 8.1 SDK and UCRT SDK
+- Visual C++ MFC for x86 and x64
 
 if you want to cross-compile for ARM, you will need at least the following (from "Individual Components")
-* "Visual C++ compilers and libraries for ARM64"
-* "Visual C++ for MFC for ARM64"
 
+- "Visual C++ compilers and libraries for ARM64"
+- "Visual C++ for MFC for ARM64"
 
 (You should be able to check everything you need is installed by opening a
 command prompt and executing:
 
-% "C:\Program Files (x86)\Microsoft Visual Studio\2017\Professional\VC\Auxiliary\Build\vcvarsall.bat" x86_amd64 8.1 -vcvars_ver=14.0
+```shell
+"C:\Program Files (x86)\Microsoft Visual Studio\2017\Professional\VC\Auxiliary\Build\vcvarsall.bat" x86_amd64 8.1 -vcvars_ver=14.0
+```
 
 if that works, then executing:
 
-% cl
+```shell
+cl
+```
 
 should report the compiler version:
 > Microsoft (R) C/C++ Optimizing Compiler Version 19.00.24234.1 for x64
@@ -43,18 +48,20 @@ Note however that it's *not* necessary to configure the environment in this
 way to build pywin32 - it's build process should find these tools automatically.
 
 ## For Visual Studio 2019
+
 - Install the [Build Tools for Visual Studio 2019](https://visualstudio.microsoft.com/thank-you-downloading-visual-studio/?sku=BuildTools&rel=16#) (`vs_BuildTools.exe` ~ 1 MB)
+
 - Maybe stop your virus scanner
 - In `Visual Studio installer`:
   - Select `Visual Studio Build Tools 2019`
     - Press `Modify`
       - In `Visual Studio Build Tools 2019`
         - Check `C++ build tools`
           - In the menue to the right, check:
-              - `MSVC v142 - VS 2019 C++ x64/x86 build tools`
-              - `Windows 10 SDK`
-              - `C++ MFC for latest v142 build tools (x86 & x64)`
-              - `C++ ATL for latest v142 build tools`
+            - `MSVC v142 - VS 2019 C++ x64/x86 build tools`
+            - `Windows 10 SDK`
+            - `C++ MFC for latest v142 build tools (x86 & x64)`
+            - `C++ ATL for latest v142 build tools`
         - If building for ARM64 (optional), select the "Individual Components" tab, and search for and select:
               - `MSVC v142 - VS 2019 C++ ARM64 build tools`
               - `C++ MFC for latest v142 build tools (ARM64)`
@@ -64,18 +71,25 @@ way to build pywin32 - it's build process should find these tools automatically.
 - Restart
 
 ### Microsoft Message Compiler
+
 Search the executable
 
-    cd "c:\Program Files (x86)\Windows Kits"
-    dir /b /s mc.exe
+```shell
+cd "c:\Program Files (x86)\Windows Kits"
+dir /b /s mc.exe
+```
 
 Append location to the `path` (example)
 
-    set "path=%path%;c:\Program Files (x86)\Windows Kits\10\bin\10.0.18362.0\x64"
+```shell
+set "path=%path%;c:\Program Files (x86)\Windows Kits\10\bin\10.0.18362.0\x64"
+```
 
-Test with 
+Test with
 
-    where mc
+```shell
+where mc
+```
 
 (Note that the above process for 'mc' doesn't appear necessary for VS2017, but
 markh hasn't tried with VS2019 - please share your experiences!)
@@ -84,22 +98,46 @@ markh hasn't tried with VS2019 - please share your experiences!)
 
 One everything is setup, just execute:
 
-% python setup.py -q install
+```shell
+python setup.py -q install
+```
 
 from the pywin32 directory.
 
 ## Cross-compiling for ARM64 (Microsoft Visual C++ 14.1 and up)
+
 - Follow the `For Visual Studio 2019` instructions above and pick the optional ARM64 build tools
+
 - Download prebuilt Python ARM64 binaries to a temporary location on your machine. You will need this location in a later step.
-  > python .github\workflows\download-arm64-libraries.py "<temporary path>"
+
+    ```shell
+    python .github\workflows\download-arm64-libraries.py "<temporary path>"
+    ```
+
   - This script downloads a Python ARM64 build [from NuGet](https://www.nuget.org/packages/pythonarm64/#versions-tab) that matches the version you used to run it.
 - Setup the cross-compilation environment:
-  > "C:\Program Files (x86)\Microsoft Visual Studio\2019\BuildTools\vc\Auxiliary\Build\vcvarsall.bat" x86_arm64
+
+    ```shell
+    "C:\Program Files (x86)\Microsoft Visual Studio\2019\BuildTools\vc\Auxiliary\Build\vcvarsall.bat" x86_arm64
+    ```
+
 - Update `setuptools` and set the following environment variables to ensure it is used:
-  > set SETUPTOOLS_USE_DISTUTILS=1
-  > set DISTUTILS_USE_SDK=1
+
+    ```shell
+    set SETUPTOOLS_USE_DISTUTILS=1
+    set DISTUTILS_USE_SDK=1
+    ```
+
 - Build the extensions, passing the directory from earlier. You may optionally add the `bdist_wheel` command to generate a wheel.
-  > python setup.py build_ext -L "<temporary path from earlier>" bdist_wheel
-  - If you are not using an initialized build environment, you will need to specify the `build_ext`, `build` and `bdist_wheel` commands and pass `--plat-name win-arm64` to _each_ of them separately. Otherwise you may get a mixed platform build and/or linker errors.
+
+    ```shell
+    python setup.py build_ext -L "<temporary path from earlier>" bdist_wheel
+    ```
+
+  - If you are not using an initialized build environment, you will need to specify the `build_ext`, `build` and `bdist_wheel` commands and pass `--plat-name win-arm64` to *each* of them separately. Otherwise you may get a mixed platform build and/or linker errors.
+
 - Copy the built wheel to the target machine and install directly:
-  > python -m pip install "<path to wheel>"
+
+    ```shell
+    python -m pip install "<path to wheel>"
+    ```

com/win32comext/mapi/src/mapi_headers/README.md

@@ -7,10 +7,10 @@ MICROSOFT SOFTWARE LICENSE TERMS
 MICROSOFT OUTLOOK 2010 MAPI HEADER FILES
 
 These license terms are an agreement between Microsoft Corporation (or based on where you live, one of its affiliates) and you. Please read them. They apply to the software named above, which includes the media on which you received it, if any. The terms also apply to any Microsoft
-    • updates,
-    • supplements,
-    • Internet-based services, and 
-    • support services
+    • updates,
+    • supplements,
+    • Internet-based services, and 
+    • support services
 for this software, unless other terms accompany those items. If so, those terms apply.
 
 BY USING THE SOFTWARE, YOU ACCEPT THESE TERMS. IF YOU DO NOT ACCEPT THEM, DO NOT USE THE SOFTWARE.
@@ -19,43 +19,43 @@ If you comply with these license terms, you have the rights below.
 1. INSTALLATION AND USE RIGHTS. You may install and use any number of copies of the software on your devices.
 2. ADDITIONAL LICENSING REQUIREMENTS AND/OR USE RIGHTS.
     a. Distributable Code. The software contains code that you are permitted to distribute in programs you develop if you comply with the terms below.
-        i. Right to Use and Distribute. The code and text files listed below are “Distributable Code.”
-            • Sample Code. You may modify, copy, and distribute the source and object code form of code marked as “sample.”
-            • Third Party Distribution. You may permit distributors of your programs to copy and distribute the Distributable Code as part of those programs.
+        i. Right to Use and Distribute. The code and text files listed below are “Distributable Code.”
+            • Sample Code. You may modify, copy, and distribute the source and object code form of code marked as “sample.”
+            • Third Party Distribution. You may permit distributors of your programs to copy and distribute the Distributable Code as part of those programs.
         ii. Distribution Requirements. For any Distributable Code you distribute, you must
-            • add significant primary functionality to it in your programs;
-            • require distributors and external end users to agree to terms that protect it at least as much as this agreement; 
-            • display your valid copyright notice on your programs; and
-            • indemnify, defend, and hold harmless Microsoft from any claims, including attorneys’ fees, related to the distribution or use of your programs.
+            • add significant primary functionality to it in your programs;
+            • require distributors and external end users to agree to terms that protect it at least as much as this agreement; 
+            • display your valid copyright notice on your programs; and
+            • indemnify, defend, and hold harmless Microsoft from any claims, including attorneys’ fees, related to the distribution or use of your programs.
         iii. Distribution Restrictions. You may not
-            • alter any copyright, trademark or patent notice in the Distributable Code; 
-            • use Microsoft’s trademarks in your programs’ names or in a way that suggests your programs come from or are endorsed by Microsoft; 
-            • distribute Distributable Code to run on a platform other than the Windows platform;
-            • include Distributable Code in malicious, deceptive or unlawful programs; or
-            • modify or distribute the source code of any Distributable Code so that any part of it becomes subject to an Excluded License. An Excluded License is one that requires, as a condition of use, modification or distribution, that
-                • the code be disclosed or distributed in source code form; or 
-                • others have the right to modify it.
+            • alter any copyright, trademark or patent notice in the Distributable Code; 
+            • use Microsoft’s trademarks in your programs’ names or in a way that suggests your programs come from or are endorsed by Microsoft; 
+            • distribute Distributable Code to run on a platform other than the Windows platform;
+            • include Distributable Code in malicious, deceptive or unlawful programs; or
+            • modify or distribute the source code of any Distributable Code so that any part of it becomes subject to an Excluded License. An Excluded License is one that requires, as a condition of use, modification or distribution, that
+                • the code be disclosed or distributed in source code form; or 
+                • others have the right to modify it.
 3. SCOPE OF LICENSE. The software is licensed, not sold. This agreement only gives you some rights to use the software. Microsoft reserves all other rights. Unless applicable law gives you more rights despite this limitation, you may use the software only as expressly permitted in this agreement. In doing so, you must comply with any technical limitations in the software that only allow you to use it in certain ways. You may not
-    • work around any technical limitations in the software;
-    • reverse engineer, decompile or disassemble the software, except and only to the extent that applicable law expressly permits, despite this limitation;
-    • make more copies of the software than specified in this agreement or allowed by applicable law, despite this limitation;
-    • publish the software for others to copy;
-    • rent, lease or lend the software; or
-    • use the software for commercial software hosting services.
+    • work around any technical limitations in the software;
+    • reverse engineer, decompile or disassemble the software, except and only to the extent that applicable law expressly permits, despite this limitation;
+    • make more copies of the software than specified in this agreement or allowed by applicable law, despite this limitation;
+    • publish the software for others to copy;
+    • rent, lease or lend the software; or
+    • use the software for commercial software hosting services.
 4. BACKUP COPY. You may make one backup copy of the software. You may use it only to reinstall the software.
 5. DOCUMENTATION. Any person that has valid access to your computer or internal network may copy and use the documentation for your internal, reference purposes.
 6. TRANSFER TO ANOTHER DEVICE. You may uninstall the software and install it on another device for your use. You may not do so to share this license between devices.
 7. TRANSFER TO A THIRD PARTY. The first user of the software may transfer it and this agreement directly to a third party. Before the transfer, that party must agree that this agreement applies to the transfer and use of the software. The first user must uninstall the software before transferring it separately from the device. The first user may not retain any copies.
 8. EXPORT RESTRICTIONS. The software is subject to United States export laws and regulations. You must comply with all domestic and international export laws and regulations that apply to the software. These laws include restrictions on destinations, end users and end use. For additional information, see www.microsoft.com/exporting.
-9. SUPPORT SERVICES. Because this software is “as is,” we may not provide support services for it.
+9. SUPPORT SERVICES. Because this software is “as is,” we may not provide support services for it.
 10. ENTIRE AGREEMENT. This agreement, and the terms for supplements, updates, Internet-based services and support services that you use, are the entire agreement for the software and support services.
 11. APPLICABLE LAW.
     a. United States. If you acquired the software in the United States, Washington state law governs the interpretation of this agreement and applies to claims for breach of it, regardless of conflict of laws principles. The laws of the state where you live govern all other claims, including claims under state consumer protection laws, unfair competition laws, and in tort.
     b. Outside the United States. If you acquired the software in any other country, the laws of that country apply.
 12. LEGAL EFFECT. This agreement describes certain legal rights. You may have other rights under the laws of your country. You may also have rights with respect to the party from whom you acquired the software. This agreement does not change your rights under the laws of your country if the laws of your country do not permit it to do so.
-13. DISCLAIMER OF WARRANTY. THE SOFTWARE IS LICENSED “AS-IS.” YOU BEAR THE RISK OF USING IT. MICROSOFT GIVES NO EXPRESS WARRANTIES, GUARANTEES OR CONDITIONS. YOU MAY HAVE ADDITIONAL CONSUMER RIGHTS UNDER YOUR LOCAL LAWS WHICH THIS AGREEMENT CANNOT CHANGE. TO THE EXTENT PERMITTED UNDER YOUR LOCAL LAWS, MICROSOFT EXCLUDES THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT.
+13. DISCLAIMER OF WARRANTY. THE SOFTWARE IS LICENSED “AS-IS.” YOU BEAR THE RISK OF USING IT. MICROSOFT GIVES NO EXPRESS WARRANTIES, GUARANTEES OR CONDITIONS. YOU MAY HAVE ADDITIONAL CONSUMER RIGHTS UNDER YOUR LOCAL LAWS WHICH THIS AGREEMENT CANNOT CHANGE. TO THE EXTENT PERMITTED UNDER YOUR LOCAL LAWS, MICROSOFT EXCLUDES THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT.
 14. LIMITATION ON AND EXCLUSION OF REMEDIES AND DAMAGES. YOU CAN RECOVER FROM MICROSOFT AND ITS SUPPLIERS ONLY DIRECT DAMAGES UP TO U.S. $5.00. YOU CANNOT RECOVER ANY OTHER DAMAGES, INCLUDING CONSEQUENTIAL, LOST PROFITS, SPECIAL, INDIRECT OR INCIDENTAL DAMAGES.
 This limitation applies to
-    • anything related to the software, services, content (including code) on third party Internet sites, or third party programs; and
-    • claims for breach of contract, breach of warranty, guarantee or condition, strict liability, negligence, or other tort to the extent permitted by applicable law.
+    • anything related to the software, services, content (including code) on third party Internet sites, or third party programs; and
+    • claims for breach of contract, breach of warranty, guarantee or condition, strict liability, negligence, or other tort to the extent permitted by applicable law.
 It also applies even if Microsoft knew or should have known about the possibility of the damages. The above limitation or exclusion may not apply to you because your country may not allow the exclusion or limitation of incidental, consequential or other damages.