From 792b32eb9669d47c6b318fb6dcec41870f998880 Mon Sep 17 00:00:00 2001
From: Matthew Leeds <matthew.leeds@endlessm.com>
Date: Fri, 12 Jan 2018 22:22:50 -0800
Subject: [PATCH] man: Update ostree-summary.xml

Update the man page for the summary command to add the undocumented
options, make the syntax clear, and add examples.

Closes: #1416
Approved by: pwithnall
---
 man/ostree-summary.xml | 71 +++++++++++++++++++++++++++++++++---------
 1 file changed, 57 insertions(+), 14 deletions(-)

diff --git a/man/ostree-summary.xml b/man/ostree-summary.xml
index 815d2b5a..b4629c3d 100644
--- a/man/ostree-summary.xml
+++ b/man/ostree-summary.xml
@@ -44,12 +44,16 @@ Boston, MA 02111-1307, USA.
 
     <refnamediv>
         <refname>ostree-summary</refname>
-        <refpurpose>Regenerate the summary metadata file</refpurpose>
+        <refpurpose>Regenerate or view the summary metadata file</refpurpose>
     </refnamediv>
 
     <refsynopsisdiv>
             <cmdsynopsis>
-                <command>ostree summary</command> <arg choice="opt" rep="repeat">OPTIONS</arg>
+                <command>ostree summary</command> <arg choice="opt">--gpg-sign=KEYID</arg> <arg choice="opt">--gpg-homedir=HOMEDIR</arg> <arg choice="req">--update</arg> <arg choice="opt" rep="repeat">--add-metadata=<replaceable>KEY</replaceable>=<replaceable>VALUE</replaceable></arg>
+            </cmdsynopsis>
+
+            <cmdsynopsis>
+                <command>ostree summary</command> <group choice="req"><arg choice="plain">--view</arg><arg choice="plain">--raw</arg></group>
             </cmdsynopsis>
     </refsynopsisdiv>
 
@@ -70,20 +74,13 @@ Boston, MA 02111-1307, USA.
 
         <variablelist>
             <varlistentry>
-                <term><option>-u</option></term>
+                <term><option>--update</option>,<option>-u</option></term>
 
                 <listitem><para>
-                  Update the summary file.
-                </para><para>
-                  Any additional arguments to the command
-                  are treated as additional key–value pairs to be added to the
-                  summary file as additional metadata. They must be in the format
-                  <command><replaceable>KEY</replaceable>=<replaceable>VALUE</replaceable></command>
-                  or as two separate arguments. The keys must be namespaced for
-                  your organisation or repository using a dot prefix. The values
-                  must be in GVariant text format. For example,
-                  <command>exampleos.end-of-life "@t 1445385600"</command>.
-                </para>
+                        Update the summary file. This option can be combined
+                        with <option>--add-metadata</option> to add metadata
+                        fields to the summary.
+                    </para>
 
                 <!-- FIXME: Uncomment this when collection ID support becomes non-experimental.
                 <para>If the repository has a collection ID configured, the
@@ -95,6 +92,37 @@ Boston, MA 02111-1307, USA.
                 </listitem>
             </varlistentry>
 
+            <varlistentry>
+                <term><option>--add-metadata</option>,<option>-m</option>=KEY=VALUE</term>
+
+                <listitem><para>
+                    Specify an additional metadata field to add to the summary.
+                    It must be in the format
+                    <command><replaceable>KEY</replaceable>=<replaceable>VALUE</replaceable></command>
+                    or as two separate arguments. The keys must be namespaced
+                    for your organisation or repository using a dot prefix. The
+                    values must be in GVariant text format. For example,
+                    <command>exampleos.end-of-life "@t 1445385600"</command>.
+                    This option can be used multiple times.
+                </para></listitem>
+            </varlistentry>
+
+            <varlistentry>
+                <term><option>--view</option>,<option>-v</option></term>
+
+                <listitem><para>
+                    View the contents of the summary file in a human readable format.
+                </para></listitem>
+            </varlistentry>
+
+            <varlistentry>
+                <term><option>--raw</option></term>
+
+                <listitem><para>
+                    View the raw bytes of the summary file.
+                </para></listitem>
+            </varlistentry>
+
             <varlistentry>
                 <term><option>--gpg-sign</option>=KEYID</term>
 
@@ -113,4 +141,19 @@ Boston, MA 02111-1307, USA.
 
         </variablelist>
     </refsect1>
+
+    <refsect1>
+        <title>Examples</title>
+        <para><command>$ ostree summary -u</command></para>
+        <para><command>$ ostree summary -u -m key="'value'"</command></para>
+        <para><command>$ ostree summary -v</command></para>
+<programlisting>
+* ostree/1/1/0
+    Latest Commit (4.2 MB):
+      9828ab80f357459b4ab50f0629beab2ae3b67318fc3d161d10a89fae353afa90
+    Timestamp (ostree.commit.timestamp): 2017-11-21T01:41:10-08
+
+Last-Modified (ostree.summary.last-modified): 2018-01-12T22:06:38-08
+</programlisting>
+    </refsect1>
 </refentry>