Rewrite, improve, update and correct the documentation

source/_static/css/custom.css

@@ -11,3 +11,40 @@
     hyphenate-limit-last: always;
     hyphenate-limit-zone: 8%;
 }
+
+.wy-table-responsive table td, .wy-table-responsive table th {
+    white-space: normal;
+}
+
+.formatted-table tr:nth-child(1) td {
+    background-color: #006400 !important;
+    color: #000000 !important;
+}
+.formatted-table tr:nth-child(2) td {
+    background-color: #006400 !important;
+    color: #000000 !important;
+}
+.formatted-table tr:nth-child(3) td {
+    background-color: #FFFF00 !important;
+    color: #000000 !important;
+}
+.formatted-table tr:nth-child(4) td {
+    background-color: #FFFF00 !important;
+    color: #000000 !important;
+}
+.formatted-table tr:nth-child(5) td {
+    background-color: #FF8000 !important;
+    color: #000000 !important;
+}
+.formatted-table tr:nth-child(6) td {
+    background-color: #FF8000 !important;
+    color: #000000 !important;
+}
+.formatted-table tr:nth-child(7) td {
+    background-color: #FF0000 !important;
+    color: #000000 !important;
+}
+
+.bold-link a {
+    font-weight: bold;
+}

source/conf.py

@@ -124,6 +124,7 @@
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
 html_static_path = ['_static']
+html_css_files = ["css/custom.css"]
 
 # Custom sidebar templates, must be a dictionary that maps document names
 # to template names.
@@ -135,6 +136,9 @@
 #
 # html_sidebars = {}
 
+# Don't automatically transform -- to a single dash
+smartquotes = False
+
 
 # -- Options for HTMLHelp output ---------------------------------------------
 
@@ -208,8 +212,3 @@
 
 # If true, `todo` and `todoList` produce output, else they produce nothing.
 todo_include_todos = True
-
-
-# apply some subtle changes to the selected theme via custom CSS file
-def setup(app):
-    app.add_css_file("css/custom.css")

source/introduction/concepts.rst

@@ -1,3 +1,5 @@
+.. include:: ../substitutions.rst
+
 Concepts
 ========
 
@@ -14,47 +16,50 @@ The AppImage development follows a few easy-to-understand core principles and co
 One app = one file
 ------------------
 
-AppImages are simple to understand. Every AppImage is a regular file, and every AppImage contains exactly one app with all its dependencies. Once the AppImage is :ref:`made executable <ref-download-make-executable-run>`, a user can just run it, either by double clicking it in their desktop environment's file manager, by running it from the console etc.
+AppImages are simple to understand. Every AppImage is a regular file, and every AppImage contains exactly one app with all its dependencies. Once the AppImage is :ref:`made executable <ref-how-to-run-appimage>`, a user can just run it, e.g. by double clicking it in their desktop environment's file manager or by running it from the console.
 
 .. _ref-opinion-reusable-frameworks:
 .. note::
 
-   On a regular basis, `users ask <https://github.com/AppImage/AppImageKit/issues/848>`__ about implementing support for some sort of "reusable/shared frameworks". These frameworks are supposed to contain bundles of libraries which are needed by more than one AppImage, and hence could save some disk space. For management, they suggest complex automagic systems that will automatically fetch the "frameworks" from the Internet if they're not available, or some complicated, mostly manual methods how to users could bundle frameworks together with the AppImages on portable disks like USB sticks.
+   On a regular basis, `users ask <https://github.com/AppImage/AppImageKit/issues/848>`__ about implementing support for some sort of "reusable/shared frameworks". These frameworks are supposed to contain bundles of libraries which are needed by more than one AppImage, and hence could save some disk space. For management, they suggest complex automagic systems that will automatically fetch the "frameworks" from the Internet if they're not available, or some complicated, mostly manual methods how users could bundle frameworks together with the AppImages on portable disks like USB drives.
 
    These may be good ideas for some people, and even if they worked perfectly fine, they'd break with our most important concept: :ref:`one app = one file <one-app-one-file-principle>`. AppImages are so simple to understand *because* every application is a single file. There's no complexity in this approach, even grandma could understand it. And after all, disk space is cheap nowadays, right?
 
-   If you prefer this approach or absolutely need it, please check out alternative approaches. AppImage will never implement such a feature.
+   If you prefer this approach or absolutely need it, please check out alternative approaches like Flatpak or Snap. AppImage will never implement such a feature.
 
 
 .. _no-external-dependencies:
 
-Do not depend on system-provided resources
-------------------------------------------
+Bundle all required dependencies
+--------------------------------
 
-The author of an AppImage needs to decide for which target systems (Linux distributions) they want to offer the AppImage.  Then, the author needs to bundle any dependencies that cannot reasonably be assumed to come with every target system (Linux distributions) in its default installation in a recent enough version.
+To be able to run on any Linux distribution, an AppImage has to bundle all resources it needs at runtime that cannot reasonably be expected to come with every still-supported target system (Linux distribution) in its default installation in a recent enough version. The most common resources that have to be bundled are the actual binaries, shared library dependencies, icons and other graphics and of course a :ref:`desktop file <desktop-entry-files>` for desktop integration.
 
-To be able to run on any Linux distribution, an AppImage should bundle all the resources it needs at runtime that cannot be reasonably expected to be "there" in the default installation of all still-supported target systems (Linux distributions). The most common resources are the actual binaries, shared library dependencies, icons and other graphics and of course one or more desktop files for desktop integration.
+This doesn't mean an AppImage must not use resources provided by the system, like for example basic libraries that can be assumed to be part of every target system (e.g., the C standard library or graphics libraries), user interface themes or the like. See the `excludelist <https://github.com/AppImage/pkg2appimage/blob/master/excludelist>`_ for a list of the libraries we consider to currently be part of every still-supported target system.
 
