Improved documentation for sync-secret

1 files changed, 46 insertions, 10 deletions

diff --git a/kiki.hs b/kiki.hs
index 498f41e..8d13f6b 100644
--- a/kiki.hs
+++ b/kiki.hs
@@ -511,21 +511,38 @@ kiki_usage bSecret cmd = putStr $
             ,"kiki sync-secret FLAGS [--keypairs KEYSPEC ...] [--keyrings FILE ...] [--hosts FILE ...]"
             ,"                       [--wallets FILE ...]"
             ,""
-            ,"     sync-secret merges a set of key files into a combined database and then"
-            ,"     uses the database to update all the input files, those inside and outside of"
-            ,"     of the home directory (see --homedir), to have the most complete information."
+            ,"     sync-secret syncs the information inside your OpenGPG keyring with information"
+            ,"     in other files. Information flows both in and out of your keyring."
+            ,""
+            ,"     sync-secret works by first creating a combined database containing all information"
+            ,"     and then updating all files (including OpenGPG files, as well as files specified as"
+            ,"     arguments to the options --keyrings, --wallets, and --hosts) with information from"
+            ,"     from the combined database."
+            ,""
+            ,"     Master keys in keyring files are fleshed out with all known subkeys"
+            ,"     in any file in which they appear. Ordinarily, if a file does not contain the master key"
+            ,"     already, it will not be added. However, in the case of --import or --import-if-authentic"
+            ,"     new master keys may be added to your OpenGPG keyring."
+            ,""
+            ,"     Cryptocoin keys in wallet files are fleshed out with all CryptoCoin subkeys of the working"
+            ,"     key. The working key is updated with new CryptoCoin subkeys from all specified wallets."
+            ,"     Ordinarily, only one wallet is specified on the command line. If multiple wallets are"
+            ,"     specified, they will all have the same keys after the the operation completes."
+            ,""
+            ,"     The --hosts option is experimental and may be removed in the future. Any files given"
+            ,"     as arguments to this option will be assumed to be in the format /etc/hosts, and will"
+            ,"     be updated with any hostname information currently stored within your OpenGPG keyring."
+            ,"     Additionally, if the file has hostnames for the ip corresponding to a master key, then"
+            ,"     then the mastekey is updated with unsigned annotations recording the additional hostnames."
+            ,"     Warning: this effects all master keys, regardless of whether they have secret key"
+            ,"     information, hence the annotations being unsigned."
             ,""
             ,"     The files pubring.gpg and secring.gpg in the directory specified by the"
             ,"     --homedir option are implicitly included in the keyring set even if they"
             ,"     are not included after the --keyrings option."
             ,""
-            ,"     Subkeys that are imported with kiki are given an annotation \"usage@\" which"
-            ,"     indicates what the key is for.  This tag can be used as a SPEC to select a"
-            ,"     particular key.  Master keys may be specified by using fingerprints or by"
-            ,"     specifying a substring of an associated UID."
-            ,""
-            ,"     If no \"INPUT FILE\" options (documented below) are specified, then arguments"
-            ,"     are implicitly interpreted as being KEYSPECs for the --keypairs option."
+            ,"     If KEYSPEC arguments appear prior to any of --keyrings, --wallets, or --hosts,"
+            ,"     then they are interpretted as if arguments to --keypairs."
             ,""
             ,"FLAGS"
             ,"     --help             Gives usage information"
@@ -557,6 +574,25 @@ kiki_usage bSecret cmd = putStr $
             ,"    --keypairs [KEYSPEC ...]"
             ,"        KEYSPEC := tag '=' file  '{' <shell command to create key file> '}'"
             ,"                 | tag '=' file"
+
+            ,"        Specify the paths of private PEM files which either currently contain"
+            ,"        keys to be imported, or lack keys to be exported. If your working key"
+            ,"        has no subkey with the given tag, and the file is empty or does not exist,"
+            ,"        and a shell command is specified in braces, then the shell command will be "
+            ,"        executed in a modified environment with the expectation of creating the PEM"
+            ,"        file for import."
+            ,""
+            ,"        Subkeys that are imported with kiki are given an annotation \"usage@\" which"
+            ,"        indicates what the key is for.  This tag can be used as a SPEC to select a"
+            ,"        particular key. If a specifed PEM file contains a novel key for an existing"
+            ,"        tag, it will import the new key and you will have multiple keys with the same"
+            ,"        tag."
+            ,""
+            ,"        Your OpenGPG keyring contains time stamps for each subkey. Timestamps of newly"
+            ,"        imported keys will reflect the mtimes of the files from which they were imported."
+            ,"        In the case that the key already exists in your OpenGPG keyring as well as in one"
+            ,"        of the specified files, the timestamp in your OpenGPG keyring is not updated."
+            ,""
             ,"        Note that this option is implicit if no options documented in this section"
             ,"        were specified.  See 'kiki help spec' for more information."
             ,""