Appimagekit: [Feature request] Implement `--appimage-readme`

[KurtPfeifle]

User story:

"As a user, I want to be able to access a README (and potentially other documentation) that an AppImage maintainer (or the developer of the respective app) has embedded into the image."

I'd expect the README text to see printed in the terminal output, when I run
myApp.AppImage --appimage-readme
from the command line.

But maybe you guys can come up with an even more convenient method?

---

^{(This feature request may need thorough discussion and preparation work first. A standard way to implement this should possibly be specified in the AppImage spec draft document.}

[TheAssassin]

Well, I think it should suffice to call the bundled app's --help option.

[KurtPfeifle]

I'm afraid, in many cases the --help function possibly isn't enough...

Or why would developers often times add more documentation than merely provide a --help output to their software if it is packaged in the traditional way (RPM, DPKG, ...)?

So why then should a AppImage package go lower than the "old-fashioned" folks and hide this legitimate info resource from its users?

Why shouldn't the AppImage spec come up with a way to bundle these parts? And to make them also accessible to users in a standard way that in the future would get automatically deployed to all AppImages created with AppImageKit-based tools?

[probonopd]

What goes into an AppImage and what command line options the things inside the AppImage support or don't support are outside of the scope for AppImageKit, so I would prefer to leave this up to the person putting together an AppImage. All of this can easily be achieved by using a custom AppRun script. We may want to implement --appimage-list though, which could be invoked like this:

Especially, we don't want to force people putting a README into a defined location.

./Some.AppImage --appimage-list | grep -r -i readme

to achieve the same effect.

[TheAssassin]

All of this can easily be achieved by using a custom AppRun script.

Just for completion, beware that --appimage* options are reserved for the AppImage runtime, i.e., you need to choose another prefix.

[KurtPfeifle]

@probonopd stated above:

"What goes into an AppImage and what command line options the things inside the AppImage support or don't support are outside of the scope for AppImageKit"

The request IS to use the --appimage-* prefix exactly because my goal is to provide a standard way for AppImage packagers of letting their payload apps also display internal documentation. (And as I indicated, the exact way -- or the potentially several recommended ways -- to implement that should be going into the AppImage file format specification.)

I hope the two of you are not arguing that AppImage is "happy to support 98% of the features which traditionally packaged software provide, for 98% of our user base". If that's so, it would be a big disappointment for me.

In any case my personal ambition would be to see this functionality not outside the scope of AppImageKit, but included. Just as I see its scope not limited to only desktop GUI applications, but also aiming for CLI utilities...

How to achieve this feat via a custom AppRun I've already explored and succeeded. So now I think it is something which should also be tackled by the standard runtime in a standard way. (Of course we can discuss about the priority of such a feature. I wouldn't complain if you guys had 10 more burning items on your current milestones list.)

"Especially, we don't want to force people putting a README into a defined location."

And why not?

If AppImage packagers and developers want their READMEs to be discoverable and easily read, why should they then NOT obey to the "force" of the AppImage spec in this regard? After all, they are also "forced" to put other components into defined locations too in order to make up a valid AppImage bundle.

Also, the typical locations for READMEs of software packages are not THAT diverse according to my experience.... So they should not be too difficult to auto-discover even, or to report: "Sorry, no suitable README found in this AppImage."

---

^{(/me now goes on a discovery tour to see if Snap or FlatPak provide such a feature. If they do, I might even find a new favorite Linux packaging format :-) I'll take the opportunity to explore the Two's respective technology and documentation in some more depth. This may take a good while.
So long...}

[probonopd]

Well, if we start specifying which type of file needs to go in which place under which name in an AppImage, then we are going down the same spiral as Debian packaging - we'll end up with a set up policies and rules that are so cumbersome that hardly anyone knows how to make a spec compliant AppImage.

The general rule of thumb is that inside an AppImage, the author of the AppImage is free to do whatever he wants, as long as there is an AppRun file that can launch the application, and a desktop file that describes basic aspects of the application, and the icon that goes with the desktop file. These are basically really the only rules.

The only acceptable exception to this general rule imho is that our tools may optionally use information from well-known LSB paths (if present), because most source packages already follow it. E.g., appimaged uses information from usr/share/icons/....

Also, on a pragmatic note, the AppImage runtime is optimized for size, both in terms of LOC as well as KB. Adding such a feature would significantly complicate the logic, as we would have to determine which files are or are not present inside the AppImage, and offer or not offer additional command line options.

[KurtPfeifle]

@TheAssassin wrote:

"Just for completion, beware that --appimage options are reserved for the AppImage runtime, i.e., you need to choose another prefix."*

Maybe I didn't express my wish clear enough? Sorry then...

No, I want exactly such a prefix to be used, because I want the AppImage default AppRun and runtime to support it and hence use such a prefix!

And I want the collective brain power of AppImage developers to come up with an simple, lightweight solution to achieve this, so AppImage packagers could also easily get it automatically added to the packages they build.

(I don't say this is the NEXT feature to be supported, or that it must be within the next 12 months. I have no idea what you guys have on your roadmap next and how busy these goals will keep you....)

[KurtPfeifle]

@probonopd argues:

"Well, if we start specifying which type of file needs to go in which place under which name in an AppImage, then we are going down the same spiral as Debian packaging - we'll end up with a set up policies and rules that are so cumbersome that hardly anyone knows how to make a spec compliant AppImage."

I'm not arguing that such a thing should be a "NEED to go" in a special place.

What I intend is to make an offer to packagers: "If you would like to see the READMEs, manpages and HTML documentation of your package be exposed to users of the AppImage, then these are the standard locations where the AppImage AppRun (and/or runtime?) are looking for it and hence will autodiscover them. If your help files do not live there, here's how you can STILL let them be exposed: 1. [...] 2. [...] -- If you don't care, we don't either. Just don't blame us if users cannot access them."

"The general rule of thumb is that inside an AppImage, the author of the AppImage is free to do whatever he wants, as long as there is an AppRun file that can launch the application, and a desktop file that describes basic aspects of the application, and the icon that goes with the desktop file. These are basically really the only rules."

I understand that.

What I want to do is extend the capabilities automatically provided by AppImages (and easy to make use of by packagers):

• The authors and contributors of the upstream application after all had made an effort to include documentation.
• Just because the AppImage packager is lazy (or clueless or a Travis CI autobuild script) and doesn't create a custom AppRun script this effort shouldn't get lost, and AppImage users shouldn't suffer from a lack of it.

"The only acceptable exception to this general rule imho is that our tools may optionally use information from well-known LSB paths (if present), because most source packages already follow it. E.g., appimaged uses information from usr/share/icons/...."

I don't know if the $MANPATH is in LSB. But even if it isn't, appimaged or even the .AppImage itself could still make use of it. And the runtime/AppRun could be spoonfed by the packager through some extra option which alternative path to apply if they want.

"Also, on a pragmatic note, the AppImage runtime is optimized for size, both in terms of LOC as well as KB. Adding such a feature would significantly complicate the logic, as we would have to determine which files are or are not present inside the AppImage, and offer or not offer additional command line options."

Ok, if I start to argue here, I'll easily be lost, since I'm not a developer or a C/C++ coder. It would be the classical case of a blind person arguing with a seeing one about the color of the sky.

However, I'd still challenge the implication of this being too big a penalty to pay size- or complexity-wise if implemented as compared to the added polish and benefit for end-users.