-This doesn't mean an AppImage must not use resources provided by the system, like for example basic libraries that can be assumed to be part of every target system (e.g., the C standard library or graphics libraries), user interface themes or the like. See the `excludelist <https://github.com/AppImage/pkg2appimage/blob/master/excludelist>`__ for a list of the libraries we consider to currently be part of each still-supported target system (distribution).
 
+.. _exclude-expected-libraries:
 
-.. _build-on-old-systems:
+Exclude expected core libraries (Recommended, but optional)
+-----------------------------------------------------------
 
-Build on old systems, run on newer systems
-------------------------------------------
+AppImages should usually exclude certain "core libraries", which can be expected to be present on all major desktop Linux distributions, reducing the overhead of :ref:`one app = one file <one-app-one-file-principle>`. These dependencies are mostly shared libraries and involve low level libraries like :code:`libc.so.6` (the GNU C library, the C language standard library the majority of all Linux distributions use), but also common libraries like `zlib <https://zlib.net/>`_ that are normally present.
 
-It is considered best practice to develop and compile the application on the oldest still-supported Linux distribution that we can assume users to still use. For example, the oldest still-supported LTS release of Ubuntu is a good choice to develop applications against and build applications on.
+It may seem contradictory to :ref:`the previous section <no-external-dependencies>` to rely on distribution provided resources. This is a trade-off between trying to reduce redundancies while at the same time being as self-contained as possible.
 
-Applications should be built on the oldest possible system, allowing them to run on newer system. This allows the exclusion of certain "base libraries", which can be expected to be present on all major desktop Linux distributions, reducing the overhead of :ref:`one app = one file <one-app-one-file-principle>`. These dependencies are mostly shared libraries and involve low level libraries like :code:`libc.so.6` (the GNU C library, the C language standard library the majority of all Linux distributions use), but also common libraries like zlib_ or the GLib_ libraries are normally present.
+In some cases, including the libraries might even break the AppImage on the target system. Those libraries involve, among others, hardware dependent libraries such as graphics card drivers provided libraries (e.g., :code:`libGL.so.1`, (`source <https://github.com/AppImage/pkg2appimage/blob/14c255b528dd88ef3e00ae0446ac6d84a20ac798/excludelist\#L38-L41>`_)), or libraries that are built and linked differently on different distributions (e.g., :code:`libharfbuzz.so.0` and :code:`libfreetype.so.6` (`source <https://github.com/AppImage/pkg2appimage/blob/14c255b528dd88ef3e00ae0446ac6d84a20ac798/excludelist\#L98-L102>`_)).
 
-It may seem contradictory to :ref:`the previous section <no-external-dependencies>` to rely on distribution provided resources. This is a trade-off between trying to reduce redundancies while at the same time being as self-contained as possible.
+The list of libraries that should be excluded, the so-called `excludelist <https://github.com/AppImage/pkg2appimage/blob/master/excludelist>`_, is carefully curated by the AppImage team, and is regularly updated.
+
+**However, excluding these core libraries requires you to compile the application on the oldest still-supported Linux distribution version that we can assume users to still use.** For example, the oldest still-supported LTS release of Ubuntu is a good choice to build applications on. |old_compile_version_reason|
+
+.. note::
 
-In some cases, including the libraries might even break the AppImage on the target system. Those libraries involve, among others, hardware dependent libraries such as graphics card drivers provided libraries (e.g., :code:`libGL.so.1`, (`source <https://github.com/AppImage/pkg2appimage/blob/14c255b528dd88ef3e00ae0446ac6d84a20ac798/excludelist\#L38-L41>`__)), or libraries that are build and linked differently on different distributions (e.g., :code:`libharfbuzz.so.0` and :code:`libfreetype.so.6` (`source <https://github.com/AppImage/pkg2appimage/blob/14c255b528dd88ef3e00ae0446ac6d84a20ac798/excludelist\#L98-L102>`__).
+   If you don't use any dynamic linking, and your application does not reference any of these core libraries, you don't have to build the application on an old system.
 
-The list of libraries that can resp. have to be excluded, the so-called `excludelist <https://github.com/AppImage/pkg2appimage/blob/master/excludelist>`__, is carefully curated by the AppImage team, and is regularly updated.
+   However, even when using a programming language that usually links everything statically like Rust or Go, some libraries might still be dynamically linked, e.g. by including C code or dependencies that do so. You should test whether your application references any shared libraries with ``ldd`` before building and packaging on a newer system, and it's usually still better to build the application on an old system (to be safe in case of future changes).
 
-.. _zlib: https://zlib.net/
-.. _GLib: https://developer.gnome.org/glib/
+Some :ref:`appimage-creation-tools` can also include these expected core libraries. This considerably increases the AppImage size (by at least 30MB), but removes the limitation of requiring the oldest supported LTS distribution version to compile the binaries (since all referenced libraries are included, the used distribution version is irrelevant). This should only be done if there are issues with the exclusion of the core libraries, e.g. if the AppImage can't be built on the oldest supported LTS distribution version, as the inclusion of some core libraries can also lead to other issues. If a considerable base of your users uses a system configuration without some of these core libraries (e.g. a custom Gentoo configuration), it's also an option to provide both AppImage versions.
 
 
 .. _appimage-specification: