Documentation update, WIP

1 files changed, 161 insertions, 81 deletions

diff --git a/kiki.hs b/kiki.hs
index 8d13f6b..55fe37b 100644
--- a/kiki.hs
+++ b/kiki.hs
@@ -452,7 +452,8 @@ whoseKey rsakey db = filter matchkey (Map.elems db)
 
 
 
-kiki_usage bSecret cmd = putStr $
+kiki_usage :: Bool -> Bool -> Bool -> String -> IO ()
+kiki_usage bExport bImport bSecret cmd = putStr $
         case cmd of
          "show" -> unlines $
             ["kiki show [options...]"
@@ -570,46 +571,6 @@ kiki_usage bSecret cmd = putStr $
             ,"     --show-wk          After the operation completes, output the possibly modified working"
             ,"                        key identity information."
             ,""
-            ,"INPUT FILES"
-            ,"    --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."
-            ,""
-            ,"    --keyrings [FILE ...]"
-            ,"        These files are PGP keyring files.  The format is similar to that of the"
-            ,"        GNU GPG state files: pubring.gpg and secring.gpg.  Those files needn't be"
-            ,"        specified here as they are included implicitly."
-            ,""
-            ,"    --wallets  [FILE ...]"
-            ,"        Bitcoin wallet files.  TODO: document format."
-            ,""
-            ,"    --hosts    [FILE ...]"
-            ,"        EXPERIMENTAL! May be removed in the future.  This option specifies files"
-            ,"        from which to read or write hostname aliases.  The format is the same as"
-            ,"        /etc/hosts on unix systems.  WARNING: hostname aliases may be imported into"
-            ,"        the gpg keyring files, but they are currently NOT signed and may be altered"
-            ,"        in transit."
             ] ++ syncflags 
          "sync-public" -> unlines $
             ["kiki sync-public [options...]"
@@ -724,42 +685,12 @@ kiki_usage bSecret cmd = putStr $
                     ,"                It is considered cross certified if there exists a cross-certified"
                     ,"                'tor' subkey corresponding to the address HOSTNAME.onion."
                     ,""
-                    ,"Merging:"
-                    ,"     --keyrings FILE FILE..."
-                    ,"                Provide keyring files other than the implicit secring.gpg and"
-                    ,"                pubring.gpg in the --homedir.  This option is implicit unless"
-                    ,"                --keypairs or --wallets is used."
-                    ,""]
-                    ++ do
-                       guard bSecret
-                       return $ unlines
-                        ["     --wallets  FILE FILE..."
-                        ,"                Provide wallet files with secret crypto-coin keys in Wallet"
-                        ,"                Import Format.  The keys will be treated as subkeys of your"
-                        ,"                current working key (the one shown by --show-wk)."
-                        ,""
-                        ,"     --keypairs KEYSPEC KEYSPEC..."
-                        ,"                A keypair is a secret key coupled with it's corresponding public"
-                        ,"                key, both of which are ordinarily stored in a single file in pem"
-                        ,"                format. Users incognisant of the fact that the public key (which"
-                        ,"                is also stored separately) is in this file, often think of it as"
-                        ,"                their secret key file."
-                        ,""
-                        ,"                Each KEYSPEC specifies that a key should match the content and"
-                        ,"                timestamp of an external PKCS #1 private RSA key file."
-                        ,"                "
-                        ,"                KEYSPEC ::= SPEC=FILE{CMD} "
-                        ,""
-                        ,"                The form of SPEC is documented elsewhere. If there is only one master"
-                        ,"                key in your keyring and only one key is used for each purpose, then"
-                        ,"                it is possible for SPEC in this case to merely be a tag which offers"
-                        ,"                information about what this key is used for, for example, any of"
-                        ,"                `tor', `ssh-client', `ssh-host', or `strongswan' will do."
-                        ,""
-                        ,"                If neither SPEC or FILE match any keys, then the CMD will be "
-                        ,"                executed in order to create the FILE."
-                        ,"                (See 'kiki help spec' for more information.)"
-                        ,""]
+                    ,"SPECIFYING FILES:"
+                    ] ++ documentKeyPairsOption bExport bImport bSecret
+                      ++ documentKeyRingsOption bExport bImport bSecret
+                      ++ documentWalletsOption  bExport bImport bSecret
+                      ++ documentHostsOption    bExport bImport bSecret
+            keyspec :: [String]
             keyspec = -- unlines $
                  ["Specifying keys on the kiki command line:"
                  ,""
@@ -797,6 +728,154 @@ kiki_usage bSecret cmd = putStr $
                  ,"      5E24CD442AA6965D2012E62A905C24185D5379C2"
                  ]
 
