Manpage update

2 files changed, 93 insertions, 34 deletions

diff --git a/share/man/keyringer.1 b/share/man/keyringer.1
index 9b6a2f5..c140dc5 100644
--- a/share/man/keyringer.1
+++ b/share/man/keyringer.1
@@ -1,4 +1,4 @@
-.TH KEYRINGER 1 "Sep 10, 2013" "Keyringer User Manual"
+.TH KEYRINGER 1 "Oct 24, 2013" "Keyringer User Manual"
 .SH NAME
 .PP
 keyringer - encrypted and distributed secret sharing software
@@ -7,8 +7,14 @@ keyringer - encrypted and distributed secret sharing software
 keyringer <\f[I]keyring\f[]> <\f[I]action\f[]> [\f[I]options\f[]]...
 .SH DESCRIPTION
 .PP
-Keyringer lets you manage and share secrets using GPG and git with
-custom commands to encrypt, decrypt, recrypt, create key pairs, etc.
+Keyringer lets you manage and share secrets using GnuPG and Git in a
+distributed fashion.
+.PP
+It has custom commands to encrypt, decrypt and recrypt secrets as well
+as create key pairs and supports encryption to multiple recipients and
+groups of different recipients to ensure the same repository can be
+shared with a workgroup but allowing to keep some secrets available just
+to subsets of that group.
 .PP
 Secrets are encrypted using GPG and added to a git tree so later then
 can be synced with remote branches.
@@ -58,10 +64,12 @@ No spaces are allowed in the secret name.
 .PP
 Secret manipulation actions do not commit changes into the secret
 repository.
-After any manipulation, the user has to manually commit the changes
-using the git wrapper action.
+Instead, the user has to manually commit the changes using the git
+wrapper action.
 .PP
-append <\f[I]secret\f[]> : Append contents into a secret.
+append <\f[I]secret\f[]> : Append contents into a secret by decrypting
+the secret, appending lines read from the standard input and encrypting
+again.
 .PP
 append-batch <\f[I]secret\f[]> : Append contents into a secret, batch
 mode.
@@ -71,10 +79,12 @@ decrypt <\f[I]secret\f[]> : Decrypts a secret into standard output.
 del <\f[I]secret\f[]> : Removes a secret using git.
 After deleting a secret a git commit and push is still needed to update
 remote repositories.
-To completely remove a file from a keyring, you should also rewrite the
-git history by yourself.
 .PP
-edit <\f[I]secret\f[]> : Edits a secret by temporarily decrypting it,
+Please note that this command \f[B]does not remove the secret from the
+git history.\f[] To completely remove a file from a keyring, you should
+also rewrite the git history by yourself.
+.PP
+edit <\f[I]secret\f[]> : Edit a secret by temporarily decrypting it,
 opening the decrypted copy into the text editor defined by the
 \f[I]$EDITOR\f[] environment variable and then recrypting it again.
 .PP
@@ -88,7 +98,12 @@ genpair <\f[I]ssh\f[]|\f[I]gpg\f[]|\f[I]ssl\f[]|\f[I]ssl-self\f[]>
 [\f[I]options\f[]] : Wrapper to generete encryption keypairs, useful for
 automated key deployment.
 .PP
-open <\f[I]secret\f[]> : Open a secret using xdg-open.
+open <\f[I]secret\f[]> : Decrypt a secret into a temporary folder and
+opening it using xdg-open which then tries to figure out the file type
+and calling the associated application.
+.PP
+After the application exits, keyringer encrypts the temporary decrypted
+file again into the secret file.
 .PP
 recrypt <\f[I]secret\f[]> : Recrypts a secret by decrypting it and
 recrypting again.
@@ -108,6 +123,10 @@ saved into the repository, making it available for all users with access
 to the repository and hence is a \f[I]global\f[] configuration stanza
 for a given keyring.
 .PP
