Doc <description>: Unclear how to create a list

[buhtz]

Doc : Unclear how to create a list

from appstream.

[buhtz]

I see the problem. Markdown do not work. Got it.
Before that I used real HTML but even this didn't work.

</p>
  <ul>
      <li>First item</li>
      <li>Second item</li>
  </ul>
</p>

Other then the error of appstreamcli indicates the "ul" is not the problem but having the "ul" inside a "p" is the problem. No matter that this is W3C-valid HTML. Gnome-software and appstreamcli are not able to handle that well.

This works

  <ul>
      <li>First item</li>
      <li>Second item</li>
  </ul>

[ximion]

See https://www.freedesktop.org/software/appstream/docs/chap-Metadata.html#tag-description
There is also an example at https://www.freedesktop.org/software/appstream/docs/chap-Quickstart.html#qsr-app-example with some further information.

[ximion]

No matter that this is W3C-valid HTML.

AppStream Metadata is neither HTML nor Markdown - the docs even specifically call this out to not expect HTML.

[buhtz]

Yes, do not expect HTML. That is why I tried Markdown which even doesn't work.
The doc do not "call" what the user should expect. The section should get rewritten to with this in mind.
But you closed it and it seems you do not treat this as a bug.

It was not a support question but a bug report about the documentation.

[ximion]

The documentation is clear - it is a specification though, so it also has to be concise. It is designed for implementers of the spec and as reference.
Apparently you expect a bit more examples, which is what documents like https://www.freedesktop.org/software/appstream/docs/chap-Quickstart.html are for, as well as the various pages software stores have made. Maybe you will like those more.