Clean the documentation

README.md

@@ -5,18 +5,18 @@ _Ready to use AppImages of Python are available as GitHub [releases][RELEASES]._
 
 ## Quickstart
 
-We provide relocatable Python runtimes as [AppImages][APPIMAGE] for Linux
-systems. These runtimes are extracted from [Manylinux][MANYLINUX] Docker images,
-and they are available as GitHub [releases][RELEASES].  Our Python AppImages are
-updated weekly, on every Sunday.
+We provide relocatable Python runtimes in the form of [AppImages][APPIMAGE] for
+Linux systems. These runtimes are extracted from [Manylinux][MANYLINUX] Docker
+images and are available as GitHub [releases][RELEASES]. Our Python AppImages
+are updated weekly, on every Sunday.
 
-Instructions for _installing_ and running _Python AppImages_ are provided on
+Instructions for _installing_ and running _Python AppImages_ can be found on
 [Read the Docs][READTHEDOCS].
 
-In addition, the online documentation describes the [`python-appimage`][PYPI]
-utility, for application developers. This utility can facilitate the building of
-Python apps, given an existing Python AppImage and a recipe folder.
-[Examples][APPLICATIONS] of recipes are available from GitHub.
+The online documentation also describes the [`python-appimage`][PYPI] utility
+for application developers. This utility can facilitate the development of
+Python applications, provided you have an existing Python AppImage and a recipe
+folder. [Examples][APPLICATIONS] of recipes are available on GitHub.
 
 
 ## Projects using [`python-appimage`][GITHUB]

docs/include/references.md

@@ -12,7 +12,9 @@
 [GITHUB]: {{ config.repo_url }}
 [LINUXDEPLOY]: https://github.com/linuxdeploy/linuxdeploy/
 [MANYLINUX]: https://github.com/pypa/manylinux/
+[NUMPY]: https://numpy.org/
 [PATCHELF]: https://github.com/NixOS/patchelf/
+[PEP_425]: https://peps.python.org/pep-0425/
 [PYPI]: https://pypi.org/project/python-appimage/
 [RELEASES]: {{ config.repo_url }}releases/
 [SHEBANG]: https://en.wikipedia.org/wiki/Shebang_(Unix)/

docs/mkdocs.yml

@@ -10,7 +10,7 @@ docs_dir: src
 
 nav:
   - Python AppImages: index.md
-  - Developers corner: apps.md
+  - Developers' corner: apps.md
 
 theme:
   name: readthedocs

docs/src/apps.md

@@ -10,157 +10,169 @@
 {% include "references.md" %}
 
 
-# Developers corner
+# Developers' corner
 
-Python [AppImages][APPIMAGE] are built with the `python-appimage` utility,
-available from [PyPI][PYPI]. This utility can also help packaging Python based
-applications as AppImages, using an existing Python AppImage and a recipe
+Python [AppImages][APPIMAGE] are created using the `python-appimage` utility,
+which is available on [PyPI][PYPI]. This utility can also be used to package
+Python-based applications as AppImages using an existing AppImage and a recipe
 folder.
 
 !!! Caution
     The `python-appimage` utility can only package applications that can be
