Improve --help text and man page generation

generate-man.py

@@ -28,20 +28,24 @@
 
 print(f".SH DESCRIPTION\n.PP\n{description}\n.SH OPTIONS")
 
-options = re.split(r"\s{2,}", parts[3].strip())
-buf = ""
 opt: List[str] = []
+options = parts[3].strip().split("\n  ")
 while options:
     o = options.pop(0)
     if o.startswith("-"):
         if opt:
-            print(".TP")
-            print((opt[0] + "\n" + " ".join(opt[1:])).replace("-", r"\-"))
-        opt = [re.sub(r"([-a-z]+)", r"\\fB\1\\fR", o)]
+            print(" ".join(opt))
+            opt = []
+        print(".TP")
+        oo = re.split(r"\s{2,}", o)
+        print(re.sub(r"([-a-z]+)", r"\\fB\1\\fR", oo.pop(0)).replace("-", r"\-"))
+        if oo:
+            options = oo + options
     else:
-        opt.append(o)
-print(".TP")
-print((opt[0] + "\n" + " ".join(opt[1:])).replace("-", r"\-"))
+        opt.append(o.strip())
+
+if opt:
+    print(" ".join(opt))
 
 print('.SS "Commands:"')
 commands = re.split(r"\s{2,}", parts[4].strip())

man/ykman.1

@@ -13,25 +13,22 @@ Configure your YubiKey via the command line.
 specify which YubiKey to interact with by serial number
 .TP
 \fB\-r\fR, \fB\-\-reader\fR NAME
-specify a YubiKey by smart card reader name (can't be used with \-\-device or list)
+specify a YubiKey by smart card reader name (can't be used with --device or list)
 .TP
 \fB\-t\fR, \fB\-\-scp\-ca\fR FILENAME
-specify the CA to use to verify the SCP11 card key (CA\-KLCC)
+specify the CA to use to verify the SCP11 card key (CA-KLCC)
 .TP
 \fB\-s\fR, \fB\-\-scp\fR CRED
-specify private key and certificate chain for secure messaging, can be used multiple times to provide key and certificates in multiple files (private key, certificates in leaf\-last order), OR SCP03 keys in hex separated by colon (:) K\-ENC:K\-MAC[:K\-DEK]
+specify private key and certificate chain for secure messaging, can be used multiple times to provide key and certificates in multiple files (private key, certificates in leaf-last order), OR SCP03 keys in hex separated by colon (:) K-ENC:K-MAC[:K-DEK]
 .TP
 \fB\-p\fR, \fB\-\-scp\-password\fR PASSWORD
-specify a password required to access the
-.TP
-\fB\-\-scp\fR \fBfile\fR, \fBif\fR \fBneeded\fR
-
+specify a password required to access the --scp file, if needed
 .TP
 \fB\-l\fR, \fB\-\-log\-level\fR [ERROR|WARNING|INFO|DEBUG|TRAFFIC]
 enable logging at given verbosity level
 .TP
 \fB\-\-log\-file\fR FILE
-write log to FILE instead of printing to stderr (requires \-\-log\-level)
+write log to FILE instead of printing to stderr (requires --log-level)
 .TP
 \fB\-\-diagnose\fR
 show diagnostics information useful for troubleshooting
@@ -40,7 +37,7 @@ show diagnostics information useful for troubleshooting
 show version information about the app
 .TP
 \fB\-\-full\-help\fR
-show \-\-help output, including hidden commands
+show --help output, including hidden commands
 .TP
 \fB\-h\fR, \fB\-\-help\fR
 show this message and exit

ykman/_cli/openpgp.py

@@ -123,6 +123,8 @@ def reset(ctx, force):
 
     This action will wipe all OpenPGP data, and set all PINs to their default
     values.
+
+    The attestation key and certificate will NOT be reset.
     """
     force or click.confirm(
         "WARNING! This will delete all stored OpenPGP keys and data and restore "
@@ -391,19 +393,22 @@ def set_touch(ctx, key, policy, admin_pin, force):
     private key on the YubiKey. The touch policy is set individually for each key slot.
     To see the current touch policy, run the "openpgp info" subcommand.
 
+    WARNING: Setting the touch policy of the attestation key to "fixed" cannot be undone
+    without replacing the attestation private key.
+
     Touch policies:
 
     \b
-    Off (default)   no touch required
-    On              touch required
-    Fixed           touch required, can't be disabled without deleting the private key
-    Cached          touch required, cached for 15s after use
-    Cached-Fixed    touch required, cached for 15s after use, can't be disabled
-                    without deleting the private key
+    Off (default)  no touch required
+    On             touch required
+    Fixed          touch required, can't be disabled without deleting the private key
+    Cached         touch required, cached for 15s after use
+    Cached-Fixed   touch required, cached for 15s after use, can't be disabled
+                   without deleting the private key
 
     \b
-    KEY     key slot to set (sig, dec, aut or att)
-    POLICY  touch policy to set (on, off, fixed, cached or cached-fixed)
+    KEY            key slot to set (sig, dec, aut or att)
+    POLICY         touch policy to set (on, off, fixed, cached or cached-fixed)
     """
     session = ctx.obj["session"]
     policy_name = policy.name.lower().replace("_", "-")
@@ -437,11 +442,15 @@ def set_touch(ctx, key, policy, admin_pin, force):
 @click.argument("private-key", type=click.File("rb"), metavar="PRIVATE-KEY")
 def import_key(ctx, key, private_key, admin_pin):
     """
-    Import a private key (ONLY SUPPORTS ATTESTATION KEY).
-
     Import a private key for OpenPGP attestation.
 
+    The attestation key is by default pre-generated during production with a
+    Yubico-issued key and certificate.
+
+    WARNING: This private key cannot be recovered once overwritten!
+
     \b
+    KEY          key slot to import to (only 'att' supported)
     PRIVATE-KEY  file containing the private key (use '-' to use stdin)
     """
     session = ctx.obj["session"]
@@ -555,7 +564,7 @@ def delete_certificate(ctx, key, admin_pin):
     Delete an OpenPGP certificate.
 
     \b
-    KEY         Key slot to delete certificate from (sig, dec, aut, or att).
+    KEY  key slot to delete certificate from (sig, dec, aut, or att)
     """
     session = ctx.obj["session"]