+Options are written using the \f[I]KEY=VALUE\f[] syntax.
+All lines starting with the hash (#) character are interpreted as
+comments.
+.PP
 preferences <\f[I]ls\f[]|\f[I]edit\f[]|\f[I]add\f[]> : List, edit or add
 \f[I]user\f[] preferences for a given repository.
 .PP
@@ -115,11 +134,18 @@ User preferences are specific configurations for the keyring which are
 saved into the user\[aq]s keyringer folder (\f[C]$HOME/.keyringer/\f[])
 hence not shared with the other users.
 .PP
-recipients <\f[I]ls\f[]|\f[I]edit\f[]> <\f[I]recipient-file\f[]> : List
-or edit recipient configuration.
+Preferences are written using the \f[I]KEY=VALUE\f[] syntax.
+All lines starting with the hash (#) character are interpreted as
+comments.
+.PP
+usage : Show keyringer usage information.
+.PP
+recipients <\f[I]ls\f[]|\f[I]edit\f[]> <\f[I]recipient-file\f[]> : List,
+create or edit recipient configuration.
 .PP
 Recipient files are lists of OpenPGP public key fingerprints which are
-used by keyringer when encrypting secrets.
+used by keyringer when encrypting secrets and associated with email
+aliases.
 .PP
 Keyringer uses a default recipient file and supports custom
 \f[I]recipient-files\f[] which overrides the default recipient file
@@ -133,19 +159,25 @@ will result in a file
 \f[C]$KEYRING_FOLDER/keys/accounting/bank-accounts.asc\f[] encrypted
 using the public keys listed in
 \f[C]$KEYRING_FOLDER/config/recipients/accounting\f[] config file.
+.PP
+Each line in a recipients file has entries in the form of
+\[aq]john\@doe.com XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\[aq], where
+\f[I]john\@doe.com\f[] is an alias for the GPG public key whose
+fingerprint is \f[I]XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX.\f[]
+.PP
+All lines starting with the hash (#) character are interpreted as
+comments.
 .SS OPTIONS
 .PP
 ls : List all existing recipient files.
 .PP
 edit : Create or edit a recipient-file.
 .PP
-Edition happens using the editor specified by the \f[C]$EDITOR\f[]
+Editing happens using the editor specified by the \f[C]$EDITOR\f[]
 environment variable.
 .PP
 The required parameter \f[I]recipient-file\f[] is taken relativelly from
 the \f[C]$KEYRING_FOLDER/config/recipients/\f[] folder.
-.PP
-usage : Show keyringer usage information.
 .SH FILES
 .PP
 $HOME/.keyringer/config : User\[aq]s main configuration file used to map
diff --git a/share/man/keyringer.1.mdwn b/share/man/keyringer.1.mdwn
index d7fb2a6..e4713bd 100644
--- a/share/man/keyringer.1.mdwn
+++ b/share/man/keyringer.1.mdwn
@@ -1,6 +1,6 @@
 % KEYRINGER(1) Keyringer User Manual
 % Silvio Rhatto
-% Sep 10, 2013
+% Oct 24, 2013
 
 # NAME
 
@@ -12,11 +12,17 @@ keyringer <*keyring*> <*action*> [*options*]...
 
 # DESCRIPTION
 
-Keyringer lets you manage and share secrets using GPG and git with custom
-commands to encrypt, decrypt, recrypt, create key pairs, etc.
+Keyringer lets you manage and share secrets using GnuPG and Git in a
+distributed fashion.
 
-Secrets are encrypted using GPG and added to a git tree so later then can
-be synced with remote branches.
+It has custom commands to encrypt, decrypt and recrypt secrets as well as
+create key pairs and supports encryption to multiple recipients and groups of
+different recipients to ensure the same repository can be shared with a
+workgroup but allowing to keep some secrets available just to subsets of that
+group.
+
+Secrets are encrypted using GPG and added to a git tree so later then can be
+synced with remote branches.
 
 # ACTIONS
 
@@ -58,11 +64,12 @@ pathname.
 No spaces are allowed in the secret name.
 
 Secret manipulation actions do not commit changes into the secret repository.
-After any manipulation, the user has to manually commit the changes using the
-git wrapper action.
+Instead, the user has to manually commit the changes using the git wrapper
+action.
 
 append <*secret*>
-:  Append contents into a secret.
+:  Append contents into a secret by decrypting the secret, appending lines read
+   from the standard input and encrypting again.
 
 append-batch <*secret*>
 :  Append contents into a secret, batch mode.
@@ -72,11 +79,14 @@ decrypt <*secret*>
 
 del <*secret*>
 :  Removes a secret using git. After deleting a secret a git commit and push is still
-   needed to update remote repositories. To completely remove a file from a keyring,
-   you should also rewrite the git history by yourself.
+   needed to update remote repositories.
+
+   Please note that this command **does not remove the secret from the git history.**
+   To completely remove a file from a keyring, you should also rewrite the git
+   history by yourself.
 
 edit <*secret*>
-:  Edits a secret by temporarily decrypting it, opening the decrypted copy into the 
+:  Edit a secret by temporarily decrypting it, opening the decrypted copy into the 
    text editor defined by the *$EDITOR* environment variable and then recrypting it
    again.
 
@@ -91,7 +101,11 @@ genpair <*ssh*|*gpg*|*ssl*|*ssl-self*> [*options*]
 :  Wrapper to generete encryption keypairs, useful for automated key deployment.
 
 open <*secret*>
-:  Open a secret using xdg-open.
+:  Decrypt a secret into a temporary folder and opening it using xdg-open which
+   then tries to figure out the file type and calling the associated application.
+
+   After the application exits, keyringer encrypts the temporary decrypted file
+   again into the secret file.
 
 recrypt <*secret*>
 :  Recrypts a secret by decrypting it and recrypting again. Useful when users are added
@@ -110,6 +124,9 @@ options <*ls*|*edit*|*add*>
    saved into the repository, making it available for all users with access to the
    repository and hence is a *global* configuration stanza for a given keyring.
 
+   Options are written using the *KEY=VALUE* syntax. All lines starting with the
+   hash (#) character are interpreted as comments.
+
 preferences <*ls*|*edit*|*add*>
 :  List, edit or add *user* preferences for a given repository.
 
@@ -117,11 +134,17 @@ preferences <*ls*|*edit*|*add*>
    saved into the user's keyringer folder (`$HOME/.keyringer/`) hence not
    shared with the other users.
 
+   Preferences are written using the *KEY=VALUE* syntax. All lines starting with the
+   hash (#) character are interpreted as comments.
+
+usage
+:  Show keyringer usage information.
+
 recipients <*ls*|*edit*> <*recipient-file*>
-:  List or edit recipient configuration.
+:  List, create or edit recipient configuration.
 
    Recipient files are lists of OpenPGP public key fingerprints which are used
-   by keyringer when encrypting secrets.
+   by keyringer when encrypting secrets and associated with email aliases.
 
    Keyringer uses a default recipient file and supports custom *recipient-files* which
    overrides the default recipient file according to it's matching pathname.
@@ -134,6 +157,13 @@ recipients <*ls*|*edit*> <*recipient-file*>
    public keys listed in `$KEYRING_FOLDER/config/recipients/accounting` config
    file.
 
+   Each line in a recipients file has entries in the form of
+   'john@doe.com XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX', where *john@doe.com*
+   is an alias for the GPG public key whose fingerprint is
+   *XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX.*
+
+   All lines starting with the hash (#) character are interpreted as comments.
+
 ### OPTIONS
 
 ls
@@ -142,15 +172,12 @@ ls
 edit
 :  Create or edit a recipient-file.
 
-   Edition happens using the editor specified by the `$EDITOR`
+   Editing happens using the editor specified by the `$EDITOR`
    environment variable.
 
    The required parameter *recipient-file* is taken relativelly
    from the `$KEYRING_FOLDER/config/recipients/` folder.
 
-usage
-:  Show keyringer usage information.
-
 # FILES
 
 $HOME/.keyringer/config