Point to readme, improve readme

Author: tiran

Tools/wasm/README.md

@@ -83,17 +83,17 @@ popd
 node --experimental-wasm-threads --experimental-wasm-bulk-memory builddir/emscripten-node/python.js
 ```
 
-## wasm32-emscripten limitations and issues
+# wasm32-emscripten limitations and issues
 
-- Heap and stack are limited.
-- Most stdlib modules with a dependency on external libraries are missing:
-  ``ctypes``, ``readline``, ``sqlite3``, ``ssl``, and more.
-- Shared extension modules are not implemented yet. All extension modules
-  are statically linked into the main binary.
-  The experimental configure option ``--enable-wasm-dynamic-linking`` enables
-  dynamic extensions.
-- Processes are not supported. System calls like fork, popen, and subprocess
-  fail with ``ENOSYS`` or ``ENOSUP``.
+Emscripten before 3.1.8 has known bugs that can cause memory corruption and
+resource leaks. 3.1.8 contains several fixes for bugs in date and time
+functions.
+
+## Network stack
+
+- Python's socket module does not work with Emscripten's emulated POSIX
+  sockets yet. Network modules like ``asyncio``, ``urllib``, ``selectors``,
+  etc. are not available.
 - Only ``AF_INET`` and ``AF_INET6`` with ``SOCK_STREAM`` (TCP) or
   ``SOCK_DGRAM`` (UDP) are available. ``AF_UNIX`` is not supported.
 - ``socketpair`` does not work.
@@ -102,8 +102,21 @@ node --experimental-wasm-threads --experimental-wasm-bulk-memory builddir/emscri
   does not resolve to a real IP address. IPv6 is not available.
 - The ``select`` module is limited. ``select.select()`` crashes the runtime
   due to lack of exectfd support.
+
+## processes, threads, signals
+
+- Processes are not supported. System calls like fork, popen, and subprocess
+  fail with ``ENOSYS`` or ``ENOSUP``.
 - Signal support is limited. ``signal.alarm``, ``itimer``, ``sigaction``
   are not available or do not work correctly. ``SIGTERM`` exits the runtime.
+- Keyboard interrupt (CTRL+C) handling is not implemented yet.
+- Browser builds cannot start new threads. Node's web workers consume
+  extra file descriptors.
+- Resource-related functions like ``os.nice`` and most functions of the
+  ``resource`` module are not available.
+
+## file system
+
 - Most user, group, and permission related function and modules are not
   supported or don't work as expected, e.g.``pwd`` module, ``grp`` module,
   ``os.setgroups``, ``os.chown``, and so on. ``lchown`` and `lchmod`` are
@@ -117,23 +130,35 @@ node --experimental-wasm-threads --experimental-wasm-bulk-memory builddir/emscri
   and are disabled.
 - Large file support crashes the runtime and is disabled.
 - ``mmap`` module is unstable. flush (``msync``) can crash the runtime.
-- Resource-related functions like ``os.nice`` and most functions of the
-  ``resource`` module are not available.
+
+## Misc
+
+- Heap memory and stack size are limited. Recursion or extensive memory
+  consumption can crash Python.
+- Most stdlib modules with a dependency on external libraries are missing,
+  e.g. ``ctypes``, ``readline``, ``sqlite3``, ``ssl``, and more.
+- Shared extension modules are not implemented yet. All extension modules
+  are statically linked into the main binary.
+  The experimental configure option ``--enable-wasm-dynamic-linking`` enables
+  dynamic extensions.
 - glibc extensions for date and time formatting are not available.
 - ``locales`` module is affected by musl libc issues,
   [bpo-46390](https://bugs.python.org/issue46390).
 - Python's object allocator ``obmalloc`` is disabled by default.
 - ``ensurepip`` is not available.
 
-### wasm32-emscripten in browsers
+## wasm32-emscripten in browsers
 
+- The interactive shell does not handle copy 'n paste and unicode support
+  well.
 - The bundled stdlib is limited. Network-related modules,
   distutils, multiprocessing, dbm, tests and similar modules
   are not shipped. All other modules are bundled as pre-compiled
   ``pyc`` files.
 - Threading is not supported.
+- In-memory file system (MEMFS) is not persistent and limited.
 
-### wasm32-emscripten in node
+## wasm32-emscripten in node
 
 Node builds use ``NODERAWFS``, ``USE_PTHREADS`` and ``PROXY_TO_PTHREAD``
 linker options.

Tools/wasm/python.html

@@ -237,21 +237,9 @@ <h1>Simple REPL for Python WASM</h1>
     </div>
     <div id="info">
         The simple REPL provides a limited Python experience in the browser.
-        <ul>
-            <li>
-                Large parts of the stdlib are not provided or do not work
-                correctly.
-            </li>
-            <li>
-                Python's socket and networking modules do not work with
-                emulated POSIX sockets yet. asyncio and urllib are not
-                available.
-            </li>
-            <li>In-memory file system is not persistent and limited.</li>
-            <li>Sub processes and threading APIs are not available.</li>
-            <li>Heap memory and stack size are restricted.</li>
-            <li>Copy 'n paste and unicode support are limited.</li>
-        </ul>
+        <a href="https://github.com/python/cpython/blob/main/Tools/wasm/README.md">
+        Tools/wasm/README.md</a> contains a list of known limitations and
+        issues. Networking, subprocesses, and threading are not available.
     </div>
 </body>
 </html>