Rewrite, improve, update and correct the documentation

[Korne127]

This is still a work in progress. However, I now got most of the major changes done, and since I might still take a while for the rest and am a bit afraid that someone else might want to start doing the same, I decided to open the current state as a draft pull request.

---

When I started looking into how to deploy AppImages a few weeks ago, I had big troubles understanding the documentation:

• There was very much duplicated information which made it hard to find a specific detail that was only mentioned in one of the duplicated parts and generally to read through the documentation.

• There was very much outdated information, from commonly recommending the deprecated linuxdeployqt tool, to the deprecated AppRun.c file, not even mentioning the new go-appimagetool, many invalid and outdated links, old Linux versions (one even being eleven years (!) old), etc.

• The same terms were sometimes used for very different concepts, e.g. "manual packaging" for

  1. manually creating the entire AppDir that's then converted into an AppImage by appimagetool,
  2. manually creating the AppDir structure to use with higher level tools that include the shared libraries and
  3. giving the path of executables, desktop and icon files to linuxdeploy via command line arguments

  which obviously led to much confusion.

• There was much conflicting information, mostly due to duplicated information, which has been outdated in some parts and updated in others, or the same terms used for different concepts.

• There was missing information that was expected in other places, e.g. which resolutions are valid for icon files.

• There was information scattered across places or in the wrong places, e.g. several pages contained some details about desktop files, but no page in the packaging guide clearly explained everything related to it and how to create them.

• There were weird structure decisions, e.g. placing a software overview, mostly about low-level software that the average user should not use, in the introduction section instead of the reference section.

• There was no single detailed comparison about the differences between the individual tools and approaches to create an AppImage, resulting in a lot of confusion which one(s) to use and how to create AppImages.

• Some things were just explained badly, e.g. the pages about using make to create an AppDir lacked the most important information on how to do so, and the linuxdeploy page made it very hard to understand how to use it without make.

I think much of this is not that noticeable when you know your way around AppImages well enough. Sure, you might notice many things aren't up to date and that some things are duplicated, but I think you can generally read through it, understand what's meant, fill in the missing information and don't really realize how hard it is to understand all of that if you don't have that prior experience and knowledge.

I also think that much of this comes from the fact that the AppImage ecosystem has evolved a lot in the past years. There are many things that have considerably improved, e.g. going from having to package the entire AppDir by yourself and use appimagetool directly, over tools like linuxdeployqt that package all shared libraries from an existing AppDir structure, to linuxdeploy, which can get all necessary data with command line arguments and requires no pre-existing structure. I also noticed that some old parts were expecting the reader to repackage existing packages, probably out of a time where AppImages haven't been commonly used, while other parts were mainly directed to the application authors. I can imagine that the focus was on developing better solutions and improving the AppImage packager and user experience. And it's understandable that, with many parts duplicated, you don't always find the time to really go through the documentation and update everything correctly when something changes, slowly leading to a worse documentation state.

All of this is to say, I hope that you don't take this as an insult. I do appreciate the work you put into AppImages and the whole ecosystem and I understand that the focus has been on other things, but I do think that the documentation is in a bad state.

And this also led to frustration by other users. See for example https://discourse.appimage.org/t/does-appimage-include-all-shared-library-dependencies-by-default/509/6, where someone is frustrated with the documentation as they don't find a guide on how to automatically package shared libraries, or https://github.com/ruffle-rs/ruffle/issues/12401, where someone didn't even know about the other available tools that help with this, which is the core thing the documentation should explain in my opinion.

---

Therefore I started to rewrite, improve, update and correct the documentation. I started with the linuxdeploy page, which I had personally had a lot of struggle with to understand previously. From there on, I worked my way through the documentation (mostly the packaging guide), and went on to improve the structure, add a comparison of creation tools & approaches, deliver better explanations, update the outdated information and add additional information.

Here is an overview of my changes:

New sections that contain collected information

• One unified section for all AppImage creation tools has been added.
  • Its main page contains one central table which lists the advantages, disadvantages and differences between the different methods.
  • It contains one page for each AppImage creation tool (some of which have been collected from many places throughout the documentation), explaining how to use it.
    • This also means that a new page for go-appimagetool has been added (it had previously not been mentioned).
    • Much additional information and better explanations have also been added to most of these pages.
    • The linuxdeploy page has been rewritten, improved and updated. It’s now much easier to understand how to use it.
  • The section also contains a better overview on what the AppImage creation tools actually do, which helps to understand why they should be used.
• The information about the different packaging approaches (packaging as application author and repackaging existing binaries) has been collected in one section and rewritten, with additional information and a better explanation of the differences between the approaches.
• One unified section on how to create the AppDir structure has been added.
  • Its main page provides an overview of the different ways to do it, the reason why one would want to do it and the additional possibility of manually packaging everything.
  • This also means that the concepts of manually creating the AppDir structure (to give it to a tool) and manually packaging everything (without a tool) have been separated and the difference is well-explained.
• A new page about desktop entry files and icon files has been created. Information from several files has been merged together with much additional information.

Other sections that have been rewritten

• The packaging automation section (formerly called hosted services) has been rewritten and updated.
  • Its main page now contains a new introduction about the advantages of packaging automation and why it should be used.
  • A new tutorial on GitHub Actions has been added to it.
  • The existing (outdated) parts have been updated.
• The sections about which dependencies are bundled and which Linux distribution version the binaries should be compiled on in the concept page have been partially rewritten.
  • Misleading headlines have been changed and a better explanation of why AppImages should usually be compiled on older systems, and which exceptions and other options exist, has been added.
• The packaging guide introduction has been rewritten to give a better introduction of what the guide explains.

Updated & improved sections

• The AppDir specification has been updated.
  • Information about the AppRun file has been updated and added.
  • More information about the desktop entry and icon files has been added.

Split up sections

• The software overview section has been split up. Most of it has been moved into the reference section, but some parts moved into other sections in which the respective software had already been mentioned. A better introduction has been added to it as well.

Minor improvements

• The table formatting has been improved. Tables now have automatic line breaks (instead of scroll bars) and are easier to edit. (This is minor for the existing documentation, but the overview table wouldn’t have been possible without it).
• Many other sections and pages that haven’t been explicitly mentioned have gotten some improvements and additional information.

For more details, each commit contains an in-depth message of all changes I have made within it.

Also, this pull request documents the features introduced in https://github.com/linuxdeploy/linuxdeploy/pull/288, so it depends on that being merged.

---

As I said in the beginning, this is currently a work in progress. I still have a lot of todos and there are quite some sections I haven't really gone through yet at all. But I still thought that now is a good time to create this draft PR, as most of the major restructuring is done and it's easy to see my desired end result. I'll probably still take a while to finish this (especially as I basically worked the entire last week from waking up until going to bed on this, and will continue slower as it's now known that I'm working on it).