systemd-id128: properly document the show verb

https://github.com/systemd/systemd/issues/27514 requested this functionality
among other things, but it is already implemented. The man page was also
missing 'show' in the synopsis, so add that, along with an example.

diff --git a/man/systemd-id128.xml b/man/systemd-id128.xml
index 6cb51fa777fc4931183d0a754c6c53359a19c3a4..c4521ea945f10b73feb3affe36f8c1172e5edd7b 100644 (file)
--- a/man/systemd-id128.xml
+++ b/man/systemd-id128.xml
@@ -44,6 +44,13 @@
       <arg choice="opt" rep="repeat">OPTIONS</arg>
       <arg choice="plain">invocation-id</arg>
     </cmdsynopsis>
+
+    <cmdsynopsis>
+      <command>systemd-id128</command>
+      <arg choice="opt" rep="repeat">OPTIONS</arg>
+      <arg choice="plain">show</arg>
+      <arg choice="opt" rep="repeat">NAME|UUID</arg>
+    </cmdsynopsis>
   </refsynopsisdiv>
 
   <refsect1>
@@ -76,9 +83,10 @@
 
     <para>With <command>show</command>, well-known IDs are printed (for now, only GPT partition type UUIDs),
     along with brief identifier strings. When no arguments are specified, all known IDs are shown. When
-    arguments are specified, they must be the identifiers or ID values of one or more known IDs, which are
-    then printed. Combine with <option>--uuid</option> to list the IDs in UUID style, i.e. the way GPT
-    partition type UUIDs are usually shown.</para>
+    arguments are specified, they may be the identifiers or ID values of one or more known IDs, which are
+    then printed with their name, or arbitrary IDs, which are then printed with a placeholder name. Combine
+    with <option>--uuid</option> to list the IDs in UUID style, i.e. the way GPT partition type UUIDs are
+    usually shown.</para>
   </refsect1>
 
   <refsect1>
@@ -137,7 +145,26 @@
   <refsect1>
     <title>Exit status</title>
 
-    <para>On success, 0 is returned, a non-zero failure code otherwise.</para>
+    <para>On success 0 is returned, and a non-zero failure code otherwise.</para>
+  </refsect1>
+
+  <refsect1>
+    <title>Examples</title>
+
+    <example>
+      <title>Show a well-known UUID</title>
+      <programlisting>
+$ systemd-id128 show -P user-home
+773f91ef66d449b5bd83d683bf40ad16
+
+$ systemd-id128 show -Pu user-home
+773f91ef-66d4-49b5-bd83-d683bf40ad16
+
+$ systemd-id128 show 773f91ef-66d4-49b5-bd83-d683bf40ad16
+NAME      ID
+user-home 773f91ef66d449b5bd83d683bf40ad16
+      </programlisting>
+    </example>
   </refsect1>
 
   <refsect1>

diff --git a/src/id128/id128.c b/src/id128/id128.c
index c22376d4fcd3d91adebc44882605599f38129814..0ec2df059a5e38144a560fc00a9d401104998716 100644 (file)
--- a/src/id128/id128.c
+++ b/src/id128/id128.c
@@ -166,7 +166,7 @@ static int help(void) {
                "  machine-id              Print the ID of current machine\n"
                "  boot-id                 Print the ID of current boot\n"
                "  invocation-id           Print the ID of current invocation\n"
-               "  show [NAME]             Print one or more well-known GPT partition type IDs\n"
+               "  show [NAME|UUID]        Print one or more UUIDs\n"
                "  help                    Show this help\n"
                "\nOptions:\n"
                "  -h --help               Show this help\n"