Apply AA-Turner's edits

Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com>

Author: hoodmane

peps/pep-0776.rst

@@ -14,11 +14,11 @@ Abstract
 ========
 
 `Emscripten <https://emscripten.org/>`__ is a complete open source compiler
-toolchain which compiles C/C++ code into WebAssembly/JavaScript executables that
-run in JavaScript runtimes including browsers and Node.js.
+toolchain. It compiles C/C++ code into WebAssembly/JavaScript executables,
+for use in JavaScript runtimes, including browsers and Node.js.
 
 This PEP formalizes the addition of Tier 3 for Emscripten support in Python 3.14
-which `was approved by the steering council on October 25, 2024
+which `was approved by the Steering Council on October 25, 2024
 <https://github.com/python/steering-council/issues/256>`__. The goal is to allow
 Pyodide wheels to be uploaded to PyPI.
 
@@ -65,7 +65,7 @@ Packaging Goals
 1. To describe Pyodide's packaging tooling
 2. To describe Pyodide's wheel abi to a similar level of detail as the manylinux
    PEPs
-3. To request that Pyodide wheels be allowed for upload to PyPI
+3. For Pyodide wheels to be allowed for upload to PyPI
 
 
 Emscripten Platform Information
@@ -79,11 +79,11 @@ Background on Emscripten
 consists of a C and C++ compiler and linker based on LLVM, together with a
 runtime based on a mildly patched musl libc.
 
-Emscripten is a POSIX-based platform. It uses the WebAssembly binary format,
-specified here:
+Emscripten is a POSIX-based platform. It uses the `WebAssembly binary format`_,
+and the `WebAssembly dynamic linking section`_.
 
-* https://webassembly.github.io/spec/core/binary/index.html
-* https://github.com/WebAssembly/tool-conventions/blob/main/DynamicLinking.md
+.. _WebAssembly binary format: https://webassembly.github.io/spec/core/binary/index.html
+.. _WebAssembly dynamic linking section: https://github.com/WebAssembly/tool-conventions/blob/main/DynamicLinking.md
 
 The ``emcc`` compiler is a wrapper around ``clang``. The ``emcc`` linker is a
 wrapper around ``wasm-ld`` (also part of the LLVM toolchain).
@@ -106,18 +106,20 @@ Emscripten executables can be linked with threading support, but it comes
 with several limitations:
 
 * Enabling threading requires websites to be served with special security headers
-  that indicate acceptance of the possibility of `Spectre <https://en.wikipedia.org/wiki/Spectre_(security_vulnerability)>`__-style information
+  that indicate acceptance of the possibility of Spectre_-style information
   leakage. These headers are a usability hazard for users who are not intimately
   familiar with the web platform.
 
+  .. _Spectre: https://en.wikipedia.org/wiki/Spectre_(security_vulnerability)
+
 * If an executable is linked with both threading and a dynamic loader, Emscripten
   prints a warning that using dynamic loading and pthreads together is
   experimental. It may cause performance problems or crashes. These problems may
   require WebAssembly standards work to resolve.
 
 Because of these limitations, Pyodide standardizes a no-pthreads build of
-Python. We will start with support for no-pthreads builds. If there is
-sufficient demand, a pthreads build with no dynamic loader could be added later.
+Python. If there is sufficient demand, a pthreads build with no dynamic loader
+could be added later.
 
 Emscripten ABI Compatibility
 ----------------------------
@@ -141,20 +143,20 @@ ABI for each feature release of Python.
 The Pyodide team also coordinates the ABI flags that Pyodide uses with the
 Emscripten ABI that Rust supports in order to ensure that we have support for
 the many popular Rust packages. Historically, most of the work for this has
-been related to unwinding ABIs. See for instance `this Rust Major change
-proposal <https://github.com/rust-lang/compiler-team/issues/801>`__.
+been related to unwinding ABIs. See for instance `this Rust Major Change
+Proposal <https://github.com/rust-lang/compiler-team/issues/801>`__.
 
 Development Tools
 -----------------
 
 Emscripten development tools are equally well supported on Linux, Windows, and
-macOS. Upstream tools:
+macOS. The upstream tools include:
 
-* The Emscripten Software Developer Kit (emsdk) which can be used to install the
-  Emscripten compiler toolchain (emcc).
-* emcc is a C and C++ compiler, linker, and a sysroot with headers for the
-  system libraries. The system libraries themselves are generated on the fly
-  based on the ABI requested.
+* The Emscripten Software Developer Kit (:program:`emsdk`) which can be used to
+  install the Emscripten compiler toolchain (:program:`emcc`).
+* :program:`emcc` is a C and C++ compiler, linker, and a sysroot with headers
+  for the system libraries. The system libraries themselves are generated on
+  the fly based on the ABI requested.
 * Node.js can be used as an "emulator" to run Emscripten programs from the
   command line. This emulation behaves best on Linux with macOS as a runner up.
   Node.js is the most convenient way to test Emscripten programs.
@@ -170,7 +172,9 @@ Pyodide's tools:
 * ``pyodide venv`` can make a virtual environment that runs in Pyodide.
 * ``pytest-pyodide`` can test Python code against various JavaScript runtimes.
 
-cibuildwheel supports building wheels to target Emscripten using ``pyodide build``.
+cibuildwheel__ supports building wheels to target Emscripten using ``pyodide build``.
+
+__ https://cibuildwheel.pypa.io/
 
 In the short term, Pyodide's packaging tooling will stay in the Pyodide
 repository. It is an open question where Pyodide's packaging tooling should live
