Improving documentation...

1 files changed, 91 insertions, 66 deletions

diff --git a/kiki.hs b/kiki.hs
index 55fe37b..000dfa2 100644
--- a/kiki.hs
+++ b/kiki.hs
@@ -513,7 +513,11 @@ kiki_usage bExport bImport bSecret cmd = putStr $
             ,"                       [--wallets FILE ...]"
             ,""
             ,"     sync-secret syncs the information inside your OpenGPG keyring with information"
-            ,"     in other files. Information flows both in and out of your keyring."
+            ,"     in other files. Information flows both in and out of your keyring. This one command"
+            ,"     is powerful enough to impliment all the functionality of kiki commands in the import-*,"
+            ,"     export-*, and sync-* families. Those other commands are mainly added to facilitate"
+            ,"     a redundant safe gaurd which restricts the flow of information in such a way that is"
+            ,"     theoretically less error prone."
             ,""
             ,"     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"
@@ -531,10 +535,10 @@ kiki_usage bExport bImport bSecret cmd = putStr $
             ,"     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"
+            ,"     as arguments to this option will be assumed to be in the format of /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."
+            ,"     then the masterkey 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."
             ,""
@@ -545,33 +549,7 @@ kiki_usage bExport bImport bSecret cmd = putStr $
             ,"     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"
-            ,""
-            ,"     --homedir PATH     Specifies the path where pubring.gpg and secring.gpg are located."
-            ,"                        Typically this would be your ~/.gnupg or the contents of the"
-            ,"                        GNUPGHOME environment variable."
-            ,""
-            ,"     --passphrase-fd FD The file descriptor from which to read a passphrase."
-            ,""
-            ,"     --import           Update home keyring files (pubring.gpg and secring.gpg) with"
-            ,"                        new master keys found in the input files specified by the"
-            ,"                        --keyrings option.  Note that new subkeys for known master-key"
-            ,"                        identities will be imported regardless."
-            ,""
-            ,"     --import-if-authentic"
-            ,"                        Like --import except that it requires a signature from the"
-            ,"                        working key on any new identities that are imported into the"
-            ,"                        home keyring files."
-            ,""
-            ,"     --autosign         Create or sign a self-authenticating UID based on tor key."
-            ,"                        Combine this with --import-if-authentic to import self-authenticating"
-            ,"                        identities that may not have previously been signed."
-            ,""
-            ,"     --show-wk          After the operation completes, output the possibly modified working"
-            ,"                        key identity information."
-            ,""
-            ] ++ syncflags 
+            ] ++ syncflags ++ specifyingFiles
          "sync-public" -> unlines $
             ["kiki sync-public [options...]"
             ,""
@@ -592,7 +570,7 @@ kiki_usage bExport bImport bSecret cmd = putStr $
             ,"     specifying a substring of an associated UID."
             ,""
             ,"     (See 'kiki help spec' for more information.)"
-            ] ++ syncflags 
+            ] ++ syncflags ++ specifyingFiles
          "import-secret" -> unlines $
             ["kiki import-secret [options...]"
             ,""
@@ -600,7 +578,9 @@ kiki_usage bExport bImport bSecret cmd = putStr $
             ,"     alter any files outside of the home directory (see --homedir)."
             ,""
             ,"     The files pubring.gpg and secring.gpg in the directory specified by the "
-            ,"     --homedir option are implicitly included in the keyring set."
+            ,"     --homedir option are implicitly included in the keyring set. Unlike the"
+            ,"     sync-secret command, information will flow into these files, but not out"
+            ,"     of them."
             ,""
             ,"     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"
@@ -608,7 +588,7 @@ kiki_usage bExport bImport bSecret cmd = putStr $
             ,"     specifying a substring of an associated UID."
             ,""
             ,"     (See 'kiki help spec' for more information.)"
-            ] ++ syncflags 
+            ] ++ syncflags ++ specifyingFiles
          "import-public" -> unlines $
             ["kiki import-public [options...]"
             ,""
@@ -629,18 +609,21 @@ kiki_usage bExport bImport bSecret cmd = putStr $
             ,"     specifying a substring of an associated UID."
             ,""
             ,"     (See 'kiki help spec' for more information.)"
-            ] ++ syncflags 
+            ] ++ syncflags  ++ specifyingFiles
          "export-secret" -> unlines $
             ["kiki export-secret [options...]"
             ,""
             ,"     export-secret updates a set of key files using information from your keyring."
             ,""
-            ,"     The files pubring.gpg and secring.gpg in the directory specified by the "
-            ,"     --homedir option are implicitly included in the keyring set."
+            ,"     The files pubring.gpg and secring.gpg in the directory specified by the"
+            ,"     --homedir option are implicitly included in the keyring set. Unlike with the"
+            ,"     sync-secret command, information only flows out of these files and not in to"
+            ,"     them. Barring this however, the usage and behavior of export-secret is similar"
+            ,"     to that of sync-secret."
             ,""
             ,"     (See 'kiki help spec' for more information.)"
             ,""
-            ] ++ syncflags 
+            ] ++ syncflags ++  specifyingFiles 
          "export-public" -> unlines $
             ["kiki export-public [options...]"
             ,""
@@ -653,39 +636,43 @@ kiki_usage bExport bImport bSecret cmd = putStr $
             ,""
             ,"     (See 'kiki help spec' for more information.)"
             ,""
-            ] ++ syncflags 
+            ] ++ specifyingFiles 
          "spec" -> unlines keyspec
         where 
             commonOptions :: [String]
             commonOptions =
