Add support for heading in app description

[CarlSchwan]

This is useful for adding some organization inside a long description. h1 is not allowed since this should be the title of the application, and this should not be handled by the app itself.

E.g. this would make sense for the description in https://apps.kde.org/zanshin/

[ximion]

Thank you for providing an example, those are always useful!
The description texts are intended to be very basic on purpose, so people do not go too crazy and make insanely long articles about their software. The intent is to give users the fastest possible way to see if they want to install the software or not.

That said, I do see why people would like some way of sectioning text, but I do not like using h2 very much. First of all, the description text in AppStream are explicitly intended to not be HTML, adding h2 would make people believe more that they can use HTML, and much worse, it will naturally lead them to believe that there was a h1 too - that's a pretty huge trap we would set just for a slightly convenient implementation.

So, what I would suggest is adding just one organizational element, section, for now. That one is not HTML, quite clear in what it does, and can be styled by software centers in every way they want. Adding subsections will likely lead to people not making terse descriptions anymore, so I'm not sure if we need those (we could always add them later, I do not like adding any feature in the hope that they will become useful in future).

What do you think? @hughsie do you have any feedback on this issue, given that we avoided adding a feature like this for quite a while... (the 1.0 release would be the time to add such a thing though, if we want it).
I actually see this being quite useful in release descriptions as well, actually.

[hughsie]

I don't think we want h2/h3 -- it's just confusing to define. Section makes 100% sense.

[JakobDev]

The problem I see with a section is, that it is not HTML. I know, that the Description is intended to not be HTML, but all valid Tags for a Description are also valid HTML tags that do the same, so in fact, it is currently a subset of HTML. Sites who Display the AppStream Description relay on this and display just us the Description Code as it is. Adding a new tag that is not HTML would break this.

[CarlSchwan]

The problem I see with a section is, that it is not HTML. I know, that the Description is intended to not be HTML, but all valid Tags for a Description are also valid HTML tags that do the same, so in fact, it is currently a subset of HTML. Sites who Display the AppStream Description relay on this and display just us the Description Code as it is. Adding a new tag that is not HTML would break this.

yeah this is also why I choose h2 and h3 since both Discover and apps.kde.org won't need any changes to support it

[ximion]

Relying on undefined behavior is not okay though, and adding a hack to the specification just so other tools might not need changes (I know some that adding any new tag here would break) is also not okay.
The specification is also quite explicit here and says Do not assume the format is HTML at the very beginning.

Websites can add CSS styles to section elements, while we can provide a to_html helper function in libappstream to convert description markup to HTML (just like we already have for Markdown). That would actually also allow us to add more tags in future with a bit less pain than currently.

[danirabbit]

I think it would be overkill to add multiple headers and agree that h2 would be confusing and imply support for h1.

The spec does include an em tag already for italic, so would it be acceptable to use strong for bold instead of adding an explicit header tag? Does the text need to be larger?

As far as I can tell, the iOS App Store for example doesn’t support any kind of headers in app descriptions.

[CarlSchwan]

<section> is already an HTML tag which a different semantic https://developer.mozilla.org/en-US/docs/Web/HTML/Element/section . So if <h2> is not acceptable, I would prefer using <heading>, which doesn't already mean something.

Similarly using <strong> would be quite incorrect since it's used "for content that is of "strong importance," including things of great seriousness or urgency (such as warnings)." (https://developer.mozilla.org/en-US/docs/Web/HTML/Element/strong) and so using that for heading can confuse a screen reader

I checked a few other app stores and apple app store, android play store and the windows store don't support headings and generally have extremely short app descriptions. Android and Windows don't even seems to support bold or italic and apps developers add stars to mark stuff as more important.

Steam, GoG and Epics do support headings and generally have a way bigger app description and inline images.

[CarlSchwan]

friendly ping :)

[ximion]

Given the amount of hell that broke loose after Flatpak introduced just em (flatpak/flatpak#5434), I would like to hold off on this a bit, at least for a short while until things settle.

With everything using libappstream I don't expect a lot of breakage to happen, but there's always that one thing that does some self-parsing (looking at you, GNOME Software and Canonical!).

Overall, heading would be a pretty okay name, I think :-)