Fix lots of documentation and formatting

1 files changed, 39 insertions, 19 deletions

diff --git a/bin/runcrypt b/bin/runcrypt
index 9d207a4..fe0f3b3 100755
--- a/bin/runcrypt
+++ b/bin/runcrypt
@@ -81,7 +81,7 @@ if ( !@ARGV ) {
     exit 2;
 }
 
-# Create an MRC object
+# Build option set for MRC constructor
 my %opts = (
     sign    => $opt->sign,
     encrypt => $opt->encrypt,
@@ -141,9 +141,9 @@ runcrypt - Encrypt and mail output from command in arguments
 
 =head1 DESCRIPTION
 
-This program applies C<Mail::Run::Crypt> to run a command and send any output
-or error content to the specified address. More information is available in the
-documentation for that module.
+This program applies L<Mail::Run::Crypt|Mail::Run::Crypt> to run a command and
+send any output or error content to the specified address. More information is
+available in the documentation for that module.
 
 =head1 REQUIRED ARGUMENTS
 
@@ -157,17 +157,20 @@ The arguments beyond the options are used as the command name to run:
 
 =item C<--sign>
 
-Whether to sign the output. This defaults to off. A key ID and passphrase file
-will need to be provided for signing to work.
+Whether to sign the output. This defaults to 0. An ID and passphrase file will
+need to be provided for signing to work.
 
 =item C<--encrypt>
 
-Whether to encrypt the output to the recipient. This defaults to on.
+Whether to encrypt the output to the recipient. This defaults to 1.
 
 =item C<--keyid>
 
-The GnuPG key ID that should be used to sign and encrypt the messages. This
-defaults to the value of the environment variable C<RUNCRYPT_KEYID>.
+The GnuPG key ID that should be used to encrypt the messages. This is required
+for signing. It can be any means of identifying the key acceptable to GnuPG;
+the key's 16-byte ("long") hexadecimal ID prefixed with C<0x> is probably the
+best way. This defaults to the value of the environment variable
+C<RUNCRYPT_KEYID>.
 
 It is I<strongly> recommended that a dedicated key and passphrase be used for
 signatures if this is needed. You should carefully consider the consequences of
@@ -188,7 +191,7 @@ This has too many negative security implications.
 
 The recipient address for the encryption portion of the email. This defaults to
 the value of the environment variable C<RUNCRYPT_MAILTO> if that is set, or
-C<MAILTO> failing that, to make it suitable for use in a C<crontab(5)> file.
+C<MAILTO> failing that, to make it suitable for use in a B<crontab(5)> file.
 
 =item C<--name>
 
@@ -223,14 +226,23 @@ The specified passphrase file could not be closed. This is not a fatal error.
 =head1 EXIT STATUS
 
 The program exits with the same exit value of the command that it ran, or 127
-if the command could not be run at all. See the C<bail()> method in
-C<Mail::Run::Crypt>.
+if the command could not be run at all. See the
+L<C<bail()>|Mail::Run::Crypt/bail()> method in
+L<Mail::Run::Crypt|Mail::Run::Crypt>.
 
 =head1 CONFIGURATION
 
 You will need to have a functioning GnuPG public key setup for this to work,
-including the secret key. You should definitely not use your personal key;
-generate one specifically for mail signing and encryption instead.
+including stored keys or a key retrieval system for your recipients. You will
+also need a secret key if you want to sign the messages.
+
+You should I<definitely not> use your personal key for this; generate one
+specifically for mail signing and encryption instead.
+
+I wrote a tutorial on GnuPG key setup, including agent configuration, as part
+of this series:
+
+L<https://sanctum.geek.nz/arabesque/series/gnu-linux-crypto/>
 
 =head1 DEPENDENCIES
 
@@ -242,22 +254,30 @@ Perl 5.10 or newer
 
 =item *
 
-C<Carp>
+L<Carp|Carp>
+
+=item *
+
+L<English|English>
+
+=item *
+
+L<File::stat|File::stat>
 
 =item *
 
-C<Getopt::Long::Descriptive>
+L<Getopt::Long::Descriptive|Getopt::Long::Descriptive>
 
 =item *
 
-C<Mail::Run::Crypt>
+L<Mail::Run::Crypt|Mail::Run::Crypt>
 
 =back
 
 =head1 INCOMPATIBILITIES
 
-This module uses C<Mail::GnuPG> and other GPG-specific code, so it won't work
-with any other OpenPGP implementations.
+This module uses L<Mail::GnuPG|Mail::GnuPG> and other GPG-specific code, so it
+won't work with any other OpenPGP implementations.
 
 =head1 BUGS AND LIMITATIONS