Rewrite, improve, update and correct the documentation #102
Conversation
Previously, tables with much text in a row had had scroll bars to scroll through all the text instead of automatic line breaks. This is due to an open issue in the sphinx read the docs theme (readthedocs/sphinx_rtd_theme#1505). A workaround has been implemented to fix this until the issue is resolved. Additionally, grid tables have been replaced by list tables. This allows explicitly setting the width of the columns and makes it easier to change the tables in the future.
The linuxdeploy user guide has been rewritten, improved and updated. In general, the explanation of how linuxdeploy can be used has been massively improved. There is now a clear explanation of the two distinct ways and its easier to understand how to use linuxdeploy without make. The misleading term "Manual packaging" has been removed as well. Additionally, there are many smaller improvements, namely: - Documentation on the command line arguments --appstream-file, --appdir, --plugin and --output has been added. (This depends on linuxdeploy/linuxdeploy#288 being merged). - The introduction has been improved and now explains the core ideas better. - Additional information about the command line arguments --icon-file and --executable as well as about plugins has been added (and wrong information has been corrected). - An incorrect link to a different section has been corrected. - TODOs about further improvements that also affect other sections have been added.
The packaging guide overview has been rewritten, improved and updated. A table that gives an overview of the different methods to create AppDirs and the corresponding AppImages has been added. It lists their advantages, disadvantages and differences. Additionally, TODOs to remove the (outdated) rest of the overview and to make a section for each AppImage creation method have been added.
Information about each appimage creation tool has been collected, created and unified into one folder. The linuxdeploy and pkg2appimage files have been moved into the new folder. They have been improved: Additional information from the new overview has been included and the introductions have been improved. The appimage-builder and electron-builder sections in the old overview have been removed and replaced by new files in the new folder. They have also been improved with additional information from the new overview. A file about go-appimagetool has been created. It contains information from the new overview as well as further information on how to use it. In the overview, links to these new files have been added (as well as a TODO to make these links more consistent). Additionally, a minor part of the new overview table has been improved. These files have been (preliminarily) added to the packaging guide toctree. The already existing files have been removed from their respective prior toctrees.
The information about the different packaging approaches (packaging as application author and converting existing packages) has been rewritten and collected in a single section. This section has been placed in the overview. The new section replaces the previous Packaging from source and Converting existing binary packages sections. It contains all relevant information from them as well as additional information and a better explanation of the differences between the approaches. Other files about converting binary packages and packaging from source have been removed as well. A TODO has been added to the remaining Packaging native binaries file to move everything relevant (about linuxdeploy or creating the AppDir structure) into new files and then removing it as well. Additionally, a link to one of the removed sections has been replaced.
The packaging automation section (formerly called hosted services) has been rewritten, improved and updated. The (previously almost empty) main page on packaging automation has been rewritten from scratch. A new introduction on the advantages of packaging automation and why it should be used instead of manual packaging has been written. Additionally, a new section about GitHub Actions with an extensive example has been added. The sections about Travis CI and OBS in the overview have been removed and their information has been moved into the main packaging automation page, together with additional information about the history and state of Travis CI. The Travis CI page has been removed. Its convenience functions section has been moved to the main packaging automation page as well. The redundant section about Travis CI in the Packaging native binaries page has also been removed. The Open Build Service page has been improved as well: - Outdated parts (e.g. an almost eleven years (!) old openSUSE version or non-existing links) have been updated. - A recommendation related to testing has been moved into the testing section, which has been linked. The testing section has been updated accordingly. - Grammar mistakes and indentation errors have been fixed. - TODOs to check whether the section is still up to date have been added. Additionally, the section about manual AppDir creation in the overview has been removed as all of its content is duplicated and has been included in the new overview table.
All information about creating the AppDir structure has been collected, rewritten and improved and moved into a new Creating the AppDir structure section. The section consists of a main page that 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. It also contains new sub-pages about 1. manually creating the AppDir structure, 2. Using make to create the AppDir structure and 3. manually packaging *everything*. Links to this new section have been added on several pages. The Manual packaging page has been removed. It had previously mixed the information about manually creating the AppDir structure (to give it to a tool) and manually packaging everything (without a tool). This has been fixed; all information from it has been separated and put (rewritten and improved) into the new section. The Packaging native binaries page has been removed as well. Information about creating the AppDir structure has been moved into the new section, information about linuxdeploy has been moved into its section (both rewritten and improved) and information about desktop entries has been added to a new todo file. The linuxdeploy page has been majorly updated as well: The parts about make have been removed as that's explained in the new section. To account for that, the explanation of --appdir has been improved. Sections on how to download linuxdeploy, on the appimage plugin variables and on an iterative workflow have been added. The page has generally been improved and additional information has been added. Additionally, the overview has been improved: Its introduction has been improved to better explain what the AppImage creation tools actually do. It now also mentions AppDir structure creation and links to the new section. Furthermore, it now provides more information on how to include additional resources.
A new page about desktop entry files and icon files has been created. To do that, the Desktop information page in References, as well as the temporary desktop file file, have been removed and replaced by it. Their content has been rewritten and moved into the new page, together with much additional information. The linuxdeploy page, AppDir specification and Manually creating an AppDir section have all been improved as well with additional information and new links (mostly to the new sections).
The different pages about the AppImage creation tools have been moved into a common section. They've been dereferenced from the packaging guide toctree and moved into a new section toctree. The previous overview page has been renamed into AppImage creation tools and now serves as the main page of this new section. It has also been adapted accordingly (with minor text changes, changed reference names and a toctree). Other pages have been adapted to use the new reference and section names. Additionally, some formatting mistakes have been fixed and the desktop entry & icon files section has been slightly improved.
The packaging guide introduction has been rewritten and improved. Among other things, additional information about the content of the packaging guide has been added.
The AppDir specification has been updated, mostly about the AppRun file, but also about desktop entry and icon files. The AppRun section from the software overview page has been moved into the AppDir specification and has been updated. Other additional information has been added to it as well. The wording has also been improved. Other related pages have been updated accordingly: The page about manually creating an AppDir structure has been updated in regards to AppRun, whose section has been removed. The page about manually creating the entire AppDir has also been updated accordingly. A new section about the rest of the AppDir structure has been added and the specification has been linked. Additional information has been added to both pages, and their wording has been improved.
The software overview page in the introduction section has been split up, partially moved into the references section and rewritten. The sections about appimaged and AppImageLauncher have been moved into the desktop integration tool section and linked. The corresponding subsections there (that had already existed) have been updated accordingly with more information and improved wording. The section about the NX Software center has been moved into the FAQ. The how to download AppImages part has been improved with additional information, among other things about AppImageHub. The sections about linuxdeploy and linuxdeployqt have been removed, and the AppImage creation tool section has been linked instead. The rest of the page has been moved into the references section (whose page order has been improved). A new introduction, which explains the purpose of the page and links to other relevant sections, has been written. Outdated parts have been updated and additional information has been added. The wording has also been improved and made more consistent.
The concept page has been improved: Additional information has been added and the wording and spelling has been improved. But most importantly, the sections about which dependencies are bundled and which Linux distribution version the binaries should be compiled on, have been greatly improved and 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 AppImage creation tools section (both the main page and the specific tool pages) has been updated and corrected accordingly. Information about which distribution versions to compile on has been added to the pages and wrong & unnecessary information has been removed.
|
I support this, recently there was this discussion asking about the static and deploy everything tools: https://github.com/orgs/AppImage/discussions/1343 Btw a small nitpick, the part that says:
Can be changed to say instead |
|
@Samueru-sama I'm sorry for the late answer, I was really busy the last days. On the other part, I took that information from the appimage-builder documentation. But thanks for the feedback; I'll change the part to say that it's usually a big increase, but can also be smaller, depending on which libraries are called. |
|
@probonopd Hey, did you see this PR yet? I noticed that you were also working on the documentation in #103. While luckily, this doesn't interfere with my PR as it's a new section, I would have expected some kind of reaction or response to this. |
|
Hi @Korne127, thanks for this massive undertaking. Hi @TheAssassin is there any way to get this documentation rendered out for easier review (without overwriting the current one, s that I can open them side by side)? |
|
Hi @Korne127
Where did you get this number from? If I remember correctly, the results i got were around 1/3rd that number. How did you test? |
|
@probonopd One way to look at the result would be to just clone my version and execute it: git clone https://github.com/Korne127/docs.appimage.org.git
cd docs.appimage.org
mkdir venv
python3 -m venv venv
source venv/bin/activate
pip3 install -r requirements.txt
make htmlAnd then the files are build in build/html, you just need to double-click them to open in a browser. I also discovered there is a |
I took them from the appimage-builder documentation. If the numbers are wrong and your tests consistently produced different results, I'll adapt it. (But keep in mind this is still a WIP and I haven't gone over some pages at all yet. I also plan to go through the project READMEs and updated them accordingly, e.g. if they link to a now unexacting link in the documentation.) |
|
Note to self, works nicely for me. Maybe we should even document it ;) |
The introduction section has been generally improved and updated: - Spelling and grammar mistakes have been corrected. - Section links have been added in multiple places. - A TODO about duplicated information has been added. - Outdated information about distributions, CIs and the excludelist has been corrected. Outdated informations about the way to create AppImages with the AppImage creation tools has been updated as well.
The motivation and advantages pages in the introduction section have been merged into a new motivation-advantages page, which has been rewritten. The new page now contains the information of both previous pages, which had the same structure and a lot of duplicated information. Some parts in the previous pages have hidden key parts among big amounts of less important information. This has been fixed: The new page has been rewritten to highlight the important AppImage advantages in short paragraphs, putting them before other secondary information. The index has been changed accordingly and a new section link has been added.
The former Running AppImages page in the user guide section has been split up into a new Inspect AppImage content page and a new Desktop integration page. This has been done because the former page didn't contain information on how to run AppImages (those had been moved into the Quickstart page much earlier), but just information on these two completely independent topics. The Inspect AppImage content page has been updated to include the ways to inspect the content of an AppImage safely with external tools. It has also been rewritten and regrouped to better explain the different methods, their advantages and disadvantages. The Desktop integration page has been rewritten to better explain the concept of desktop integration, what exactly the individual tools do and their differences. An additional download link has been added as well. Additionally, the config has been adapted to allow for double dashes to be displayed in headlines, and the index has been changed accordingly.
The FUSE Troubleshooting page has been improved, corrected and rewritten. The structure has been greatly improved: Similar sections have been merged, the order of the sections have been improved, important information has been added to the overview, duplicated information has been removed, a part in a wrong place has been moved to the right place and text styles have been unified. The content has been improved as well: The texts have been shortened and made easier to understand, and some explanations have also been improved. Additionally to that, wrong information has been corrected, additional information has been added and outdated information has been updated. This has been done by adding all important information from the AppImage wiki (https://github.com/AppImage/AppImageKit/wiki/FUSE) to this page.
All user guide pages have been improved, updated and corrected: The texts in the user guide pages have been massively improved. Among other things, information has been specified, things have been explained in a better and more detailed way, wording has been improved, links to other sections with more information have been added, sections with duplicated information have been merged and the overview and content descriptions have been improved & updated to contain everything. Several other things like terminal commands have been improved as well to always work. Additionally to that, the macOS similarity page has been updated with better comparisons that are easier to understand for normal end users, a link to the AppImage creation tools has been added and wrong information has been corrected. Several substitutions have also been added to reduce duplicated texts; they replace previously existing similar or worse texts. Furthermore, spelling, grammar and formatting errors have been fixed, outdated links have been updated and credits have been added.
|
I finally continued on this, and went through the whole introduction and user guide pages and improved, rewrote, updated and corrected them all. I've spent most of my free time in the past week in that process. 😅 (I also merged two pages that basically provided the same kind of information in the same structure with big parts duplicate.) To view the exact changes and things I did, see the commit messages. Also, I noticed something important: The FUSE page in the AppImage wiki (https://github.com/AppImage/AppImageKit/wiki/FUSE) has generally the same structure behind its documentation page, but has been much more up-to-date (although it also missed some information). |
The information on the AppImage updating system and how to make AppImages (self-)updateable has been rewritten and heavily improved. The updating informaion page has been restructured: - Much information that had previously been buried in subsections although it was generally applicable has been moved into more general sections. - The difference between different concepts has been made more clear and information on what approach to use in which case and the (dis-)advantages has been added. - The overview explaining the general topic has been improved to better explain the different updating concepts. - Information on specific AppImage creation tools has been replaced with a more general overview and moved into the respective tools' pages. Additionally to the restructuring, the page has been rewritten and massively improved: - The given information and explanations have generally been improved, made more concise and easier to understand and follow. Additional information and explanations have been added as well. - Information on what the update information string is and how it works has been added and improved. - A section about the update GUI libraries has been added. - The example code and corresponding explanations have been improved and bundled in one concise place. - Information that depends on a very specific project structure (using CMake and C++) has been removed and replaced with information that's generally applicable and not dependent on a specific language. - Redundant text that didn't contain meaningful information has been removed. - Duplicated information has been removed. - TODOs have been added to correct some wrong information. Furthermore, a new page in the user guide about downloading and updating AppImages has been added. It contains the information a user should know, including a basic explanation on (self-)updateable AppImages, how they work, and the ways they can be updated.
The updating information page contains information on how to call bundled executables (as appimageupdatetool can be bundled to achieve self-updateability). However, this information had previously been incorrect and didn't work. This has been fixed. The text has been replaced by an accurate explanation on how to call such bundled executables with additional notes and information.
|
I have another update: I finished rewriting the updating information page: Improving the page structure and all explanations (making them more concise and easier to follow), correcting wrong information that didn't work and adding missing information, giving a better overview about different approaches and their (dis-)advantages and replacing information that depends on a specific project structure with information that's generally applicable. |
The information to run an AppImage in the terminal to see potential error messages has been added to the troubleshooting page. It has also been generally improved and made more consistent with the rest of the documentation.
Information about the desktop integration tools Gear Lever, zap, Soar and AM has been added to the desktop integration page in the user guide. Additionally, a warning has been added to the AppImageLauncher section that it doesn't work with current reference implementation AppImages anymore and to the appimaged section that the monitored directories are not configurable. The project links have also been improved to not link to a specific version anymore.
The FUSE troubleshooting page has been updated to the change to the new static runtime being the official reference implementation runtime. The descriptions have been updated to account for the fact that it mostly applies to older AppImages and not those built by the modern reference implementation, as well as the fact that most distributions don't have FUSE 2 installed out of the box anymore. The error messages have also been updated to the error message actually giving by recent AppImages. Additionally, some explanations have generally been improved.
The pkg2appimage page has been improved and updated. An explicit section on how to download and use pkg2appimage with distributed recipe files has been added. The information has been moved there from the introduction. It has also been updated to use the prepackaged pkg2appimage AppImage (and not the shell script). The recipe file section has been improved to not have duplicated information anymore and have better and easier to understand explanations. Additionally, spelling and grammar has been corrected in some places and links have been improved.
The testing page has been majorly improved, updated and corrected. The introduction has been improved and duplicates in it have been removed. Everything in the introduction that only applies to live images has been moved into a corresponding section. The testappimage part has been removed as the tool is outdated and doesn't work with modern AppImages. It has been replaced by an easy-to-understand explanation on how to manually test the AppImages with live images. The appimage-testsuite part has also been removed as the tool and its supported distribution versions are outdated and as it contains some bugs, resulting in it not working out of the box. It has been replaced by a script inside the documentation, which is an improved version of the relevant parts of appimage-testsuite. The following changes and improvements have been made: - No dockerfiles are used. Instead, the container must exist locally or gets downloaded, making it future-proof. Important packages are still installed, but transparently in the script, and this is explained to the user. - The docker command has been improved to use the X11 server socket to connect to the host system instead of an unnecessary TCP connection. (The original code didn't work anyways, as the code to get the IP didn't work on Linux and code to make the host X11 server listen on port 6000 was missing.) - Non-executed und unnecessary code has been removed. This way, several scripts could be merged into one smaller snippet which actually works without having to modify it. Explanatory comments have also been added to make the script easy to understand. Additionally, the descriptions and explanations on the page have generally been improved.
|
Another smaller update; I finally finished going through every page once. There are still some things on my to do list, but most are either smaller consistency changes or things I already wrote a todo for. Those are the new changes:
|
Several minor improvements to the documentation have been carried out: - The appimagebuilder and pkg2appimage pages now link to a section explaining why the compilation should sometimes be done on an old system. Even if this doesn't apply to these projects, this helps readers to understand the context. - An explanation why the version of the system where a pkg2appimage recipe is invoked doesn't matter has been added to its page. - A runtime reference implementation decision has been added to the list. - A Woodpecker CI script has been moved into the Woodpecker folder. - The 404 page has improved to reflect the state of the documentation more accuractly, and grammar mistakes have been corrected. - An unused file has been removed. - A duplicate in the .gitignore file has been removed.
The README file has been improved: - The explanation on how to use the convenience script and what it actually does has been improved. - A new section which explains how to manually set up the project and build the documentation has been added. - A non-existant image has been removed. - Its general structure and phrasing has been improved.
The reference links have been improved: - The reference link naming has been made more consistent. Redundant "ref"s in the names have been removed. - The names of some reference links have been improved. - Unused and redundant reference links have been removed. Additionally, the AppDir page has been slightly improved to better explain the concept of an AppDir.
The sphinx smartquote feature (transforming all quotation marks into curly quotation marks) has been re-enabled. For consistency, all curly quotation marks in the documentation have been replaced by ASCII ones. The headlines with double dashes have been modified for the dashes to not automatically be replaced.
The sphinx syntax in the documentation has been made more consistent. These changes don't affect the build result. - The lines used to mark headlines have been made consistent for every level. - The amount of empty lines after resp. before a headline has been made consistent (to one resp. two (even for sub-headlines)). - The amount of empty lines after a directive (like note::) has been made consistent (to zero). - Hyperlink target definitions have been moved into the link if they were used only one time and to the bottom of the page if they were used several times. Additionally, one unnecessary hyperlink has been removed.
All code blocks have been made more consistent: - All shell commands in code blocks are now consistently prepended by > (which differentiates them from console output). Previously, some had been prepended by $ or not at all. - All shell code blocks are now consistently marked as shell. Previously, some had been marked as bash. - All literal blocks (::) have been transformed into explicit code-blocks. Some of them are yaml code blocks (this improves their formatting); the others are text blocks (this doesn't change their formatting, but improves the overall consistency). - All inline code blocks are now created with ``…``. Previously, many of them had been created with :code:`…`, which results in the same formatting. This improves consistency and makes sense as the overall majority of inline code blocks aren't actual code. Additionally, two code blocks have been transformed into inline code blocks to improving the related explanation.
The sphinx hyperlink syntax has been corrected. Most sphinx hyperlinks have been made anonymous hyperlinks. This fixes the issue that many of them had falsely not been anonymous before (resulting in conflicting target definitions in some places). Only the ones that are referencing the same target (only) under the same name in different places have been kept as or replaced by non-anonymous hyperlinks. For consistency and maintainability, their target definitions have been moved out of the link definition and to the bottom of the page or into the substitutions page. Additionally, links have been made more consistent without a trailing slash, one link has been corrected and one unnecessary link has been removed to improve the related explanation. The syntax of one headline has also been fixed.
Several improvements have been carried out, most noticably to the AppImage creation tools page, the macOS page and the sphinx configuration. AppImage creation tools page improvements: - The information that appimagetool is (part of) the reference implementation and go-appimagetool doesn't use it has been added. - The information that linuxdeploy currently doesn't use the new static runtime has been added. - The wrong information that including the core libraries increases the AppImage size by at least 30MB has been corrected both here and in other places in the documentation. While it had originally been taken from the appimage-builder documentation, feedback to the pull request revealed that this is usually not the case. - Information on the platforms AppImages run on (according to the tools) has been removed as this is not primarily dependent on the creation tool. macOS page improvements: - The information about self-updateable AppImages has been clarified and its section has been linked. - The information about appimaged has been replaced by more general information about desktop integration tools. - The update information section and signature section have been linked. Configuration improvements: - The language entry has been corrected (previously, sphinx had used the fallback value). - The format of the intersphinx_mapping entry has been updated and its unused dummy value has been removed. - The format of the source_suffix entry has been updated. Additionally, formatting and phrasing has been improved. Some mentions of Travis CI have also been removed as it's not recommended to use anymore.
Explanations on what type 2 AppImages are as well as references to the sections explaining it in detail have been added to multiple places where AppImage types are mentioned. In some places, a rough explanation on what type 2 AppImages are had already been given. Only an additional link to the respective section has been added there to give more information. In the other places where the term had been mentioned without any explanation, both a basic explanation on what type 2 means as well as such a link has been added.
A section on how to determine whether an AppImage uses the new static runtime or the old dynamic runtime has been added. Additionally, several TODOs that had already been done have been removed. Some spelling mistakes and a wrong name have also been corrected and a reference link has been added in one place. The TODO to add other helper tools in the reference chapter has been removed as no other tools are currently recommended or generally used.
A section about the alternative (to the reference) implementation go-appimagetool has been added to the reference chapter. It explains the consequences of it being an alternative implementation and the differences between the implementations. It has been linked in relevant places. The same information has also been added to the go-appimagetool page itself. The appimagetool section in the reference implementation page has also been linked wherever it's mentioned to give more information on what it is. In some places where it makes sense, the information that it is (part of) the reference implementation has also been added. Additionally, several minor improvements have been carried out: - The signature page has been improved to explain when to use appimagetool. - An additional reference implementation decision has been added. - A warning that linuxdeploy doesn't use the new static runtime has been added to its page. - All reference links have been made consistent by replacing some underscores with dashes. - Phrasing has been improved.
The AppStream generator code has been massively improved in both capabilities, descriptions and design. Some wrong descriptions and results have also been corrected. It now offers more capabilities: - The ability to use multiple screenshots has been added. - The ability to not use any screenshot or not use a homepage URL has been added. Several things have been corrected: - The ID and the desktop file entries have been separated. This is especially important as the ID has to be unique and follow the reverse DNS notation scheme (and the desktop file name doesn't have to do that). Previously, there had only been a desktop file name input field, resulting in possibly invalid IDs. - The ID and desktop file example names have been corrected to use the DNS notation schemes. - A multi-line description is now correctly being split up into several paragraph tags (with empty beginning or trailing lines being trimmed). - The output name has been updated from <ID>.appdata.xml to <ID>.metainfo.xml. Design improvements: - Tooltips have been added. This allows for short and concise input names while allowing longer descriptions that explain the purpose of and requirements for these inputs. Previously, the input names were long and cumbersome, yet still couldn't give enough information about the inputs. - The order of the inputs has been improved and made more intuitive. - Associate labels have been added to increase accessibility. - The style has been improved; all input fields now have the same length and an unnecessary textarea tag has been replaced with a simple input field. The source code has also gotten some minor improvements: - Deprecated tags have been replaced by modern CSS. - Line breaks have been added so that most of the source code is readable without scrolling. - The two space indentation scheme has been replaced with tabs. - The algorithm generating the AppStream file has been improved. - Comments have been improved. Additionally, the information that the AppStream generator doesn't generate a complete AppStream file but other important tags exist and readers should look into the AppStream documentation has been added.
|
Wow, I finally finished it. I almost can't believe it myself yet. This last batch of commits consists mostly of smaller consistency changes, but also has some bigger ones: Bigger improvements
Other improvements
|
The packaging guide introduction page has been removed as it had mostly contained duplicated information (which had also been in the packaging guide main page). The packaging guide index (main page) has been improved by adding some additional information from the introduction page. Some information from the introduction page has also been moved into the AppImage creation tools page. Additionally, several minor improvements have been carried out: - A downloading section has been added to the go-appimagetool page - Links to the AppImage creation tool repositories have been added to the respective page. - Links to the appimagetool section have been added in some places to find the project more easily. - The information that the custom AppImage keys should be included in AppImage desktop entry files has been added. - The wrong information that all software catalogs use the AppStream metadata has been corrected. - Spelling and phrasing has been improved.
All outdated and non-existing URLs have been found using make linkcheck and updated. In most cases, outdated URLs have been updated to the newer ones to which they redirect. However, one URL has been replaced by a web.archive.org link as the original page seems to no longer exist.
|
(While going over the documentation and the issues, I noticed some minor things, so I added two more commits. Among other things, two introduction pages with duplicated information have been merged, a downloading section has been added to the go-appimagetool page and all outdated and non-existing URLs have been updated.) |
|
So, I went through all issues in this GitHub repository to see which ones this pull request fixes: Fixes #9, #29 - While the documentation doesn't start with a literal copy & paste example, the underlying problem that it consists of tons of contradictory, wrong, and unstructured information has been fixed. The home page now directly links first-time developers to the packaging guide, which contains structured information about the requirements and copy & paste commands for the AppImage creation tools. Fixes #30 - The original problem that the user didn't even find the place where to download the tools has been fixed as the pages now contain download instructions and links to the projects. A decision tree is not implemented, but as stated above, the documentation is now structured and makes it much easier to find the respective information. Fixes #57 - This issue is about the problem I had in the beginning: Unclear, conflicting and non-understandable information on how to build an AppImage. (In hindsight I also see that much information had required a workflow with make and other things, which hadn't been explained.) This is completely fixed as all the information has been structured, the different ways on how to do this have been separated and the differences have been explained. @freakboy3742 @ok2cqr @onpon4 As you were some of the people complaining about the (previous) documentation being completely inaccessible and not understandable (which I can fully understand), I'd be interested in what you think about the new documentation (especially the packaging guide). Do you think it's now easier to start using AppImages as a developer? Tell me if you have any feedback. Fixes #28 - The new static runtime bundles FUSE, so using this command isn't required with modern AppImages anymore. Additionally, the documentation now clearly explains how you can run AppImages if you can't get FUSE to run (and the specific command also isn't required for new Ubuntu versions anymore). Fixes #32 - The new documentation tries to always link to the respective section and only to the external project in that specific section. Fixes #34 - The different (duplicated) sections about "compiled-in absolute paths" and relocation in general have been merged and made much more easy to understand. The general concept of relocation is also explained better. Fixes #35 - The information about FUSE in the documentation has been merged with some additional information in the wiki and the problem and solution are explained better. The problem with docker is also now explained in its own section and directly mentioned on the homepage and the quickstart page. Fixes #66 - The desktop entry page now lists the important keys an application should have, but also explicitly mentions that other keys exist and should be used. It links to the desktop entry specification for an exhaustive list. Fixes #68 - All the broken links have been corrected. Fixes #73 - The documentation explicitly states to install libfuse2 and not fuse in Ubuntu. It also goes over additional steps like adding the universe repository that may be required. Fixes #77 - The information about the deprecated AppRun.c file has been collected and merged into one block, which explains why it had been used but that it's deprecated and shouldn't be used anymore. In other places where it's mentioned, this section is linked (and it's not recommended anymore). Fixes #84 - The duplicated information about hard-coded paths and relocatability has been merged into one single section. Fixes #87 - The software catalogs page now goes over all software catalogs and explains the differences between them. The ambiguity of "AppImageHub" has been removed. Fixes #88 - The unmaintained appimage-testsuite has been removed and replaced by a script inside the documentation itself, in which some bugs have been corrected and which works out of the box. Fixes #98 - The outdated information that linuxdeploy isn't available on ARM has been removed. Fixes #99 - The information that FUSE has to be installed for older AppImages without the new static runtime, and how to do it using Fedora is in the documentation. Installing GTK shouldn't be required as it has been removed from the excludelist. The problem that the user couldn't get any information on which libraries to install should be fixed as the documentation now explains how to see the error message if an AppImage doesn't run. |
|
I also found this comment (#35 (comment)) which I fully agree with. I think this whole problem that the information was / is inconsistent, outdated, conflicting, etc. stems from the fact that there are several places in which the same kind of information is. Therefore, I think that after this documentation is finally updated, structured, easy to understand and without duplications, it should become what it claims to be: A single unified source of information. So after this is merged, I'll go through the wiki and all these other places in the next time and see if there is any additional information and add it to the documentation so that we can remove the wikis and other places and just replace them with links to the documentation, so that everyone always sees the complete unified source of up-to-date information. |
|
@Korne127 Thanks for tagging me on this; these changes definitely look extensive. However, I'm no longer interested in AppImage as a deployment mechanism. The tool I maintain (Briefcase) has support for AppImage, but we've effectively deprecated our support for AppImage as a result of the large number of issues that we've had with apps deployed using this technique, including (but not limited to) this one. As a result, we now discourage the use of AppImage for new projects, and we plan to eventually remove AppImage support from Briefcase altogether. |
That webkitgtk is a cursed thing, we had this issue and we were able to bundle it, but it required a lot of manual hacks. The issue is that the library is hardcoded to look for some binaries in |
| .. 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. |
There was a problem hiding this comment.
These frameworks are supposed to contain bundles of libraries which are needed by more than one AppImage, and hence could save some disk space.
Likely when this was originally written that was true, but today that's far from true.
I would either remove this or mention that it is not true that they save disk space, but not big deal anyway.
There was a problem hiding this comment.
This section isn't about the comparison to a different system like Flatpak, but rather about the general concept of additionally deduplicating AppImage parts. For example, by removing something that's very common from AppImages and instead fetching that once if needed.
The paragraph states that yes, even if those would save disk space (as the AppImages are the same, just with less), that still goes against the core concept of AppImages and would not be worth it.
|
|
||
| .. _build-on-old-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 ``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. |
There was a problem hiding this comment.
Would put "can" instead of "should" here. I often see people confused when I suggest them to bundle everything to fix an issue and they point to suggestions like this.
| It requires a manual creation of the AppDir folder structure and file placement (if make isn't used). For more information on how to use make accordingly, or manually create the necessary structure, see :ref:`creating-appdir-structure`. | ||
|
|
||
| .. note:: | ||
| go-appimagetool is not using the :ref:`reference implementation <reference-implementation>` (called appimagetool) to create AppImages; instead, it creates them itself. This means that it might choose different :ref:`implementation decisions <appimagetool>` (e.g. CLI options like ``--appimage-extract`` the resulting AppImage supports), resulting in AppImages that behave differently to the usual ones (created with the reference implementation). |
There was a problem hiding this comment.
Appimages created with go-appimagetool use the same static runtime, maybe the version is a bit older compare to the type2-repo, but the CLI arguments are the same.
What is different is that go-appimagetool itself has less CLI deploy options than appimagetool, like for example that you can't disable appstream validation.
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
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 ruffle-rs/ruffle#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
Other sections that have been rewritten
Updated & improved sections
Split up sections
Minor improvements
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 linuxdeploy/linuxdeploy#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).
Edit: This is just the motivation and description of the first 13 commits; see my other posts for the description of the rest.
#102 (comment) is an overview over the issues this pull request fixes, but I have to write this in the first post for GitHub to recognize it:
Fixes #9, fixes #28, fixes #29, fixes #30, fixes #32, fixes #34, fixes #35, fixes #57, fixes #66, fixes #68, fixes #73, fixes #77, fixes #84, fixes #87, fixes #88, fixes #98, fixes #99.