[docs] Fix rst syntax

site/source/docs/building_from_source/configuring_emscripten_settings.rst

@@ -26,12 +26,12 @@ in order to generate one in the default location.
 1. Navigate to the directory where you cloned the Emscripten repository.
 2. Enter the command:
 
-  ::
+   ::
 
-    ./emcc --generate-config
+      ./emcc --generate-config
 
-  You should get a ``An Emscripten settings file has been generated at:``
-  message, along with the contents of the config file.
+   You should get a ``An Emscripten settings file has been generated at:``
+   message, along with the contents of the config file.
 
 When generating this file Emscripten will make its "best guess" at the correct
 locations for tools based on the current ``PATH``.
@@ -48,12 +48,12 @@ The settings file (``.emscripten``) is created by default within the emscripten
 directory (alongside ``emcc`` itself).  In cases where the emscripten directory
 is read-only the user's home directory will be used:
 
-  - On Linux and macOS this file is named **~/.emscripten**, where ~ is the
-    user's home directory.
+- On Linux and macOS this file is named **~/.emscripten**, where ~ is the
+  user's home directory.
 
-    .. note:: Files with the "." prefix are hidden by default. You may need to change your view settings to find the file.
+  .. note:: Files with the "." prefix are hidden by default. You may need to change your view settings to find the file.
 
-  - On Windows the file can be found at a path like: **C:/Users/yourusername_000/.emscripten**.
+- On Windows the file can be found at a path like: **C:/Users/yourusername_000/.emscripten**.
 
 
 Compiler configuration file-format
@@ -80,10 +80,10 @@ update the variable ``LLVM_ROOT``
 #. Edit the variable ``LLVM_ROOT`` to point to the directory where you built the
    LLVM binaries, such as:
 
-    ::
+   ::
 
       LLVM_ROOT = '/home/ubuntu/a-path/llvm/build/bin'
 
-    .. note:: Use forward slashes!
+   .. note:: Use forward slashes!
 
 After setting those paths, run ``emcc`` again. It should again perform the sanity checks to test the specified paths. There are further validation tests available at :ref:`verifying-the-emscripten-environment`.

site/source/docs/building_from_source/index.rst

