Document the flatpakref file format

Add a man page with details about this file format: flatpak-flatpakref.5

doc/Makefile.am

@@ -51,6 +51,7 @@ man1 = \
 
 man5 = \
 	flatpak-metadata.5		\
+	flatpak-flatpakref.5		\
 	$(NULL)
 
 man_MANS = \

doc/flatpak-flatpakref.xml

@@ -0,0 +1,120 @@
+<?xml version='1.0'?> <!--*-nxml-*-->
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+    "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
+
+<refentry id="flatpak-flatpakref">
+
+    <refentryinfo>
+        <title>flatpakref</title>
+        <productname>flatpak</productname>
+
+        <authorgroup>
+            <author>
+                <contrib>Developer</contrib>
+                <firstname>Alexander</firstname>
+                <surname>Larsson</surname>
+                <email>alexl@redhat.com</email>
+            </author>
+        </authorgroup>
+    </refentryinfo>
+
+    <refmeta>
+        <refentrytitle>flatpakref</refentrytitle>
+        <manvolnum>5</manvolnum>
+    </refmeta>
+
+    <refnamediv>
+        <refname>flatpak-flatpakref</refname>
+        <refpurpose>Reference to a remote for an application or runtime</refpurpose>
+    </refnamediv>
+
+    <refsect1>
+        <title>Description</title>
+
+        <para>
+            Flatpak uses flatpakref files to share information about a remote for
+            a single application. The <filename>flatpakref</filename> file contains
+            enough information to add the remote and install the application.
+            Use the <command>flatpak install --from</command> command to do so.
+        </para>
+
+        <para>
+           The filename extension commonly used for flatpakref files is <filename>.flatpakref</filename>.
+        </para>
+
+        <para>
+           A flatpakref file can also refer to a remote for a runtime.
+        </para>
+
+    </refsect1>
+
+    <refsect1>
+        <title>File format</title>
+
+        <para>
+            The flatpakref file is using the same .ini file format that is used for
+            systemd unit files or application .desktop files.
+        </para>
+
+        <refsect2>
+            <title>[Flatpak Ref]</title>
+
+            <para>
+                All the information is contained in the [Flatpak Ref] group.
+            </para>
+            <para>
+                The following keys can be present in this group:
+            </para>
+            <variablelist>
+                <varlistentry>
+                    <term><option>Name</option> (string)</term>
+                    <listitem><para>The fully qualified name of the runtime that is used by the application. This key is mandatory.</para></listitem>
+                </varlistentry>
+                <varlistentry>
+                    <term><option>Url</option> (string)</term>
+                    <listitem><para>The url for the remote. This key is mandatory.</para></listitem>
+                </varlistentry>
+                <varlistentry>
+                    <term><option>Branch</option> (string)</term>
+                    <listitem><para>The name of the branch from which to install the application or runtime. If this key is not specified, the "master" branch is used.</para></listitem>
+                </varlistentry>
+                <varlistentry>
+                    <term><option>Title</option> (string)</term>
+                    <listitem><para>The title of the application or runtime. This should be a user-friendly name that can be displayed e.g. in an app store.</para></listitem>
+                </varlistentry>
+                <varlistentry>
+                    <term><option>IsRuntime</option> (boolean)</term>
+                    <listitem><para>Whether this file refers to a runtime. If this key is not specified, the file is assumed to refer to an application.</para></listitem>
+                </varlistentry>
+                <varlistentry>
+                    <term><option>GPGKey</option> (string)</term>
+                    <listitem><para>The base64-encoded gpg key for the remote.</para></listitem>
+                </varlistentry>
+            </variablelist>
+        </refsect2>
+    </refsect1>
+
+    <refsect1>
+        <title>Example</title>
+<programlisting>
+[Flatpak Ref]
+Title=GEdit
+Name=org.gnome.gedit
+Branch=stable
+Url=http://sdk.gnome.org/repo-apps/
+IsRuntime=False
+GPGKey=mQENBFUUCGcBCAC/K9WeV4xCaKr3NKRqPXeY5mpaXAJyasLqCtrDx92WUgbu0voWrhohNAKpqizod2dvzc/XTxm3rHyIxmNfdhz1gaGhynU75Qw4aJVcly2eghTIl++gfDtOvrOZo/VuAq30f32dMIgHQdRwEpgCwz7WyjpqZYltPAEcCNL4MTChAfiHJeeiQ5ibystNBW8W6Ymf7sO4m4g5+/aOxI54oCOzD9TwBAe+yXcJJWtc2rAhMCjtyPJzxd0ZVXqIzCe1xRvJ6Rq7YCiMbiM2DQFWXKnmYQbj4TGNMnwNdAajCdrcBWEMSbzq7EzuThIJRd8Ky4BkEe1St6tuqwFaMZz+F9eXABEBAAG0KEdub21lIFNESyAzLjE2IDxnbm9tZS1vcy1saXN0QGdub21lLm9yZz6JATgEEwECACIFAlUUCGcCGwMGCwkIBwMCBhUIAgkKCwQWAgMBAh4BAheAAAoJEArkz6VV0VKBa5cH/0vXa31YgEjNk78gGFXqnQxdD1WYA87OYxDi189l4lA802EFTF4wCBuZyDOqdd5BhS3Ab0cR778DmZXRUP2gwe+1zTJypU2JMnDpkwJ4NK1VP6/tE4SAPrznBtmb76BKaWBqUfZ9Wq1zg3ugvqkZB/Exq+usypIOwQVp1KL58TrjBRda0HvRctzkNhr0qYAtkfLFe0GvksBp4vBm8uGwAx7fw/HbhIjQ9pekTwvB+5GwDPO/tSip/1bQfCS+XJB8Ffa04HYPLGedalnWBrwhYY+G/kn5Zh9L/AC8xeLwTJTHM212rBjPa9CWs9C6a57MSaeGIEHLC1hEyiJJ15w8jmY=
+</programlisting>
+    </refsect1>
+
+    <refsect1>
+        <title>See also</title>
+
+        <para>
+            <citerefentry><refentrytitle>flatpak</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
+            <citerefentry><refentrytitle>flatpak-install</refentrytitle><manvolnum>1</manvolnum></citerefentry>
+        </para>
+
+    </refsect1>
+
+</refentry>