flatpak: add more details and example commands

As requested, this commit adds more detailed explanations and
step-by-step commands for creating and installing signed flatpak
applications.

Signed-off-by: Arnaud Ferraris <arnaud.ferraris@collabora.com>

content/guides/flatpak.md

@@ -35,7 +35,11 @@ verified. Similarly, it is not possible to sign flatpak applications using GPG.
 The simplest way to create a signed flatpak is to use `flatpak-builder` with
 the `--sign=<SECRETKEY>` command-line argument, where `<SECRETKEY>` is the
 base64-encoded secret Ed25519 key. This ensures the OSTree commit and summary
-are properly signed.
+are properly signed:
+
+```
+flatpak-builder --repo=myrepo --sign=m8/rp9I9ax2w81yujZyeXTfZlbeBjEBUPQSQKo14iHgHdrzpKYH6xvL83midrFNeMrU4QBtk4jZ+x2veQoP4oQ== build-dir org.example.sampleapplication.yaml
+```
 
 For more advanced usage, the same command-line option can also be used with the
 following flatpak commands:
@@ -47,7 +51,7 @@ following flatpak commands:
   * `flatpak build-update-repo`
 
 These commands allow one to create Ed25519-signed commits from an unsigned
-repository or bundle, or to create signed bundles.
+repository or bundle, or to create signed bundles as explained below.
 
 Multiple occurrences of the `--sign` option are allowed in to order to permit
 multiple signatures of each object.
@@ -72,6 +76,18 @@ This line will instruct flatpak to add the corresponding configuration keys to
 the remote and perform signature verification when installing and/or updating
 this application.
 
+Such a .flatpakref file could be:
+
+```
+[Flatpak Ref]
+Name=org.example.sampleapplication
+Title=Sample application from our example repo
+Url=https://example.org/flatpak/repo
+RuntimeRepo=https://example.org/flatpak/example.flatpakrepo
+IsRuntime=false
+SignatureKey=B3a86SmB+sby/N5onaxTXjK1OEAbZOI2fsdr3kKD+KE=
+```
+
 ## Publishing a repository
 
 When distributing several applications, it can be useful to publish the whole
@@ -82,13 +98,30 @@ Exactly as it is done with with `.flatpakref` files, using
 `SignatureKey=<PUBLICKEY>` instead of `GPGKey=...` will instruct flatpak to
 enable Ed25519 signature verification for this repository.
 
+Such a .flatpakrepo file could be:
+
+```
+[Flatpak Repo]
+Title=Sample Repo
+Url=https://example.org/flatpak/repo
+Homepage=https://example.org/flatpak
+Comment=Sample Flatpak repository signed with Ed25519
+Description=This Flatpak repository provides applications signed with Ed25519
+Icon=https://example.org/flatpak/icon.svg
+SignatureKey=B3a86SmB+sby/N5onaxTXjK1OEAbZOI2fsdr3kKD+KE=
+```
+
 ## Publishing a bundle
 
 Flatpak applications can also be distributed as
 [single-file bundles](https://docs.flatpak.org/en/latest/single-file-bundles.html),
 which can be created using the `flatpak build-bundle` command. As previously
 mentioned, these bundles can be signed by adding the `--sign=<SECRETKEY>` option
-to the command invocation.
+to the command invocation:
+
+```
+flatpak build-bundle --sign=m8/rp9I9ax2w81yujZyeXTfZlbeBjEBUPQSQKo14iHgHdrzpKYH6xvL83midrFNeMrU4QBtk4jZ+x2veQoP4oQ== myrepo example.bundle org.example.sampleapplication
+```
 
 However, when publishing a signed flatpak bundle, the corresponding public key
 has to be stored in a location easily accessible to the final user for signature
@@ -100,7 +133,7 @@ to retrieve the associated public key.
 ## Configuring a remote repository
 
 If the repository publisher provides a `.flatpakrepo` file including the public key,
-then no action is needed other than running `flatpak remote-add <REPOFILE>`.
+then no action is needed other than running `flatpak remote-add <REPONAME> <REPOFILE>`.
 
 However, if such a file is not available, one must add the `--sign-verify`
 command-line option to the `flatpak remote-add` command in order to provide
@@ -111,6 +144,16 @@ either the public key directly, or a file containing the public key:
     containing a list of public keys (base64-encoded, one key per line), among
     which at least one can be used to verify signatures for this repository
 
+```
+flatpak remote-add example example.flatpakrepo
+```
+
+or
+
+```
+flatpak remote-add --sign-verify=ed25519=inline:B3a86SmB+sby/N5onaxTXjK1OEAbZOI2fsdr3kKD+KE= example https://example.org/flatpak/repo
+```
+
 Multiple `--sign-verify` occurrences are allowed in order to specify as many
 public keys as needed. This can be useful when a new signature key is being
 deployed, while the old one is still in use: by specifying both the old and the
@@ -126,11 +169,26 @@ This option can also be added when using the `flatpak remote-modify` command.
 Similarly to the process of using `.flatpakrepo` files, when installing a single
 application using a `.flatpakref` file including the public key, no additional
 action is needed. Flatpak will automatically verify Ed25519 signatures using the
-provided public key.
+provided public key:
+
+```
+flatpak install --from example.flatpakref
+```
 
 When the application is installed from a previously configured repository,
 signature verification is also automated, as long as the corresponding public
-key has been imported into the remote's configuration.
+key has been imported into the remote's configuration:
+
+```
+flatpak install org.example.sampleapplication
+```
+
+If the public key has not been previously imported into the remote's
+configuration, one can also use the `--sign-verify` command-line option:
+
+```
+flatpak install --sign-verify=ed25519=inline:B3a86SmB+sby/N5onaxTXjK1OEAbZOI2fsdr3kKD+KE= org.example.sampleapplication
+```
 
 ## Installing a signed bundle
 
@@ -140,6 +198,10 @@ repository configuration to import public keys from, the user needs to specify
 the relevant public keys using the `--sign-verify` command-line option as stated
 above.
 
+```
+flatpak install --sign-verify=ed25519=inline:B3a86SmB+sby/N5onaxTXjK1OEAbZOI2fsdr3kKD+KE= --bundle example.bundle
+```
+
 This option works the same way with both `flatpak build-import-bundle` and
  `flatpak install` commands.