@@ -33,14 +33,12 @@ Building LLVM
 
 Build LLVM from the `git repo <https://github.com/llvm/llvm-project>`_.
 Include clang and wasm-ld (using something like ``-DLLVM_ENABLE_PROJECTS='lld;clang'``) and the Wasm backend (which is included by default; just don't disable it), following `that project's instructions <http://llvm.org/docs/CMake.html>`_.
-For example, something like this can work:
+For example, something like this can work::
 
-  ::
-
-      mkdir build
-      cd build/
-      cmake ../llvm -DCMAKE_BUILD_TYPE=Release -DLLVM_ENABLE_PROJECTS='lld;clang' -DLLVM_TARGETS_TO_BUILD="host;WebAssembly" -DLLVM_INCLUDE_EXAMPLES=OFF -DLLVM_INCLUDE_TESTS=OFF  # -DLLVM_ENABLE_ASSERTIONS=ON
-      cmake --build .
+    mkdir build
+    cd build/
+    cmake ../llvm -DCMAKE_BUILD_TYPE=Release -DLLVM_ENABLE_PROJECTS='lld;clang' -DLLVM_TARGETS_TO_BUILD="host;WebAssembly" -DLLVM_INCLUDE_EXAMPLES=OFF -DLLVM_INCLUDE_TESTS=OFF  # -DLLVM_ENABLE_ASSERTIONS=ON
+    cmake --build .
 
 Then set the environment variable ``EM_LLVM_ROOT`` to ``<llvm_src>/build/bin`` (no need to install).
 

site/source/docs/building_from_source/toolchain_what_is_needed.rst

@@ -22,13 +22,13 @@ Emscripten tools and dependencies
 
 In general a complete Emscripten environment requires the following tools. First test to see if they are already installed using the :ref:`instructions below <toolchain-test-which-dependencies-are-installed>`.
 
-  - :term:`Node.js` (18.3.0 or above)
-  - :term:`Python` (3.8 or above)
-  - :term:`Java` (1.6.0_31 or later). Java is optional. It can be used to run the java version of term:`Closure Compiler`.
-  - :term:`Git` client. Git is required if building tools from source.
-  - :term:`LLVM` (LLVM, including clang and wasm-ld)
-  - :term:`Binaryen` (Binaryen, including wasm-opt, wasm-emscripten-finalize, etc.)
-  - The `Emscripten code <https://github.com/emscripten-core/emscripten>`_, from GitHub
+- :term:`Node.js` (18.3.0 or above)
+- :term:`Python` (3.8 or above)
+- :term:`Java` (1.6.0_31 or later). Java is optional. It can be used to run the java version of term:`Closure Compiler`.
+- :term:`Git` client. Git is required if building tools from source.
+- :term:`LLVM` (LLVM, including clang and wasm-ld)
+- :term:`Binaryen` (Binaryen, including wasm-opt, wasm-emscripten-finalize, etc.)
+- The `Emscripten code <https://github.com/emscripten-core/emscripten>`_, from GitHub
 
 .. note: 64-bit versions of all needed dependencies are preferred, and may be required if you are building large projects.
 

site/source/docs/building_from_source/verify_emscripten_environment.rst

@@ -89,8 +89,8 @@ Other common problems
 
 Other common problems to check for are:
 
-   - Errors in the paths in :ref:`.emscripten <compiler-configuration-file>`. These are less likely if you update the file using :ref:`emsdk <emsdk>`.
-   - Using older versions of Node or JavaScript engines. Use the default versions for the SDK as listed with :ref:`emsdk list <emsdk>`.
-   - Using older versions of LLVM. The correct versions come with the SDK, but if you're building the environment from source you should make sure to use the proper version of LLVM (which you can find using the `emscripten-releases DEPS file and history <https://github.com/emscripten-core/emscripten/blob/main/docs/process.md#release-processes>`_; other versions might work, especially close-by ones, but are not tested by us and so not guaranteed to work).
+- Errors in the paths in :ref:`.emscripten <compiler-configuration-file>`. These are less likely if you update the file using :ref:`emsdk <emsdk>`.
+- Using older versions of Node or JavaScript engines. Use the default versions for the SDK as listed with :ref:`emsdk list <emsdk>`.
+- Using older versions of LLVM. The correct versions come with the SDK, but if you're building the environment from source you should make sure to use the proper version of LLVM (which you can find using the `emscripten-releases DEPS file and history <https://github.com/emscripten-core/emscripten/blob/main/docs/process.md#release-processes>`_; other versions might work, especially close-by ones, but are not tested by us and so not guaranteed to work).
 
 If none of the above is helpful, then please :ref:`contact us <contact>` for help.

site/source/docs/compiling/Building-Projects.rst

@@ -283,8 +283,8 @@ Adding more ports
 The simplest way to add a new port is to put it under the ``contrib`` directory.
 Basically, the steps are:
 
- * Make sure the port is open source and has a suitable license.
- * Read the ``README.md`` file under ``tools/ports/contrib`` which contains more information.
+* Make sure the port is open source and has a suitable license.
+* Read the ``README.md`` file under ``tools/ports/contrib`` which contains more information.
 
 External ports
 --------------
@@ -378,18 +378,18 @@ Detecting Emscripten in Preprocessor
 
 Emscripten provides the following preprocessor macros that can be used to identify the compiler version and platform:
 
- * The preprocessor define ``__EMSCRIPTEN__`` is always defined when compiling programs with Emscripten.
- * The preprocessor variables ``__EMSCRIPTEN_MAJOR__``, ``__EMSCRIPTEN_MINOR__``
-   and ``__EMSCRIPTEN_TINY__`` are defined in ``emscripten/version.h`` and
-   specify, as integers, the currently used Emscripten compiler version.
- * Emscripten behaves like a variant of Unix, so the preprocessor defines ``unix``, ``__unix`` and ``__unix__`` are always present when compiling code with Emscripten.
- * Emscripten uses Clang/LLVM as its underlying codegen compiler, so the preprocessor defines ``__llvm__`` and ``__clang__`` are defined, and the preprocessor defines ``__clang_major__``, ``__clang_minor__`` and ``__clang_patchlevel__`` indicate the version of Clang that is used.
- * Clang/LLVM is GCC-compatible, so the preprocessor defines ``__GNUC__``, ``__GNUC_MINOR__`` and ``__GNUC_PATCHLEVEL__`` are also defined to represent the level of GCC compatibility that Clang/LLVM provides.
- * The preprocessor string ``__VERSION__`` indicates the GCC compatible version, which is expanded to also show Emscripten version information.
- * Likewise, ``__clang_version__`` is present and indicates both Emscripten and LLVM version information.
- * Emscripten is a 32-bit platform, so ``size_t`` is a 32-bit unsigned integer, ``__POINTER_WIDTH__=32``, ``__SIZEOF_LONG__=4`` and ``__LONG_MAX__`` equals ``2147483647L``.
- * When targeting SSEx SIMD APIs using one of the command line compiler flags ``-msse``, ``-msse2``, ``-msse3``, ``-mssse3``, or ``-msse4.1``, one or more of the preprocessor flags ``__SSE__``, ``__SSE2__``, ``__SSE3__``, ``__SSSE3__``, ``__SSE4_1__`` will be present to indicate available support for these instruction sets.
- * If targeting the pthreads multithreading support with the compiler & linker flag ``-pthread``, the preprocessor define ``__EMSCRIPTEN_PTHREADS__`` will be present.
+* The preprocessor define ``__EMSCRIPTEN__`` is always defined when compiling programs with Emscripten.
+* The preprocessor variables ``__EMSCRIPTEN_MAJOR__``, ``__EMSCRIPTEN_MINOR__``
+  and ``__EMSCRIPTEN_TINY__`` are defined in ``emscripten/version.h`` and
+  specify, as integers, the currently used Emscripten compiler version.
+* Emscripten behaves like a variant of Unix, so the preprocessor defines ``unix``, ``__unix`` and ``__unix__`` are always present when compiling code with Emscripten.
+* Emscripten uses Clang/LLVM as its underlying codegen compiler, so the preprocessor defines ``__llvm__`` and ``__clang__`` are defined, and the preprocessor defines ``__clang_major__``, ``__clang_minor__`` and ``__clang_patchlevel__`` indicate the version of Clang that is used.
+* Clang/LLVM is GCC-compatible, so the preprocessor defines ``__GNUC__``, ``__GNUC_MINOR__`` and ``__GNUC_PATCHLEVEL__`` are also defined to represent the level of GCC compatibility that Clang/LLVM provides.
+* The preprocessor string ``__VERSION__`` indicates the GCC compatible version, which is expanded to also show Emscripten version information.
+* Likewise, ``__clang_version__`` is present and indicates both Emscripten and LLVM version information.
+* Emscripten is a 32-bit platform, so ``size_t`` is a 32-bit unsigned integer, ``__POINTER_WIDTH__=32``, ``__SIZEOF_LONG__=4`` and ``__LONG_MAX__`` equals ``2147483647L``.
+* When targeting SSEx SIMD APIs using one of the command line compiler flags ``-msse``, ``-msse2``, ``-msse3``, ``-mssse3``, or ``-msse4.1``, one or more of the preprocessor flags ``__SSE__``, ``__SSE2__``, ``__SSE3__``, ``__SSSE3__``, ``__SSE4_1__`` will be present to indicate available support for these instruction sets.
+* If targeting the pthreads multithreading support with the compiler & linker flag ``-pthread``, the preprocessor define ``__EMSCRIPTEN_PTHREADS__`` will be present.
 
 
 Using a compiler wrapper
@@ -438,8 +438,7 @@ Troubleshooting
   ``emmake``/``emconfigure`` should avoid this by setting the env var RANLIB,
   but a build system might have it hardcoded, or require you to
   `pass an option <https://github.com/emscripten-core/emscripten/issues/9705#issuecomment-548199052>`_.
--
-  The compilation error ``multiply defined symbol`` indicates that the project has linked a particular static library multiple times. The project will need to be changed so that the problem library is linked only once.
+- The compilation error ``multiply defined symbol`` indicates that the project has linked a particular static library multiple times. The project will need to be changed so that the problem library is linked only once.
 
   .. note:: You can use ``llvm-nm`` to see which symbols are defined in each object file.
 

site/source/docs/compiling/Deploying-Pages.rst

@@ -82,17 +82,17 @@ To provide the best possible user experience, make sure that the different ways
 
 - If a particular browser is known to not be supported, resist the temptation to read ``navigator.userAgent`` field to gate users with that browser, if at all possible. For example, if your page needs WebGL 2 but Safari is known not to support it, do not exclude out Safari users with a following type of check:
 
-   .. code:: js
+  .. code:: js
 
     if (navigator.userAgent.indexOf('Safari') != -1) alert('Your browser does not support WebGL 2!');
 
-but instead, detect the actual errors:
+  but instead, detect the actual errors:
 
-   .. code:: js
+  .. code:: js
 
     if (!canvas.getContext('webgl2')) alert('Your browser does not support WebGL 2!'); // And look for webglcontextcreationerror here for an error reason.
 
-This way the page will be future compatible once support for the particular feature later becomes available.
+  This way the page will be future compatible once support for the particular feature later becomes available.
 
 - Test various failure cases up front by simulating different issues and browser limitations. For example, on Firefox, it is possible to manually disable WebGL 2 by navigating to ``about:config`` and setting the preference ``webgl.enable-webgl2`` to ``false``. This allows you to debug what kind of error reporting your page will present to the user in such a scenario. To disable WebGL support altogether for testing purposes, set the preference ``webgl.disabled`` to ``true``.
 
@@ -108,11 +108,11 @@ This way the page will be future compatible once support for the particular feat
 
 - Catch all exceptions that come from within entry points that call to compiled asm.js and WebAssembly code. There are three distinct exception classes that compiled code can throw:
 
-    1. C++ exceptions that are represented by a thrown integer and not caught by the C++ program. This integer points to a memory location in the application heap that contains pointer to the thrown object.
+  1. C++ exceptions that are represented by a thrown integer and not caught by the C++ program. This integer points to a memory location in the application heap that contains pointer to the thrown object.
 
-    2. Exceptions caused by Emscripten runtime calling the ``abort()`` function. These correspond to a fatal error that execution of the compiled code cannot recover from. For example, this can occur when calling an invalid function pointer.
+  2. Exceptions caused by Emscripten runtime calling the ``abort()`` function. These correspond to a fatal error that execution of the compiled code cannot recover from. For example, this can occur when calling an invalid function pointer.
 
-    3. Traps caused by compiled WebAssembly code. These correspond to fatal errors coming from the WebAssembly VM. This can occur for example when performing an integer division by zero, or when converting a large floating point number to an integer when the float is out of range of the numbers representable by that integer type.
+  3. Traps caused by compiled WebAssembly code. These correspond to fatal errors coming from the WebAssembly VM. This can occur for example when performing an integer division by zero, or when converting a large floating point number to an integer when the float is out of range of the numbers representable by that integer type.
 
 - Implement a final "catch all" error handler on the page by implementing a ``window.onerror`` script. This will be called as a last resort if no other source handled an exception that was raised on the page. See `window.onerror <https://developer.mozilla.org/en-US/docs/Web/API/GlobalEventHandlers/onerror#window.onerror>`_ documentation on MDN.
 

site/source/docs/compiling/Running-html-files-with-emrun.rst

@@ -27,13 +27,13 @@ Using *emrun* is simple:
 
 #. Rebuild your Emscripten application and add the ``--emrun`` :ref:`linker flag <emcc-emrun>`.
 
-  This flag injects code into the generated :ref:`Module` to enable capture of ``stdout``, ``stderr`` and ``exit()``.
+   This flag injects code into the generated :ref:`Module` to enable capture of ``stdout``, ``stderr`` and ``exit()``.
 
-  .. note:: If you skip this step, you can still run any **.html** file with *emrun*, but the capture will not work.
+   .. note:: If you skip this step, you can still run any **.html** file with *emrun*, but the capture will not work.
 
 #. Open a terminal, navigate to the build output directory, and call ``emrun page.html``.
 
-  This will spawn a new web server to host the page and launch your default system browser to visit that page. *emrun* will block until the page calls ``exit(returncode)``, after which it will quit back to shell with the given process exit code.
+   This will spawn a new web server to host the page and launch your default system browser to visit that page. *emrun* will block until the page calls ``exit(returncode)``, after which it will quit back to shell with the given process exit code.
 
 
 Choosing the browser to run