Convert Docbook to reStructuredText for man pages

[danyeaw]

Removes the dependency on xsltproc and the DocBook style sheets for better cross-platform compatibility. ReStructuredText is more modern than writing XML.

[ximion]

First of all, thank you for the work and creating a patch!
To be honest though, I have a lot of doubts whether it makes any sense at all to merge this.

The entire documentation and specification of AppStream is written in Docbook XML, so these dependencies you mention will be pulled in anyway, either directly, or indirectly via daps on any build that includes documentation builds.

And while for something new I would prefer reST for sure, I think there is value in keeping things consistently in Docbook for this project. That, or converting everything to reST so we do not need to maintain even more tooling and markup languages.

So, by merging this we would gain nothing, but instead make things harder to maintain by having more languages to write documentation in.
I was thinking of rewriting the specification in reST, but I didn't find any compelling reason to justify the huge effort for doing so.

[danyeaw]

Hi @ximion, thanks for the feedback! If I took on converting all the documentation from Docbook to reST would that be more acceptable?

[ximion]

Yes, but why would you even want to do that? What problem does it solve?
If all docs would be converted, we would also need to provide compat links so everything referencing the specification still works (it is linked to from a lot of places), making this a really difficult task to do right. It's a lot of work, so I think it would really need a super strong reason to invest time in it.

[danyeaw]

My motivation is to get AppStream better supported on macOS and Windows, because while my GTK app that uses libadwaita is primarily used by Linux users, it also is available for those other platforms as well.

I can submit a separate issue, but this is what I run in to on macOS:

[1/21] Generating docs/man-appstreamcli with a custom command
FAILED: docs/appstreamcli.1
/usr/bin/xsltproc --nonet --stringparam man.output.quietly 1 --stringparam funcsynopsis.style ansi --stringparam man.th.extra1.suppress 1 -o docs/appstreamcli.1 http://docbook.sourceforge.net/release/xsl/current/manpages/docbook.xsl ../docs/xml/man/appstreamcli.1.xml
I/O error : Attempt to load network entity http://docbook.sourceforge.net/release/xsl/current/manpages/docbook.xsl
warning: failed to load external entity "http://docbook.sourceforge.net/release/xsl/current/manpages/docbook.xsl"
cannot parse http://docbook.sourceforge.net/release/xsl/current/manpages/docbook.xsl

I have docbook-xsl installed, but no joy and I don't know why besides well its Docbook and there are better, more readable formats available.

[ximion]

Two options might work: We don't build manual pages in Windows, or we find out why this issue happens. The schema should be available locally, so for some reason they are not found on Windows. It would make sense to investigate that.
Can you locale where docbook.xsl was placed, maybe it requires us to set some environment variables.

[danyeaw]

Replaced by #550.