From 0ae7c446a191216c924e5fe0b850a7a12db668e2 Mon Sep 17 00:00:00 2001
From: Matthias Clasen <mclasen@redhat.com>
Date: Sat, 18 Jun 2016 21:08:27 -0400
Subject: [PATCH] Clarify the documentation a bit

Revise the man pages for the new document commands a bit, using
'document id' consistently, and adding cross references among them.
---
 doc/flatpak-document-export.xml   | 19 ++++++++++++-------
 doc/flatpak-document-info.xml     |  4 +++-
 doc/flatpak-document-list.xml     |  4 +++-
 doc/flatpak-document-unexport.xml |  6 ++++--
 4 files changed, 22 insertions(+), 11 deletions(-)

diff --git a/doc/flatpak-document-export.xml b/doc/flatpak-document-export.xml
index 40108c3d..3ab40a39 100644
--- a/doc/flatpak-document-export.xml
+++ b/doc/flatpak-document-export.xml
@@ -40,9 +40,10 @@
         <title>Description</title>
 
         <para>
-            Creates a document identifier for a local file that can be
-            exposed to sandboxed applications, allowing them access to
-            files that they would not otherwise see.
+            Creates a document id for a local file that can be exposed to
+            sandboxed applications, allowing them access to files that they
+            would not otherwise see. The exported files are exposed in a
+            fuse filesystem at /run/user/$UID/doc/.
         </para>
 
         <para>
@@ -90,7 +91,9 @@
                 <term><option>--app=APPID</option></term>
 
                 <listitem><para>
-                  Grant read access to the specified application.
+                  Grant read access to the specified application. The
+                  --allow and --forbid options can be used to grant
+                  or remove additional privileges.
                   This option can be used multiple times.
                 </para></listitem>
             </varlistentry>
@@ -132,7 +135,7 @@
                 <term><option>--allow-delete</option></term>
 
                 <listitem><para>
-                  Grant the ability to delete a document id to the applications specified with --app.
+                  Grant the ability to remove the document from the document portal to the applications specified with --app.
                 </para></listitem>
             </varlistentry>
 
@@ -140,7 +143,7 @@
                 <term><option>--forbid-delete</option></term>
 
                 <listitem><para>
-                  Remove the ability to delete a document id from the applications specified with --app.
+                  Revoke the ability to remove the document from the document portal from the applications specified with --app.
                 </para></listitem>
             </varlistentry>
 
@@ -196,7 +199,9 @@
 
         <para>
             <citerefentry><refentrytitle>flatpak</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
-            <citerefentry><refentrytitle>flatpak-run</refentrytitle><manvolnum>1</manvolnum></citerefentry>
+            <citerefentry><refentrytitle>flatpak-document-unexport</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
+            <citerefentry><refentrytitle>flatpak-document-info</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
+            <citerefentry><refentrytitle>flatpak-document-list</refentrytitle><manvolnum>1</manvolnum></citerefentry>
         </para>
 
     </refsect1>
diff --git a/doc/flatpak-document-info.xml b/doc/flatpak-document-info.xml
index b833acca..14f00426 100644
--- a/doc/flatpak-document-info.xml
+++ b/doc/flatpak-document-info.xml
@@ -106,7 +106,9 @@ permissions:
 
         <para>
             <citerefentry><refentrytitle>flatpak</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
-            <citerefentry><refentrytitle>flatpak-document-export</refentrytitle><manvolnum>1</manvolnum></citerefentry>
+            <citerefentry><refentrytitle>flatpak-document-export</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
+            <citerefentry><refentrytitle>flatpak-document-unexport</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
+            <citerefentry><refentrytitle>flatpak-document-list</refentrytitle><manvolnum>1</manvolnum></citerefentry>
         </para>
 
     </refsect1>
diff --git a/doc/flatpak-document-list.xml b/doc/flatpak-document-list.xml
index 4a38ff0b..e4b191d9 100644
--- a/doc/flatpak-document-list.xml
+++ b/doc/flatpak-document-list.xml
@@ -86,7 +86,9 @@
 
         <para>
             <citerefentry><refentrytitle>flatpak</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
-            <citerefentry><refentrytitle>flatpak-document-export</refentrytitle><manvolnum>1</manvolnum></citerefentry>
+            <citerefentry><refentrytitle>flatpak-document-export</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
+            <citerefentry><refentrytitle>flatpak-document-unexport</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
+            <citerefentry><refentrytitle>flatpak-document-info</refentrytitle><manvolnum>1</manvolnum></citerefentry>
         </para>
 
     </refsect1>
diff --git a/doc/flatpak-document-unexport.xml b/doc/flatpak-document-unexport.xml
index 7e3d6db3..4b36acae 100644
--- a/doc/flatpak-document-unexport.xml
+++ b/doc/flatpak-document-unexport.xml
@@ -40,7 +40,7 @@
         <title>Description</title>
 
         <para>
-            Removes the document identifies for the file from the
+            Removes the document id for the file from the
             document portal. This will make the document unavailable
             to all sandboxed applications.
         </para>
@@ -86,7 +86,9 @@
 
         <para>
             <citerefentry><refentrytitle>flatpak</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
-            <citerefentry><refentrytitle>flatpak-document-export</refentrytitle><manvolnum>1</manvolnum></citerefentry>
+            <citerefentry><refentrytitle>flatpak-document-export</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
+            <citerefentry><refentrytitle>flatpak-document-info</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
+            <citerefentry><refentrytitle>flatpak-document-list</refentrytitle><manvolnum>1</manvolnum></citerefentry>
         </para>
 
     </refsect1>