Updates and a bug fix for make_shownotes

Community_News/.make_shownotes.cfg: more comments

Community_News/make_email: added colour test for pod2usage

Community_News/make_shownotes: fixed a bug when using
    -lastrecording=DATETIME. Added reporting of expanded output file
    names; tidying and updates to POD documentation.

Community_News/recording_dates.dat: added test entry for May 2025

Community_News/make_email

@@ -47,7 +47,8 @@ use open ':std', ':encoding(UTF-8)'; # Make all IO UTF-8
 use Cwd qw( abs_path );
 
 use Getopt::Long;
-use Pod::Usage;
+BEGIN { $ENV{PERLDOC} = '-MPod::Text::Color'; }
+use Pod::Usage qw(pod2usage);           # Use colour-capable Pod::Text
 
 use Config::General;
 
@@ -98,7 +99,7 @@ chdir($basedir);
 # DateTime::TimeZone->all_names(). Just uncomment the desired elements.
 #
 my @zones = (
-    #{{{
+    #{{{ --- time zones ---
     #'Africa/Abidjan',
     #'Africa/Accra',
     #'Africa/Addis_Ababa',
@@ -1646,6 +1647,8 @@ The number of the show found in the database.
 
 =head1 DESCRIPTION
 
+=head2 B<Overview>
+
 The script makes an invitation email for the next Community News recording
 with times per timezone. The message is structured by a Template Toolkit
 template, so its contents can be adjusted without changing this script.
@@ -1666,6 +1669,44 @@ to use it with an email client to construct the message to be sent to the HPR
 mailing list, usually on the Monday prior to the weekend of the recording. The
 script does not send the message itself.
 
+=head2 B<Required files>
+
+The B<make_email> script requires the presence of two files, which are
+described in this section. These files are expected to be located in the same
+directory used to store the script.
+
+The script also requires a configuration file which is described in the
+B<CONFIGURATION AND ENVIRONMENT> section below:
+
+=over 4
+
+=item B<Date Cache>
+
+This is a file containing the recording dates of previous Community News
+shows. The file is managed by B<make_email>, and it exists to aid the script
+B<make_shownotes> when it is generating the HTML notes for distribution to the
+volunteers who are contributing to the recording.
+
+When B<make_shownotes> is generating notes for the volunteers it tries to work
+out whether any comments were missed for that month, or whether any for the
+current review month were read. It highlights any such cases to assist with
+continuity. The date and time of the last recording are needed to achieve
+this.
+
+The file name is defined in the configuration file, and the default is
+B<recording_dates.dat>.
+
+The format of the file is described in the B<DATE CACHE> part of the
+B<CONFIGURATION AND ENVIRONMENT> section below.
+
+=item B<Template>
+
+This is a file written in the Template Toolkit syntax which defines the format
+of the email text. The name of this file is defined in the configuration file.
+By default it is B<make_email_template.tpl>.
+
+=back
+
 =head1 DIAGNOSTICS
 
 =over 8
@@ -1827,23 +1868,29 @@ is no record for the month being processed, one is appended to the file. If
 the details already exist they are updated unless they are the same as those
 stored.
 
-A backup of the file is made if the data in a record is being updated.
+A backup of the file is made if the data in a record is being updated. This
+file has the same name as the cache file with a B<~> character appended to it.
 
 =head1 EXAMPLES
 
 =over 4
 
-=item 1. Specify a future recording date
+=item B<Specify a future recording date>
 
     make_email -date=2025-08-01
 
 Generates the text of an email for a specific date (expected to be in the
-future). The first Monday of August 2025 is 2025-08-04. The date use in the
+future). The first Monday of August 2025 is 2025-08-04. The date used in the
 example is the Friday before that. The script will compute the month to be
 reviewed (July 2025) from this date and write the email message text
 accordingly, to STDOUT.
 
-=item 2. Specify and force a review month in the recent past
+This would be a way of testing the generation of the email text for a future
+date, as opposed to the next one. It will cause the writing of a record in the
+data cache file, but, since this will be adjusted if there are any changes in
+the future, this should not be a problem.
+
+=item B<Specify and force a review month in the recent past>
 
     make_email -force -month=2025-03-01 -start=16:00 -out=HPR_email_%s.txt
 
@@ -1855,7 +1902,7 @@ Normally, generating email for March would not be allowed since it's in the
 past, so B<-force> is needed to override the checks. The start day is the
 default Friday, and the start time is set to 16:00. The message (email body)
 is written to B<HPR_email_2025-03.txt>. The date cache
-(B<recording_dates.dat)> will be updated with the line:
+(B<recording_dates.dat>) will be updated with the line:
 
     2025-03-01,2025-04-04 16:00:00