[AppStream] Additional markup support in descriptions

[Matthias Klumpp]

Am Fr., 26. Juli 2019 um 05:32 Uhr schrieb Robert Ancell
<robert.ancell at canonical.com>:
>
> Hi all,
>
> I'd like to propose that more markup be supported in app descriptions to allow publishers to express more.
>
> The spec [1] currently supports the following:
> - paragraphs <p>
> - ordered and unordered lists <ol>, <ul> and <li>
>
> I propose we add the following:
> - emphasis <em>

The <em> emphasis is already scheduled for addition, we had a really
long discussion about this particular one in
https://github.com/ximion/appstream/issues/184

> - strong emphasis <strong>

I am not so sure about this one - isn't a regular emphasis enough?

> - code <code> or <pre> or <pre><code> (CommonMark uses options 1 and 3, but it's probably simpler to just only <code> or <pre> in AppStream. I'm not enough of an XML expert to work out the differences between these tags).

<code> makes sense to me, if it isn't overused. Would code be inline
monospace, or rather be a code block?

> I haven't picked these at random, as these are elements used in Markdown from the CommonMark spec [2]. I'm familiar with this because Snaps use a subset of CommonMark for their descriptions and I want to be able to translate these descriptions into an AppStream compatible format so they can be more easily shown in AppStream based apps like GNOME Software.
>
> I do think these are generally useful tags to use for descriptions for any system. Markdown is used quite a lot now (see GitHub/GitLab, .md files etc) so the concepts of emphasis and code blocks are well understood and used features.
>
> For completeness the other major features of Markdown are:
> - headers

I don't want headers, as they would break most UI in software centers
and make descriptions look really really messy. However, I think I
could be convinced that those are useful if there is a strong reason
to have them and designers are okay with having them displayed in
software centers.

> - links

At least not for now, as we have a dedicated url tag for those
already, which should be used for common web references. However, in
the long run links to Wikipedia pages etc. to explain certain things
may make sense in the full description text...

> - images

To those I would be opposed, as that would make us have to load images
from 3rd-party servers when displaying descriptions or would require
implementation of a more advanced image caching logic in appstream
generators. Furthermore it would introduce clutter in the descriptions
and clash with the already existing screenshots tag.

> I'm not proposing we add those at this time as the headers can be confusing with the information shown around descriptions (it's a few paragraphs, not a complete document) and links and images can be used maliciously. We do support making links clickable in Snaps, but this is not something that needs to be explicitly tagged in the description data.

Indeed ;-)

The next AppStream release will contain a <video> tag, btw, to allow
videos as screenshots. In the release after that, I planned to add the
<em> tag, unless Richard has objections to it (which doesn't seem the
case any longer).

Cheers,
    Matthias

-- 
I welcome VSRE emails. See http://vsre.info/