Fix lots of documentation and formatting

3 files changed, 164 insertions, 110 deletions

diff --git a/README.markdown b/README.markdown
index 5327928..6e6515e 100644
--- a/README.markdown
+++ b/README.markdown
@@ -8,21 +8,22 @@ Version 0.01
 
 # DESCRIPTION
 
-This module runs commands with `IPC::Run3::run3()`, and collects any standard
-output and standard error it emits. If there is any standard output or standard
-error content, it is signed and/or encrypted with GnuPG, and then mailed to a
-specified recipient address (each stream separately).
+This module runs a system command with [IPC::Run3](https://metacpan.org/pod/IPC::Run3), and collects any
+standard output and standard error it emits. If there is any standard output or
+standard error content, it is encrypted and optionally signed with GnuPG, and
+then each stream's content is mailed separately to a specified recipient
+address.
 
 The idea is to allow you to view the output of automated commands while having
-the content encrypted as it passes through to your mailserver, and (optionally)
-have some assurance that the content was actually generated by the server
-concerned. `cron(8)` scripts are the ideal use case, but this would also work
-with `at(1)` or anything else that might non-interactively run jobs for which
+the content encrypted as it passes through to your mailserver, and optionally
+to have some assurance that the content was actually generated by the server
+concerned. **cron(8)** scripts are the ideal use case, but this would also work
+with **at(1)**, or anything else that might non-interactively run jobs for which
 output is significant.
 
-You probably want to call this with the `runcrypt(1)` program installed by
-this distribution, which provides a means to set the properties for the module
-via environment variables or command-line options.
+You will probably want to call this with the [**runcrypt(1)**](https://metacpan.org/pod/runcrypt) program
+provided by this distribution, which includes a means to set the properties for
+the module via environment variables or command line options.
 
 # SYNOPSIS
 
@@ -35,7 +36,7 @@ via environment variables or command-line options.
     ...
     my $mrc = Mail::Run::Crypt->new(
         sign       => 1,
-        keyid      => 0x1234DEAD,
+        keyid      => '0x1234DEAD5678BEEF',
         passphrase => 'able was i ere i saw elba',
         mailto     => 'you@example.net',
     );
@@ -44,85 +45,99 @@ via environment variables or command-line options.
 
 # SUBROUTINES/METHODS
 
-## **new(%opts)**
+## `new(%opts)`
 
-Constructor accepts the following named parameters:
+Constructor method; accepts the following named parameters:
+
+- `mailto`
+
+    The recipient email address for the content. This is always required.
 
 - `sign`
 
-    Whether to sign the command output. This defaults to off. A key ID and
-    passphrase will be required for signing.
+    Whether to sign the command output. This defaults to 0. A `keyid` and
+    `passphrase` will be required for signing.
 
 - `encrypt`
 
-    Whether to encrypt the command output. This defaults to on.
+    Whether to encrypt the command output. This defaults to 1.
 
 - `keyid`
 
-    The GnuPG key ID that should be used to encrypt the messages.
+    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 `0x` is probably the
+    best way. 
 
 - `passphrase`
 
-    The passphrase used to decrypt the key.
-
-- `mailto`
-
-    The recipient email address for the content.
+    The passphrase used to decrypt the key. This is required for signing.
 
 - `name`
 
-    (Optional) The name of the object. When called from the `runcrypt(1)`
-    program, this will be the string "runcrypt".
+    (Optional) The name of the object. When called from the
+    [**runcrypt(1)**](https://metacpan.org/pod/runcrypt) program, this will be the string "runcrypt".
+    Otherwise, it will default to this package's name.
 
-## **run(@command)**
+## `run(@command)`
 
-Run the specified arguments as a command with `IPC::Run3::run3()`, and email
-any output or error content to the email recipient.
+Run the specified arguments as a command with [IPC::Run3](https://metacpan.org/pod/IPC::Run3), and email
+any output or error content to the email recipient, encrypting and/or signing
+as configured. Returns 1 if the command succeeded, 0 otherwise. Use
+[`bail()`](#bail) to get the actual exit code if needed.
 
-## **bail()**
+## `bail()`
 
 Return the exit status of the most recently run command, or 127 if no command
 has been successfully run.
 
 # DIAGNOSTICS
 
-- mailto required
+- `mailto required`
 
     The required `mailto` property was not passed in the constructor.
 
-- keyid required for signing
+- `keyid required for signing`
 
     Signing was specified, but no `keyid` attribute was passed in the constructor.
 
-- passphrase required for signing
+- `passphrase required for signing`
 
     Signing was specified, but no `passphrase` attribute was passed in the constructor.
 
-- command failed: %s
+- `command failed: %s`
 
-    The command did not merely fail, it could not even be started, with the given
-    error string. This is typically due to problems finding the executable.
+    The command could not be run at all, raising the given error string. This is
+    typically due to problems finding the executable.
 
 # CONFIGURATION AND ENVIRONMENT
 
 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 _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:
+
+[https://sanctum.geek.nz/arabesque/series/gnu-linux-crypto/](https://sanctum.geek.nz/arabesque/series/gnu-linux-crypto/)
 
 # DEPENDENCIES
 
 - Perl v5.10.0 or newer
-- `Carp`
-- `Const::Fast`
-- `English`
-- `IPC::Run3`
-- `Mail::GnuPG`
-- `MIME::Entity`
+- [Carp](https://metacpan.org/pod/Carp)
+- [Const::Fast](https://metacpan.org/pod/Const::Fast)
+- [English](https://metacpan.org/pod/English)
+- [IPC::Run3](https://metacpan.org/pod/IPC::Run3)
+- [Mail::GnuPG](https://metacpan.org/pod/Mail::GnuPG)
+- [MIME::Entity](https://metacpan.org/pod/MIME::Entity)
 
 # INCOMPATIBILITIES
 
-This module uses `Mail::GnuPG` and other GPG-specific code, so it won't work
-with any other OpenPGP implementations.
+This module uses [Mail::GnuPG](https://metacpan.org/pod/Mail::GnuPG) and other GnuPG-specific code, so
+it won't work with other OpenPGP implementations.
 
 # BUGS AND LIMITATIONS
 
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
 
diff --git a/lib/Mail/Run/Crypt.pm b/lib/Mail/Run/Crypt.pm
index 5631acb..64dd7e5 100644
--- a/lib/Mail/Run/Crypt.pm
+++ b/lib/Mail/Run/Crypt.pm
@@ -35,7 +35,7 @@ sub new {
       or croak 'mailto required';
 
     # Default the instance name to the package name if it wasn't given;
-    # runcrypt(1p) will pass it in
+    # runcrypt(1) will pass it in
     $self->{name} //= $class;
 
     # We default to encrypting but not signing
@@ -139,21 +139,22 @@ Version 0.01
 
 =head1 DESCRIPTION
 
-This module runs commands with C<IPC::Run3::run3()>, and collects any standard
-output and standard error it emits. If there is any standard output or standard
-error content, it is signed and/or encrypted with GnuPG, and then mailed to a
-specified recipient address (each stream separately).
+This module runs a system command with L<IPC::Run3|IPC::Run3>, and collects any
+standard output and standard error it emits. If there is any standard output or
+standard error content, it is encrypted and optionally signed with GnuPG, and
+then each stream's content is mailed separately to a specified recipient
+address.
 
 The idea is to allow you to view the output of automated commands while having
-the content encrypted as it passes through to your mailserver, and (optionally)
-have some assurance that the content was actually generated by the server
-concerned. C<cron(8)> scripts are the ideal use case, but this would also work
-with C<at(1)> or anything else that might non-interactively run jobs for which
+the content encrypted as it passes through to your mailserver, and optionally
+to have some assurance that the content was actually generated by the server
+concerned. B<cron(8)> scripts are the ideal use case, but this would also work
+with B<at(1)>, or anything else that might non-interactively run jobs for which
 output is significant.
 
-You probably want to call this with the C<runcrypt(1)> program installed by
-this distribution, which provides a means to set the properties for the module
-via environment variables or command-line options.
+You will probably want to call this with the L<B<runcrypt(1)>|runcrypt> program
+provided by this distribution, which includes a means to set the properties for
+the module via environment variables or command line options.
 
 =head1 SYNOPSIS
 
@@ -166,7 +167,7 @@ via environment variables or command-line options.
     ...
     my $mrc = Mail::Run::Crypt->new(
         sign       => 1,
-        keyid      => 0x1234DEAD,
+        keyid      => '0x1234DEAD5678BEEF',
         passphrase => 'able was i ere i saw elba',
         mailto     => 'you@example.net',
     );
@@ -174,46 +175,56 @@ via environment variables or command-line options.
     
 =head1 SUBROUTINES/METHODS
 
-=head2 B<new(%opts)>
+=head2 C<new(%opts)>
 
-Constructor accepts the following named parameters:
+Constructor method; accepts the following named parameters:
 
 =over 4
 
+=item C<mailto>
+
+The recipient email address for the content. This is always required.
+
 =item C<sign>
 
-Whether to sign the command output. This defaults to off. A key ID and
-passphrase will be required for signing.
+Whether to sign the command output. This defaults to 0. A C<keyid> and
+C<passphrase> will be required for signing.
 
 =item C<encrypt>
 
-Whether to encrypt the command output. This defaults to on.
+Whether to encrypt the command output. This defaults to 1.
 
 =item C<keyid>
 
-The GnuPG key ID that should be used to encrypt the messages.
-
-=item C<passphrase>
+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. 
 
-The passphrase used to decrypt the key.
+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
+a compromised key.
 
-=item C<mailto>
+=item C<passphrase>
 
-The recipient email address for the content.
+The passphrase used to decrypt the key. This is required for signing.
 
 =item C<name>
 
-(Optional) The name of the object. When called from the C<runcrypt(1)>
-program, this will be the string "runcrypt".
+(Optional) The name of the object. When called from the
+L<B<runcrypt(1)>|runcrypt> program, this will be the string "runcrypt".
+Otherwise, it will default to this package's name.
 
 =back
 
-=head2 B<run(@command)>
+=head2 C<run(@command)>
 
-Run the specified arguments as a command with C<IPC::Run3::run3()>, and email
-any output or error content to the email recipient.
+Run the specified arguments as a command with L<IPC::Run3|IPC::Run3>, and email
+any output or error content to the email recipient, encrypting and/or signing
+as configured. Returns 1 if the command succeeded, 0 otherwise. Use
+L<C<bail()>|/bail()> to get the actual exit code if needed.
 
-=head2 B<bail()>
+=head2 C<bail()>
 
 Return the exit status of the most recently run command, or 127 if no command
 has been successfully run.
@@ -222,30 +233,38 @@ has been successfully run.
 
 =over 4
 
-=item mailto required
+=item C<mailto required>
 
 The required C<mailto> property was not passed in the constructor.
 
-=item keyid required for signing
+=item C<keyid required for signing>
 
 Signing was specified, but no C<keyid> attribute was passed in the constructor.
 
-=item passphrase required for signing
+=item C<passphrase required for signing>
 
 Signing was specified, but no C<passphrase> attribute was passed in the constructor.
 
-=item command failed: %s
+=item C<command failed: %s>
 
-The command did not merely fail, it could not even be started, with the given
-error string. This is typically due to problems finding the executable.
+The command could not be run at all, raising the given error string. This is
+typically due to problems finding the executable.
 
 =back
 
 =head1 CONFIGURATION AND ENVIRONMENT
 
 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
 
@@ -257,34 +276,34 @@ Perl v5.10.0 or newer
 
 =item *
 
-C<Carp>
+L<Carp|Carp>
 
 =item *
 
-C<Const::Fast>
+L<Const::Fast|Const::Fast>
 
 =item *
 
-C<English>
+L<English|English>
 
 =item *
 
-C<IPC::Run3>
+L<IPC::Run3|IPC::Run3>
 
 =item *
 
-C<Mail::GnuPG>
+L<Mail::GnuPG|Mail::GnuPG>
 
 =item *
 
-C<MIME::Entity>
+L<MIME::Entity|MIME::Entity>
 
 =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 GnuPG-specific code, so
+it won't work with other OpenPGP implementations.
 
 =head1 BUGS AND LIMITATIONS