-    directly installed with `pip`. For more advanced usage, one needs to extract
-    the Python AppImage and to edit it, e.g. as explained in the [Advanced
-    installation](index.md#advanced-installation) section.  Additional details
-    on this use case are provided [below](#advanced-packaging).
+    installed directly with `pip`. For more advanced usage, it is necessary to
+    extract and edit the Python AppImage, as explained in the [Advanced
+    installation](index.md#advanced-installation) section. Further details on
+    this use case can be found [below](#advanced-packaging).
 
 
 ## Building a Python AppImage
 
-The primary scope of `python-appimage` is to relocate an existing Python
-installation inside an AppDir, and to build the corresponding AppImage.  For
-example, the following
+The primary purpose of `python-appimage` is to relocate an existing Python
+installation to an AppDir and build the corresponding AppImage. For example, the
+command
 
 ```bash
 python-appimage build local -p $(which python2)
 ```
 
-should build an AppImage of your local Python 2 installation, provided that it
+should create an AppImage of your local Python installation, provided that it
 exists.
 
 !!! Tip
-    Help on available arguments and options to `python-appimage` can be obtained
-    with the `-h` flag. For example, `python-appimage build local -h` provides
-    help on local builds.
+    Help on the available arguments and options for `python-appimage` can be
+    obtained by using the `-h` flag. For example, running
+    `python-appimage build local -h` provides help on local builds.
 
 
 {{ begin(".capsule") }}
 ### Auxiliary tools
 
 The `python-appimage` utility relies on auxiliary tools that are downloaded and
-installed at runtime, on need. Those are [appimagetool][APPIMAGETOOL] for
-building AppImages, and [patchelf][PATCHELF] in order to edit ELFs runtime paths
-(`RPATH`). Auxiliary tools are installed to the the user space. One can get
-their location with the `which` command word. For example,
+installed on demand during application execution. These are
+[appimagetool][APPIMAGETOOL], which is used to build AppImages, and
+[patchelf][PATCHELF], which is used to edit runtime paths (`RPATH`) in ELF
+files. These auxiliary tools are installed in the application cache. Their
+location can be found using the `which` command. For example, the command
 
 ```bash
 python-appimage which appimagetool
 ```
 
-returns the location of `appimagetool`, if it has been installed. If not, the
-`install` command word can be used in order to trigger its installation.
+returns the location of [appimagetool][APPIMAGETOOL] if it has been installed.
+If not, the `install` command can be used to trigger its installation.
 {{ end(".capsule") }}
 
 
 ## Manylinux Python AppImages
 
-AppImages of your local `python` are unlikely to be portable, except if you run
-an ancient Linux distribution. Indeed, a core component preventing portability
-across Linuses is the use of different versions of the `glibc` system library.
-Hopefully, `glibc` is highly backward compatible. Therefore, a simple
-work-around is to compile binaries using the oldest Linux distro you can afford
-to.  This is the strategy used for creating portable AppImages, as well as for
-distributing Python site packages as ready-to-use binary [wheels][WHEELS].
+AppImages of your local `python` are unlikely to be portable, unless you are
+running an outdated Linux distribution. A core component that prevents
+portability across Linux distributions is the use of different versions of the
+`glibc` system library. Fortunately, `glibc` is highly backward compatible.
+Therefore, a simple workaround is to compile binaries using the oldest Linux
+distribution you can. This strategy is used to create portable AppImages and to
+distribute Python site packages as ready-to-use binary [wheels][WHEELS].
 
 The Python Packaging Authority (PyPA) has defined standard platform tags for
-building Python site packages, labelled [manylinux][MANYLINUX].  These build
-platforms are available as Docker images with various versions of Python already
-installed. The `python-appimage` utility can be used to package those installs
-as AppImages. For example, the following command
+building Python site packages labelled [Manylinux][MANYLINUX]. These build
+platforms are available as Docker images, with different versions of Python
+already installed. The `python-appimage` utility can be used to package these
+installations as AppImages. For example, the following command
 
 ```bash
-python-appimage build manylinux 2014_x86_64 cp310-cp310
+python-appimage build manylinux 2014_x86_64 cp313-cp313
 ```
 
-should build an AppImage of Python 3.10 using the CPython (_cp310-cp310_)
-install found in the `manylinux2014_x86_64` Docker image.
+should build an AppImage of Python __3.13__ using the CPython (__cp313-cp313__)
+installation found in the `manylinux2014_x86_64` Docker image.
 
 !!! Note
-    Docker needs to be already installed on your system in order to build
-    Manylinux Python images. However, the command above can be run on the host.
-    That is, you need **not** to explictly shell inside the manylinux Docker
-    image.
+    From version `1.4.0` of `python-appimage` onwards, Docker is **no longer**
+    required to build the Manylinux Python images. Cross-building is also
+    supported, for example producing an `aarch64` Python image from an `x86_64`
+    host.
+
+!!! Warning
+    Creating multiple Manylinux Python images can significantly increase the
+    size of the application cache. This can be managed using the
+    `python-appimage cache` command.
 
 !!! Tip
-    A compilation of ready-to-use Manylinux Python AppImages is available from
-    the [releases][RELEASES] area of the `python-appimage` [GitHub
+    A compilation of ready-to-use Manylinux Python AppImages is available in the
+    [releases][RELEASES] section of the `python-appimage` [GitHub
     repository][GITHUB]. These AppImages are updated weekly, on every Sunday.
 
+!!! Tip
+    Instead of an AppImage, the `python-appimage build manylinux` command can
+    produce either an `AppDir` or a bare tarball (i.e. without the AppImage
+    layer) of a Manylinux Python installation. See the `-b` and `-n` command
+    line options for more information.
 
 ## Simple packaging
 
-The `python-appimage` utility can also be used in order to build simple
-applications, that can be `pip` installed. The syntax is
+The `python-appimage` utility can also be used to package simple AppImage
+applications, whose dependencies can be installed using `pip`. The syntax is
 
 ```bash
-python-appimage build app -p 3.10 /path/to/recipe/folder
+python-appimage build app -p 3.13 /path/to/recipe/folder
 ```
 
-in order to build a Python 3.10 based application from a recipe folder.
-Examples of recipes can be found on GitHub in the [applications][APPLICATIONS]
-folder.  The recipe folder contains:
+to build a Python 3.13-based application from a recipe folder. Examples of
+recipes can be found in the [applications][APPLICATIONS] folder on GitHub. The
+recipe folder contains
 
 - the AppImage metadata (`application.xml` and `application.desktop`),
 - an application icon (e.g. `application.png`),
-- a Python requirements file (`requirements.txt`)
+- a Python requirements file (`requirements.txt`),
 - an entry point script (`entrypoint.sh`).
 
-Additional information on metadata can be found in the AppImage documentation.
-That is, for [desktop][APPIMAGE_DESKTOP] and [AppStream XML][APPIMAGE_XML]
-files. The `requirements.txt` file allows to specify additional site packages
-to be bundled in the AppImage, using `pip`.
+Further information on metadata can be found in the AppImage documentation
+(e.g., regarding [desktop][APPIMAGE_DESKTOP] and [AppStream XML][APPIMAGE_XML]
+files). The `requirements.txt` file enables additional site packages to be
+specified for bundling in the AppImage using `pip`.
 
 !!! Caution
-    For the application to be portable, site packages bundled in the AppImage,
-    as well as their dependencies, must must be available as binary wheels, or
-    be pure Python packages.
+    In order for the application to be portable, the site packages bundled in
+    the AppImage and their dependencies must be available as binary wheels or
+    pure Python packages.
 
-    If a **C extension** is bundled from **source**, then it will likely **not
-    be portable**, as further discussed in the [Advanced
+    If a **C extension** is bundled from **source**, it will likely **not be
+    portable**; this is discussed further in the [Advanced
     packaging](#advanced-packaging) section.
 
 !!! Tip
-    Some site packages are available only for specific Manylinux tags. This can
-    be cross-checked by browsing the `Download files` section on the package's
-    PyPI page.
+    Some site packages are only available for specific Manylinux tags. You can
+    check this by browsing the `Download files` section on the package's PyPI
+    page.
 
 !!! Tip
-    Since version 1.2, `python-appimage` allows to specify local requirements as
-    well, using the `local+` tag (see
-    [PR49](https://github.com/niess/python-appimage/pull/49)). Note however that
-    this performs a direct copy of the local package, which has several
-    limitations.
+    Since version 1.2, `python-appimage` allows local requirements to be
+    specified using the `local+` tag (see
+    [PR49](https://github.com/niess/python-appimage/pull/49)). Please note,
+    however, that this involves directly copying the local package, which has
+    several limitations.
 
 {{ begin(".capsule") }}
 ### Entry point script
 
 {% raw %}
-The entry point script deserves some additional explanations. This script allows
-to customize the startup of your application. A typical `entrypoint.sh` script
-would look like
+The entry point script deserves some additional explanations. This script lets
+you customise your application's startup. A typical `entrypoint.sh` script would
+look like this
 
 ```bash
 {{ python-executable }} ${APPDIR}/opt/python{{ python-version }}/bin/my_app.py "$@"
 ```
 
-where `my_app.py` is the application startup script, installed by `pip`. As can
-be seen from the previous example, the `entrypoint.sh` script recognises some
-particular variables, nested between double curly braces, `{{ }}`. Those
-variables are listed in the table hereafter. In addition, usual [AppImage
-environement variables][APPIMAGE_ENV] can be used as well, if needed. For
-example, `$APPDIR` points to the AppImage mount point at runtime.
+where `my_app.py` is the application startup script installed by `pip`. As can
+be seen from the previous example, the `entrypoint.sh` script recognises
+particular variables nested between double curly braces (`{{}}`). These
+variables are listed in the table below. In addition, the usual [AppImage
+environement variables][APPIMAGE_ENV] can be used if needed. For instance,
+`$APPDIR` points to the AppImage mount point at runtime.
 {% endraw %}
 
+
 | variable             | Description                                                   |
 |----------------------|---------------------------------------------------------------|
 | `architecture`       | The AppImage architecture, e.g. `x86_64`.                     |
@@ -173,20 +185,20 @@ example, `$APPDIR` points to the AppImage mount point at runtime.
 
 {% raw %}
 !!! Note
-    By default, Python AppImages are not isolated from the user space, nor from
-    Python specific environment variables, the like `PYTHONPATH`. Depending on
-    your use case, this can be problematic.
+    By default, Python AppImages are not isolated from user space or
+    Python-specific environment variables such as `PYTHONPATH`. Depending on
+    your use case, this can cause problems.
 
-    The runtime isolation level can be changed by adding the `-E`, `-s` or `-I`
-    options, when invoking the runtime.  For example,
-    `{{ python-executable }} -I` starts a fully isolated Python instance.
+    You can change the isolation level by adding the `-E`, `-s` or `-I` options
+    when invoking the runtime. For example, `{{ python-executable }} -I` starts
+    a fully isolated Python instance.
 {% endraw %}
 
 ### Bundling data files
 
-`python-appimage` is also capable of bundling in auxilliary data files directly
-into the resulting AppImage. `-x/--extra-data` switch exists for that task.
-Consider following example.
+`python-appimage` is also capable of bundling auxiliary data files directly into
+the resulting AppImage. The `-x/--extra-data` switch is used for this purpose.
+Consider the following example.
 
 ```bash
 echo -n "foo" > foo
@@ -195,10 +207,10 @@ echo -n "baz" > bar/baz
 python-appimage [your regular parameters] -x foo bar/*
 ```
 
-User data included in such a way becomes accessible to the Python code
-contained within the AppImage in a form of regular files under the directory
-pointed to by `APPDIR` environment variable. Example of Python 3 script
-that reads these exemplary files is presented below.
+In this way, user data becomes accessible to the Python code contained within
+the AppImage as regular files under the directory pointed to by the `APPDIR`
+environment variable. An example of a Python 3 script that reads these files is
+presented below.
 
 ```python
 import os, pathlib
@@ -206,7 +218,7 @@ for fileName in ("foo", "baz"):
   print((pathlib.Path(os.getenv("APPDIR")) / fileName).read_text())
 ```
 
-Above code, when executed, would print following output.
+When executed, the above code would produce the following output.
 
 ```bash
 foo
@@ -215,37 +227,36 @@ baz
 
 ## Advanced packaging
 
-In more complex cases, e.g. if your application relies on external C libraries
-not bundled with the Python runtime, then the simple packaging scheme described
-previously will fail. Indeed, this falls out of the scope of `python-appimage`,
-whose main purpose it to relocate an existing Python install. In this case, you
-might rather refer to the initial AppImage [Packaging
-Guide][APPIMAGE_PACKAGING], and use alternative tools like
+In more complex cases, for example if your application relies on external C
+libraries that are not bundled with the Python runtime, the simple packaging
+scheme described previously will not work. This falls outside the scope of
+`python-appimage`, which is primarily intended for relocating an existing Python
+installation. In this case, you may wish to refer to the initial AppImage
+[Packaging Guide][APPIMAGE_PACKAGING], and use alternative tools such as
 [linuxdeploy][LINUXDEPLOY].
 
-However, `python-appimage` can still be of use in more complex cases by
-extracting its AppImages to an AppDir, as discussed in the [Advanced
-installation](index.md#advanced-installation) section. The extracted AppImages
-contain a relocatable Python runtime, that can be used as a starting base for
-building more complex AppImages.
+However, `python-appimage` can still be useful in more complex cases, as it can
+generate a base AppDir containing a relocatable Python runtime (e.g., using the
+`-n` option). This can then serve as a starting point to create more complex
+AppImages.
 
 !!! Tip
-    In some cases, a simple workaround to missing external libraries can be to
-    fetch portable versions of those from a Manylinux distro, and to bundle them
-    under `AppDir/usr/lib`. You might also need to edit their dynamic section,
-    e.g.  using [`patchelf`][PATCHELF], which is installed by `python-appimage`.
+    In some cases, a simple workaround for missing external libraries is to
+    download portable versions of them from a Manylinux distribution and bundle
+    them in `AppDir/usr/lib`. You may also need to edit the dynamic section
+    using [`patchelf`][PATCHELF], which is installed by `python-appimage`.
 
 
 {{ begin(".capsule") }}
 ### C extension modules
 
-If your application relies on C extension modules, they need to be compiled on a
-Manylinux distro in order to be portable. In addition, their dependencies need
-to be bundled as well. In this case, you might better start by building a binary
-wheel of your package, using tools like [Auditwheel][AUDITWHEEL] which can
-automate some parts of the packaging process. Note that `auditwheel` is already
+If your application relies on C extension modules, these must be compiled on a
+Manylinux distribution in order to be portable. Their dependencies also need to
+be bundled. In this case, it would be better to start by building a binary wheel
+of your package using tools like [Auditwheel][AUDITWHEEL], which can automate
+some parts of the packaging process. Please note that `auditwheel` is already
 installed on the Manylinux Docker images.
 
-Once you have built a binary wheel of your package, it can be used with
-`python-appimage` in order to package your application as an AppImage.
+Once you have built a binary wheel of your package, you can use it with
+`python-appimage` to package your application as an AppImage.
 {{ end(".capsule") }}

docs/src/index.md

@@ -15,8 +15,8 @@
 # Python AppImages
 
 We provide relocatable Python runtimes for _Linux_ systems, as
-[AppImages][APPIMAGE]. These runtimes have been extracted from
-[manylinux][MANYLINUX] Docker images.
+[AppImages][APPIMAGE]. These runtimes have been extracted from a variety of
+[Manylinux][MANYLINUX] Docker images.
 {{ "" | id("append-releases-list") }}
 
 ## Basic installation
@@ -35,23 +35,24 @@ chmod +x python3.10.2-cp310-cp310-manylinux2014_x86_64.AppImage
 
 !!! Note
     As can be seen from the previous [example](#basic-installation-example), the
-    AppImage name contains several informations. That are, the Python full
-    version ({{ "3.10.2" | id("example-full-version") }}), the CPython tag
-    ({{ "cp310-cp310" | id("example-python-tag") }}), the Linux compatibility
-    tag ({{ "manylinux2014" | id("example-linux-tag") }}) and the machine
-    architecture ({{ "x86_64" | id("example-arch-tag") }}).
+    AppImage name contains several pieces of information. This includes the
+    Python full version ({{ "3.10.2" | id("example-full-version") }}), the
+    [CPython tag][PEP_425] ({{ "cp310-cp310" | id("example-python-tag") }}), the
+    [Linux compatibility tag][MANYLINUX] ({{ "manylinux2014" |
+    id("example-linux-tag") }}) and the machine architecture ({{ "x86_64" |
+    id("example-arch-tag") }}).
 
 !!! Caution
-    One needs to **select an AppImage** that matches **system requirements**. A
-    summmary of available Python AppImages is provided at the
-    [bottom](#available-python-appimages) of this page.
+    It is essential to **select an AppImage** that aligns with the **system's
+    specifications**. An overview of the available Python AppImages is provided
+    at the [bottom](#available-python-appimages) of this page.
 
 
 {{ begin(".capsule") }}
 ### Creating a symbolic link
 
-Since AppImages native names are rather lengthy, one might create a symbolic
-link, e.g. as
+As AppImages' native names are quite lengthy, it might be relevant to create a
+symbolic link, for example as
 
 {{ begin("#basic-installation-example-symlink") }}
 ```bash
@@ -59,23 +60,23 @@ ln -s python3.10.2-cp310-cp310-manylinux2014_x86_64.AppImage python3.10
 ```
 {{ end("#basic-installation-example-symlink") }}
 
-Then, executing the AppImage as
-{{ "`./python3.10`" | id("basic-installation-example-execution") }} should
-start a Python interactive session on _almost_ any Linux, provided that **fuse**
-is supported.
+Executing the AppImage as {{ "`./python3.10`" |
+id("basic-installation-example-execution") }} should then start a Python
+interactive session on almost any Linux distribution, provided that **fuse** is
+supported.
 {{ end(".capsule") }}
 
 !!! Tip
-    Fuse is not supported on Windows Subsytem for Linux v1 (WSL1), preventing
-    AppImages direct execution. Yet, one can still extract the content of Python
-    AppImages and use them, as explained in the [Advanced
-    installation](#advanced-installation) section.
+    Fuse is not supported on Windows Subsystem for Linux v1 (WSL1), which
+    prevents the direct execution of AppImages. However, it is still possible to
+    extract the contents of Python AppImages and use them, as explained in the
+    [Advanced installation](#advanced-installation) section.
 
 
 ## Installing site packages
 
-Site packages can be installed using `pip`, distributed with the AppImage. For
-example, the following
+Site packages can be installed using `pip`, which is distributed with Python
+AppImages. For example, the following command
 
 {{ begin("#site-packages-example") }}
 ```bash
@@ -83,23 +84,22 @@ example, the following
 ```
 {{ end("#site-packages-example") }}
 
-installs the numpy package, where it is assumed that a symlink to the AppImage
-has been previously created. When using the **basic installation** scheme, by
-default Python packages are installed to your **user space**, i.e. under
-`~/.local` on Linux.
+installs the [numpy][NUMPY] package, assuming that a symlink to the AppImage has
+been created beforehand. When using this **basic installation** scheme, Python
+packages are installed by default to your **user space** (i.e. under `~/.local`
+on Linux).
 
 !!! Note
-    AppImage are read-only. Therefore, site packages cannot be directly
-    installed to the AppImage. However, the AppImage can be extracted, as
+    AppImages are read-only. Therefore, site packages cannot be installed
+    directly to the Python AppImage. However, the AppImage can be extracted, as
     explained in the [Advanced installation](#advanced-installation) section.
 
 
 {{ begin(".capsule") }}
 ### Alternative site packages location
 
-One can
-specify an alternative installation directory for site packages using the
-`--target` option of pip. For example, the following
+The `--target option` of pip can be used to specify an alternative installation
+directory for site packages. For example, the following command
 
 {{ begin("#site-packages-example-target") }}
 ```bash
@@ -107,7 +107,9 @@ specify an alternative installation directory for site packages using the
 ```
 {{ end("#site-packages-example-target") }}
 
-installs the numpy package besides the AppImage, in a `packages` folder.
+installs the [numpy][NUMPY] package in the `packages` folder, besides the
+AppImage.
+
 {{ end(".capsule") }}
 
 !!! Tip
@@ -116,33 +118,33 @@ installs the numpy package besides the AppImage, in a `packages` folder.
     `PYTHONPATH` environment variable.
 
 !!! Caution
-    While Python AppImages are relocatable, site packages might not be. In
-    particular, packages installing executable Python scripts assume a fix
-    location of the Python runtime. If the Python AppImage is moved, then these
-    scripts will fail. This can be patched by editing the script
-    [shebang][SHEBANG], or be reinstalling the corresponding package.
+    Although Python AppImages are relocatable, site packages may not be. In
+    particular, packages that install executable Python scripts assume a fixed
+    location for the Python runtime. If the Python AppImage is moved, these
+    scripts will fail. This can be resolved by either editing the script
+    [shebang][SHEBANG] or reinstalling the corresponding package.
 
 
 ## Isolating from the user environment
 
 By default, Python AppImages are not isolated from the user environment. For
 example, packages located under `~/.local/lib/pythonX.Y/site-packages` are
-loaded prior to AppImage's (system) ones.  Note that this is the usual Python
-runtime behaviour. However, it can be conflictual for some applications.
+loaded before the AppImage's ones. Note that this is the standard Python runtime
+behaviour. However, this can be conflictual for some applications.
 
-In order to isolate your application from the user environment, the Python
-runtime provides the `-E`, `-s` and `-I` options. For example, invoking a Python
-AppImage as {{ "`./python3.10 -s`" | id("user-isolation-example") }} prevents
-the loading of user site packages (located under `~/.local`). Additionaly, the
-`-E` option disables Python related environment variables. In particular, it
-prevents packages under `PYTHONPATH` to be loaded. The `-I` option triggers both
-`-E` and `-s`.
+To isolate your application from the user environment, the Python runtime
+provides the `-E`, `-s` and `-I` options. For example, running {{ "`./python3.10
+-s`" | id("user-isolation-example") }} prevents the loading of user site
+packages located under `~/.local`. Additionally, the `-E` option disables
+Python-related environment variables. In particular, it prevents packages under
+`PYTHONPATH` from being loaded. The `-I` option triggers both the `-E` and `-s`
+options.
 
 
 ## Using a virtual environement
 
-Isolation can also be achieved with a [virtual environment][VENV]. Python
-AppImages can create a `venv` using the standard syntax, e.g. as
+[Virtual environments][VENV] can also be used to achieve isolation. For example,
+Python AppImages can create a `venv` using the standard syntax, as
 
 {{ begin("#venv-example") }}
 ```bash
@@ -150,15 +152,16 @@ AppImages can create a `venv` using the standard syntax, e.g. as
 ```
 {{ end("#venv-example") }}
 
-Note that moving the base Python AppImage to another location breaks the virtual
-environment. This can be patched by editing symbolic links under `venv/bin`, as
-well as the `home` variable in `venv/pyvenv.cfg`. The latter must point to the
-AppImage directory.
+Please note that moving the base Python AppImage to a different location will
+break the virtual environment. This can be resolved by editing the symbolic
+links in `venv/bin`, as well as the `home` variable in `venv/pyvenv.cfg`. The
+latter must point to the AppImage directory.
 
 !!! Tip
-    Old Python AppImages, created before version 1.1, fail setting up `pip`
-    automaticaly during `venv` creation. However, this can be patched by calling
-    `ensurepip` from within the `venv`, after its creation.  For example, as
+    Old Python AppImages created before version 1.1 fail to set up `pip`
+    automatically during `venv` creation. However, this can be resolved by
+    calling `ensurepip` within the virtual environment after its creation. For
+    example, as
 
 ```bash
 source /path/to/new/virtual/environment/bin/activate
@@ -170,10 +173,10 @@ python -m ensurepip
 ## Advanced installation
 
 The [basic installation](#basic-installation) scheme described previously has
-some limitations when using Python AppImages as a runtime. For example,  site
-packages need to be installed to a separate location. This can be solved by
-extracting a Python AppImage to an `*.AppDir` directory, e.g. as
-
+certain limitations when Python AppImages are used as the runtime environment.
+For example, site packages need to be installed in a different location. This
+issue can be resolved by extracting a Python AppImage to an `AppDir`
+directory, e.g. as
 
 {{ begin("#advanced-installation-example") }}
 ```bash
@@ -185,32 +188,32 @@ ln -s python3.10.2-cp310-cp310-manylinux2014_x86_64.AppDir/AppRun python3.10
 ```
 {{ end("#advanced-installation-example") }}
 
-Then, by default **site packages** are installed to the extracted **AppDir**,
-when using `pip`. In addition, executable scripts installed by `pip` are patched
-in order to use relative [shebangs][SHEBANG].  Consequently, the AppDir can be
-freely moved around.
+Then, by default, **site packages** are installed to the extracted `AppDir`
+when using `pip`. Additionally, executable scripts installed by `pip` are
+patched to use relative [shebangs][SHEBANG]. Consequently, the `AppDir` can be
+moved around freely.
 
 !!! Note
-    Python AppDirs follow the [manylinux][MANYLINUX] installation scheme.
-    Executable scripts are installed under `AppDir/opt/pythonX.Y/bin` where _X_
-    and _Y_ in _pythonX.Y_ stand for the major and minor version numbers. Site
-    packages are located under
-    `AppDir/opt/pythonX.Y/lib/pythonX.Y/site-packages`. For convenience, `pip`
-    installed applications are also mirrored under `AppDir/usr/bin`, using
-    symbolic links.
+    Python `AppDirs` follow the [Manylinux][MANYLINUX] installation scheme.
+    Executable scripts are installed under the `AppDir/opt/pythonX.Y/bin`
+    directory, where _X_ and _Y_ represent the major and minor version numbers,
+    respectively. Site packages are located under
+    `AppDir/opt/pythonX.Y/lib/pythonX.Y/site-packages`. For convenience,
+    applications installed using `pip` are also mirrored under `AppDir/usr/bin`
+    using symbolic links.
 
 !!! Tip
-    As for Python AppImages, by default the extracted runtime is [not isolated
-    from the user environment](#isolating-from-the-user-environment). This
+    As for Python AppImages, the extracted runtime is [not isolated from the
+    user environment](#isolating-from-the-user-environment) by default. This
     behaviour can be changed by editing the `AppDir/usr/bin/pythonX.Y` wrapper
-    script, and by adding the `-s`, `-E` or `-I` option at the very bottom,
-    where Python is invoked.
+    script and adding the `-s`, `-E` or `-I` option to the line invoking Python
+    (at the end of the script).
 
 
 {{ begin(".capsule") }}
 ### Repackaging the AppImage
 
-An extracted AppDir can be re-packaged as an AppImage using
+An extracted `AppDir` can be re-packaged as an AppImage using
 [appimagetool][APPIMAGETOOL], e.g. as
 
 
@@ -227,21 +230,21 @@ chmod +x appimagetool-x86_64.AppImage
 ```
 {{ end("#repackaging-example") }}
 
-This allows to customize your Python AppImage, for example by adding your
-preferred site packages.
+This allows you to personalise your Python AppImage by adding your preferred
+site packages, for example.
 {{ end(".capsule") }}
 
 !!! Note
-    Python AppImages can also be used for packaging Python based applications,
-    as AppImages. Additional details are provided in the [developers
+    Python AppImages can also be used to package Python-based applications as
+    AppImages. Further information can be found in the [developers'
     section](apps).
 
 
 ## Available Python AppImages
 
-A summary of available Python AppImages [releases][RELEASES] is provided in the
-[table](#appimages-download-links) below. Clicking on a badge should download
-the corresponding AppImage.
+The [table](#appimages-download-links) below provides a summary of the available
+Python AppImage [releases][RELEASES]. Clicking on a badge should download the
+corresponding AppImage.
 
 {{ begin("#suggest-appimage-download") }}
 !!! Caution

docs/src/js/index.js

@@ -75,7 +75,7 @@ $.getJSON("https://api.github.com/repos/niess/python-appimage/releases").done(fu
             elements.push(`<a href="${release.url}">${release.version}</a>`)
         }
         $("#append-releases-list").html(
-            " Available Python versions are " +
+            " The available Python versions are " +
             elements.slice(0, -1).join(", ") +
             " and " +
             elements[elements.length - 1] +