man page improvements (#830)

* improve command summaries in man pages
* improve some phrasing

man/man1/git-secret-add.1.md

@@ -7,11 +7,12 @@ git-secret-add - starts to track added files.
 
 
 ## DESCRIPTION
-`git secret add` - tells `git secret` which files hold secrets,
-and adds filepath(s) into `.gitsecret/paths/mapping.cfg`.
+`git secret add` - tells `git secret` which files hold secrets.
+
+Adds filepath(s) into `.gitsecret/paths/mapping.cfg`.
 (It is not recommended to alter `.gitsecret/paths/mapping.cfg` manually.)
 
-As of 0.2.6, this command also ensures the filepath is mentioned `.gitignore`
+As of 0.2.6, this command also ensures the filepath is in `.gitignore`
 as the contents are now considered secret and should not be committed into the repository unencrypted.
 
 The `add` action will fail unless there are already users in `git-secret`'s keyring.

man/man1/git-secret-cat.1.md

@@ -7,7 +7,7 @@ git-secret-cat - decrypts files passed on command line to stdout.
 
 
 ## DESCRIPTION
-`git-secret-cat` - Outputs the decrypted contents of the named files to stdout.
+`git-secret-cat` - prints the decrypted contents of the passed files.
 
 As with `git-secret-reveal`, you'll need to have the private key for one of the emails allowed to
 decrypt this repo in your personal keyring.

man/man1/git-secret-changes.1.md

@@ -7,7 +7,7 @@ git-secret-changes - view diff of the hidden files.
 
 
 ## DESCRIPTION
-`git-secret-changes` - show changes between the current versions of secret files and encrypted versions.
+`git-secret-changes` - shows changes between the current versions of secret files and encrypted versions.
 
 If no filenames are provided, changes to all hidden files will be shown. Alternately,
 provide any number of hidden files to this command as arguments, and it will show changes for those files.

man/man1/git-secret-clean.1.md

@@ -7,7 +7,10 @@ git-secret-clean - removes all the hidden files.
 
 
 ## DESCRIPTION
-`git-secret-clean` deletes all files in the current `git-secret` repo that end with `.secret`.
+`git-secret-clean` - deletes all files in the current `git-secret` repo that end with `.secret`.
+
+You can change the extension `git-secret` uses for encrypted files
+with the `SECRETS_EXTENSION` environment variable.
 
 Note that it will delete any files ending in `.secret`, even if they are not tracked by `git-secret`. 
 
@@ -15,8 +18,6 @@ Also note that this command does not delete unencrypted versions of files.
 
 Verbose mode, enabled with the `-v` option, displays the filenames deleted.
 
-You can change the extension `git-secret` uses for encrypted files
-with the `SECRETS_EXTENSION` environment variable.
 
 ## OPTIONS
 

man/man1/git-secret-hide.1.md

@@ -1,4 +1,4 @@
-git-secret-hide - encrypts all added files with the inner keyring.
+git-secret-hide - encrypts all added files with repo keyring.
 ==================================================================
 
 ## SYNOPSIS
@@ -7,13 +7,14 @@ git-secret-hide - encrypts all added files with the inner keyring.
 
 
 ## DESCRIPTION
-`git-secret-hide`  - writes an encrypted version (typically called `filename.txt.secret`)
-of each file added by `git-secret-add` command.
+`git-secret-hide`  - writes an encrypted version of each file added by `git-secret-add` command.
 
 Then anyone enabled via `git secret tell` can decrypt these files. 
 
-Under the hood, `git-secret` uses the keyring of public keys in `.gitsecret/keys` to _encrypt_ files.
-Later a permitted user can use their secret key (typically from their home directory) to _decrypt_ files.
+Under the hood, `git-secret` uses the keyring of public keys in `.gitsecret/keys` to _encrypt_ files,
+encrypted versions are typically called `filename.txt.secret`.
+
+Later permitted users can use their secret key (typically from their home directory) to _decrypt_ files.
 
 It is recommended to encrypt (or re-encrypt) all the files in a `git-secret` repo each
 time `git secret hide` is run.  

man/man1/git-secret-removeperson.1.md

@@ -1,4 +1,4 @@
-git-secret-removeperson - deletes key identified by an email from the inner keyring.
+git-secret-removeperson - removes user's public key from repo keyring.
 ==================================================================================
 
 ## SYNOPSIS

man/man1/git-secret-reveal.1.md

@@ -7,7 +7,7 @@ git-secret-reveal - decrypts all added files.
 
 
 ## DESCRIPTION
-`git-secret-reveal` - decrypts passed files, or all files considered secret by `git-secret` 
+`git-secret-reveal` - decrypts passed files, or all files considered secret by `git-secret`.
 
 Under the hood, `reveal` uses the `gpg --decrypt` command
 and your private key (typically from your personal keyring in your
@@ -15,7 +15,7 @@ home directory) to _decrypt_ files.
 
 Therefore, for this operation to succeed, your personal keyring must contain a private key 
 matching one of the public keys which were used to encrypt the secrets --
-i.e., one of the public keys in `git-secret` repo's keyring when the file was encrypted. 
+i.e., one of the public keys in your repo's `git-secret` keyring when the file was encrypted.