-                ["     --homedir DIR"
-                ,"                Where to find the the files secring.gpg and pubring.gpg. The "
-                ,"                default location is taken from the environment variable "
-                ,"                GNUPGHOME."
+                ["     --help"
+                ,"                Gives usage information"
                 ,""
-                ,"     --passphrase-fd N"
-                ,"                Read passphrase from the given file descriptor."
+                ,"     --homedir DIR"
+                ,"                Where to find the files secring.gpg and pubring.gpg. The"
+                ,"                default location is taken from the environment variable"
+                ,"                GNUPGHOME. If this environment variable is not set and no"
+                ,"                directory is specified using this option then a hardcoded"
+                ,"                default of ~/.gnupg is assumed. "
+                ,""
+                ,"                WARNING: Confusingly, this is *not* your home directory as"
+                ,"                given by the HOME environment variable. The option is named"
+                ,"                or rather misnamed in a fashion similar to the gpg option with"
+                ,"                exactly the same functionality."
+                ,""] ++ documentPassphraseFDFlag bExport bImport bSecret ++ showwk
+            showwk :: [String]
+            showwk =
+                ["     --show-wk"
+                ,"                After the operation completes, output the possibly modified"
+                ,"                working key identity information."
                 ,""
                 ]
             syncflags :: [String]
             syncflags =
                 [""
-                ,"Flags:"] ++ commonOptions ++
-                    ["     --import   Add master keys to pubring.gpg.  Without this option, only UID"
-                    ,"                and subkey data is updated. "
-                    ,""
-                    ,"     --import-if-authentic"
-                    ,"                Add signed master keys to pubring.gpg.  Like --import except that"
-                    ,"                only keys with signatures from the working key (--show-wk) are"
-                    ,"                imported."
-                    ,""
-                    ,"     --autosign Sign all cross-certified tor-style UIDs."
-                    ,"                A tor-style UID is of the form:"
-                    ,"                        Anonymous <root@HOSTNAME.onion>"
-                    ,"                It is considered cross certified if there exists a cross-certified"
-                    ,"                'tor' subkey corresponding to the address HOSTNAME.onion."
-                    ,""
-                    ,"SPECIFYING FILES:"
+                ,"Flags:"] ++ commonOptions
+                           ++ documentImportFlag            bExport bImport bSecret
+                           ++ documentImportIfAuthenticFlag bExport bImport bSecret
+                           ++ documentAutoSignFlag          bExport bImport bSecret
+            specifyingFiles :: [String]
+            specifyingFiles =
+                    ["SPECIFYING FILES:"
                     ] ++ documentKeyPairsOption bExport bImport bSecret
                       ++ documentKeyRingsOption bExport bImport bSecret
                       ++ documentWalletsOption  bExport bImport bSecret
@@ -728,6 +715,37 @@ kiki_usage bExport bImport bSecret cmd = putStr $
                  ,"      5E24CD442AA6965D2012E62A905C24185D5379C2"
                  ]
 
+documentPassphraseFDFlag bExport bImport bSecret = 
+                ["     --passphrase-fd FD"
+                ,"                The file descripter from which to read a passphrase. If FD is"
+                ,"                0, then the passphrase is inputted via stdin. Note that this"
+                ,"                requires the user to issue CTRL-D to send EOF, so that kiki"
+                ,"                knows to continue."
+                ,""]
+
+documentImportFlag bExport bImport bSecret =
+    if bImport  then
+                    ["     --import   Add master keys to pubring.gpg.  Without this option, only UID"
+                    ,"                and subkey data is updated. "
+                    ,""]
+                else []
+
+documentImportIfAuthenticFlag bExport bImport bSecret =
+    if bImport  then
+                    ["     --import-if-authentic"
+                    ,"                Add signed master keys to pubring.gpg.  Like --import except that"
+                    ,"                only keys with signatures from the working key (--show-wk) are"
+                    ,"                imported."
+                    ,""]
+                else []
+
+documentAutoSignFlag bExport bImport bSecret =
+                    ["     --autosign Sign all cross-certified tor-style UIDs."
+                    ,"                A tor-style UID is of the form:"
+                    ,"                        Anonymous <root@HOSTNAME.onion>"
+                    ,"                It is considered cross certified if there exists a cross-certified"
+                    ,"                'tor' subkey corresponding to the address HOSTNAME.onion."
+                    ,""]
 documentKeyPairsOption :: Bool -> Bool -> Bool -> [String]
 documentKeyPairsOption bExport bImport bSecret = 
             ["    --keypairs [KEYSPEC ...]"
@@ -759,6 +777,7 @@ documentKeyPairsOption bExport bImport bSecret =
                     ,"                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"
@@ -768,6 +787,7 @@ documentKeyPairsOption bExport bImport bSecret =
                     ,"                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"
@@ -781,6 +801,7 @@ documentKeyPairsOption bExport bImport bSecret =
                     ,"                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"
@@ -790,6 +811,7 @@ documentKeyPairsOption bExport bImport bSecret =
                     ,"                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"
@@ -797,6 +819,7 @@ documentKeyPairsOption bExport bImport bSecret =
                     ,"                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 = 
@@ -844,6 +867,7 @@ documentKeyPairsOption bExport bImport bSecret =
             ,"                information."
             ,""
             ,"                (See 'kiki help spec' for more information.)"
+            ,""
             ]
 
 documentKeyRingsOption :: Bool -> Bool -> Bool -> [String]
@@ -858,7 +882,7 @@ documentKeyRingsOption bExport bImport bSecret =
 
 documentWalletsOption :: Bool -> Bool -> Bool -> [String]
 documentWalletsOption bExport bImport bSecret =
-              ["     --wallets  FILE FILE..."
+              ["    --wallets  [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)."                    
@@ -867,11 +891,12 @@ documentWalletsOption bExport bImport bSecret =
 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."
+            ,"                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."
             ,""]