@@ -189,13 +193,13 @@ shut down the runtime on exit. It also includes an implementation for all of the
 system calls, including the file system, the dynamic loader, and any logic to
 expose additional functionality from the JavaScript runtime to C code.
 
-The ``.mjs`` file exports a single ``bootstrapEmscriptenExecutable()``
+The ``.mjs`` file exports a single :js:func:`bootstrapEmscriptenExecutable()`
 JavaScript function that bootstraps the runtime, calls the ``main()`` function,
 and returns an API object that can be used to call C functions. Each time it is
 called produces a complete and independent copy of the runtime with its own
 separate address space.
 
-The ``bootstrapEmscriptenExecutable()`` takes a large number of runtime
+The :js:func:`bootstrapEmscriptenExecutable()` takes a large number of runtime
 settings. `The full list is described in the Emscripten documentation here.
 <https://emscripten.org/docs/api_reference/module.html#id3>`__ The most
 important of these are as follows:
@@ -242,8 +246,8 @@ Emscripten file system. There are several possible approaches to this:
   uncompressed zip file allows the web server and client to apply better
   compression to the standard library itself. It also uses the more efficient
   native decompression algorithms of the browser rather than less efficient
-  WebAssembly decompression. The disadvantage of this is a higher memory
-  footprint and it breaks :py:mod:`inspect` and various tests that do not expect the
+  WebAssembly decompression. The disadvantages of this are a higher memory
+  footprint and breaking :py:mod:`inspect` & various tests that do not expect the
   standard library to be packaged in this way.
 
 * Put the standard library into an uncompressed tar archive and mount it into a
@@ -256,30 +260,30 @@ Pyodide uses the ``ZipImporter`` approach in every runtime. Python uses the
 NODEFS approach when run with node and the ``ZipImporter`` approach for the web
 example. We will continue with this approach.
 
-The ``ZipImporter`` provides a clean resolution for a bootstrapping problem: The
+The ``ZipImporter`` provides a clean resolution for a bootstrapping problem: the
 Python runtime is capable of unpacking a wide variety of archive formats, but
 the Python runtime is not ready to use until the standard library is already
 available. Since ``zipimport.py`` is a frozen module, it avoids these problems.
 All of the other approaches solve the bootstrapping problem by setting up the
 standard library using JavaScript.
 
-Packages
-~~~~~~~~
+Third-party packages
+~~~~~~~~~~~~~~~~~~~~
 
 It is also necessary to make any needed packages available in the Emscripten
-file system. Currently Emscripten cpython has no support for packages. Pyodide
+file system. Currently Emscripten CPython has no support for packages. Pyodide
 uses two different approaches for packages:
 
 * In the browser, Pyodide downloads and unpacks wheels into the MEMFS
   site-packages directory. It then preloads all dynamic libraries in the wheel.
   The work of downloading and installing all the packages is redone every time
   the runtime starts.
 
-* The Pyodide ``python`` cli entrypoint mounts all of the host file system as
+* The Pyodide ``python`` CLI entrypoint mounts all of the host file system as
   NODEFS directories before it bootstraps Python. This allows the normal virtual
   environment mechanism to work. Pyodide virtual environments contain a patched
   copy of pip and a custom ``pip.conf`` so that pip will install Pyodide wheels.
-  On startup the Pyodide ``python`` cli will preload all Emscripten dynamic
+  On startup the Pyodide ``python`` CLI will preload all Emscripten dynamic
   libraries that are in the site-packages directory.
 
 
@@ -288,7 +292,7 @@ Console and Interactive Usage
 
 ``stdin`` defaults to always returning ``EOF``, while ``stdout`` and ``stderr``
 default to calling ``console.log`` and ``console.error`` respectively. It is
-possible to pass handlers to ``bootstrapEmscriptenExecutable()`` to configure
+possible to pass handlers to :js:func:`bootstrapEmscriptenExecutable()` to configure
 the standard streams, but no matter what the I/O devices have undesirable line
 buffering behavior that forces a new line when flushed. To implement a well
 behaved TTY in-browser, it is necessary to remove the default I/O devices and
@@ -394,7 +398,7 @@ exceptions. This ensures that any recoverable JavaScript error is caught before
 it unwinds through any WebAssembly frames. All entrypoints to WebAssembly are
 also wrapped with JavaScript try/catch blocks. Any exceptions caught there have
 unwound WebAssembly frames and are thus considered to be fatal errors (though
-there is a special case to handle ``exit()``). This requires foundational
+there is a special case to handle :func:`~sys.exit()`). This requires foundational
 integration with the Python/JavaScript foreign function interface.
 
 When the Pyodide runtime catches a fatal exception, it introspects the error to
@@ -413,7 +417,7 @@ traceback.
 
 Because Emscripten Python currently has no JavaScript API and no foreign function
 interface, the situation is much simpler. The Python Node.js runner wraps the call
-to ``bootstrapEmscriptenExecutable()`` in a try/catch block. If an exception is
+to :js:func:`bootstrapEmscriptenExecutable()` in a try/catch block. If an exception is
 caught, it displays the JavaScript exception and calls ``_Py_DumpTraceback()``.
 It then exits with code 1. We will stick with this approach until we add either
 a JavaScript API or foreign function interface, which is out of scope for this PEP.
@@ -714,8 +718,8 @@ code duplication.
 Eventually, we would like to upstream Pyodide's bootstrapping API. In the short
 term, to keep things simple we will support no JavaScript API.
 
-FFI
-~~~
+JavaScript foreign function interface (FFI)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Because Emscripten supports POSIX, a significant number of tasks can be achieved
 using the ``os`` module. However, many fundamental operations in JavaScript