+documentKeyPairsOption :: Bool -> Bool -> Bool -> [String]
+documentKeyPairsOption bExport bImport bSecret = 
+            ["    --keypairs [KEYSPEC ...]"
+            ,"                A keypair is a secret key coupled with it's corresponding public"
+            ,"                key, both of which are ordinarily stored in a single file in PEM"
+            ,"                format. Users incognisant of the fact that the public key (which"
+            ,"                is also stored separately) is in this file, often think of it as"
+            ,"                their secret key file."
+            ,""
+            ] ++ case (bExport,bImport,bSecret) of
+                (True,True,True) -> -- sync-secret
+                    ["                This option specifies the paths of such 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."
+                    ,""
+                    ] ++ afterSecond
+                (True,True,False) -> -- sync-public
+                    ["                This option specifies the paths of PEM files, of both the"
+                    ,"                public and private variety, which either currently contain"
+                    ,"                public keys to be imported, or lack public 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. Unlike the sync-secret command, this command"
+                    ,"                leaves no possibility of secret key information leaking from"
+                    ,"                your OpenGPG keyring into specified files."
+                    ] ++ afterSecond
+                (False,True,True) -> -- import-secret
+                    ["                This option specifies the paths of such private PEM files which"
+                    ,"                contain keys to be imported.  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. Files external"
+                    ,"                to your OpenGPG keyring will not be modified by this command."
+                    ] ++ afterSecond
+                (False,True,False) -> -- import-public
+                    ["                This option specifies the paths of PEM files, of both the"
+                    ,"                public and private variety, which either currently contain"
+                    ,"                contain keys to be imported.  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. Files external"
+                    ,"                to your OpenGPG keyring will not be modified by this command."
+                    ,"                Unlike the import-secret command, this command leaves no"
+                    ,"                possibility of secret key information leaking from your OpenGPG"
+                    ,"                keyring.  "
+                    ] ++ afterSecond
+                (True,False,True) -> -- export-secret
+                    ["                This option specifies the paths of such private PEM files, of"
+                    ,"                both the public variety, to which kiki will export keys. These"
+                    ,"                files will be updated with information from your OpenGPG"
+                    ,"                keyring, but your OpenGPG keyring will not be modified by this"
+                    ,"                command. Unlike the export-secret comamnd, this command leaves"
+                    ,"                no possibility that secret key information will leak from your"
+                    ,"                OpenGPG keyring."
+                    ] ++ afterSecond
+                (True,False,False) -> -- export-public
+                    ["                This option specifies the paths of PEM files, of the private or"
+                    ,"                public variety, which lack public keys to be exported.  Unlike"
+                    ,"                the export-secret command, this command leaves no possibility"
+                    ,"                of secret key information leaking from your OpenGPG keyring"
+                    ,"                into the specified files."
+                    ] ++ afterSecond
+                _ -> afterSecond
+    where afterSecond = 
+            ["                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 imported,"
+            ,"                and you will have multiple keys with the same tag."
+            ,""
+            ,"                Each KEYSPEC specifies that a key should match the content and"
+            ,"                timestamp of an external PKCS #1 private RSA key file."
+            ,"                "
+            ,"                KEYSPEC ::= tag '=' file"
+            ] ++ if bImport then "                          | tag '=' file  '{' <shell command to create key file> '}'":next
+                            else next
+          next =
+            [""
+            ,"                Or in more complicated cases,"
+            ,""
+            ,"                KEYSPEC ::= SPEC '=' file"
+            ] ++ if bImport then "                          | SPEC '=' file  '{' <shell command to create key file> '}'":next'
+                            else next'
+          next' =
+            [""
+            ,"                where the format of SPEC is documented in 'kiki help spec'."
+            ,""
+            ,"                If there is only one master key in your keyring and only one"
+            ,"                key is used for each purpose, then it is possible for SPEC in"
+            ,"                this case to merely be a tag which offers information about"
+            ,"                what this key is used for, for example, any of `tor',"
+            ,"                `ssh-client', `ssh-host', or `strongswan' will do."] ++ next''
+          next'' = if bImport then timeStamps ++ next''' else next'''  
+          timeStamps = 
+            [""
+            ,"                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."]
+          next'''=
+            [""
+            ,"                Note that this option is implicit if no options documented in"
+            ,"                this section were specified.  See 'kiki help spec' for more"
+            ,"                information."
+            ,""
+            ,"                (See 'kiki help spec' for more information.)"
+            ]
+
+documentKeyRingsOption :: Bool -> Bool -> Bool -> [String]
+documentKeyRingsOption bExport bImport bSecret =
+            ["    --keyrings [FILE ...]"
+            ,"                These files are PGP keyring files.  The format is similar to"
+            ,"                that of the GNU GPG state files: pubring.gpg and secring.gpg."
+            ,"                Those files needn't be specified here as they are included"
+            ,"                implicitly."
+            ,""
+            ]
+
+documentWalletsOption :: Bool -> Bool -> Bool -> [String]
+documentWalletsOption bExport bImport bSecret =
+              ["     --wallets  FILE FILE..."
+              ,"                Provide wallet files with secret crypto-coin keys in Wallet"          
+              ,"                Import Format.  The keys will be treated as subkeys of your"          
+              ,"                current working key (the one shown by --show-wk)."                    
+              ,""] 
+
+documentHostsOption :: Bool -> Bool -> Bool -> [String]
+documentHostsOption bExport bImport bSecret =
+            ["    --hosts    [FILE ...]"
+            ,"        EXPERIMENTAL! May be removed in the future.  This option specifies files"
+            ,"        from which to read or write hostname aliases.  The format is the same as"
+            ,"        /etc/hosts on unix systems.  WARNING: hostname aliases may be imported into"
+            ,"        the gpg keyring files, but they are currently NOT signed and may be altered"
+            ,"        in transit."
+            ,""]
+            
+            
+
 processArgs sargspec polyVariadicArgs defaultPoly args_raw = (sargs,margs)
     where
         (args,trail1) = break (=="--") args_raw
@@ -854,6 +933,7 @@ buildStreamInfo rtyp ftyp = StreamInfo { typ = ftyp
                                        , initializer = Nothing
                                        , transforms = [] }
 
+
 sync :: Bool -> Bool -> Bool -> String -> [String] -> IO ()
 sync bExport bImport bSecret cmdarg args_raw = do
     let (sargs,margs) = processArgs sargspec polyVariadicArgs "--keyrings" args_raw
@@ -943,7 +1023,7 @@ sync bExport bImport bSecret cmdarg args_raw = do
             , opHome = homespec
             }
 
-    (\f -> maybe f (const $ kiki_usage bSecret cmdarg) $ Map.lookup "--help" margs) $ do
+    (\f -> maybe f (const $ kiki_usage bExport bImport bSecret cmdarg) $ Map.lookup "--help" margs) $ do
     KikiResult rt report <- runKeyRing kikiOp 
 
     case rt of
@@ -1008,8 +1088,8 @@ kiki "help" [] = do
     return ()
 
 kiki "help" args = forM_ args $ \arg -> case lookup arg commands of
-    Nothing | arg == "spec" -> kiki_usage False arg 
-    Nothing | arg == "SPEC" -> kiki_usage False arg 
+    Nothing | arg == "spec" -> kiki_usage False False False arg 
+    Nothing | arg == "SPEC" -> kiki_usage False False False arg 
     Nothing -> putStrLn $ "No help available for commmand '" ++ arg ++ "'."
     _       -> kiki arg ["--help"]
 
@@ -1055,7 +1135,7 @@ kiki "show" args = do
             , opHome = homespec
             }
 
-    (\f -> maybe f (const $ kiki_usage False "show") $ Map.lookup "--help" margs) $ do
+    (\f -> maybe f (const $ kiki_usage False False False "show") $ Map.lookup "--help" margs) $ do
     KikiResult rt report <- runKeyRing kikiOp 
 
     input_key <- maybe (return Nothing)