HPR/hpr-tools
5
0
Fork 1
Code Issues 12 Pull Requests Packages Projects Releases Wiki Activity

Updates and a bug fix for make_shownotes

Browse Source 
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
This commit is contained in:
Dave Morriss 2025-04-16 17:14:26 +01:00
parent 01d4639ba7
commit 960c5acc83
4 changed files with 119 additions and 51 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

8
Community_News/.make_shownotes.cfg
View File

@ -1,10 +1,12 @@
#
# .make_shownotes.cfg (2025-03-27)
# .make_shownotes.cfg (2025-04-13)
# Configuration file for make_shownotes version >= 4
#
<settings>
# Format strings (using 'printf' formatting) for building certain required strings
title_template = HPR Community News for %s %s
summary_template = HPR Volunteers talk about shows released and comments posted in %s %s
# Repeat the following line with each of the desired tags to make an
# array-like structure
tags = Community News
@ -27,8 +29,8 @@
# cache of previous recording dates and times
cache = recording_dates.dat
# Templates
# ---------
# Template Toolkit templates
# --------------------------
# Main note template (actually a soft link)
main_template = shownote_template.tpl

61
Community_News/make_email
View File

@ -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

80
Community_News/make_shownotes
View File

@ -32,7 +32,7 @@
# VERSION: 0.4.4
# ORIGINAL: 2014-04-24 16:08:30
# CREATED: 2025-03-13 15:07:35
# REVISION: 2025-04-01 21:29:10
# REVISION: 2025-04-15 23:36:56
#
#===============================================================================
@ -305,6 +305,9 @@ if (defined($lastrecording)) {
emit( $silent, "Last recording from option: ", $lastrecording, "\n" );
_debug( $DEBUG > 1, '$lastrecording = ' . $lastrecording );
# Compute the last month, with a date
@dc_lm = find_last_month(\@review_month);
@dc_lr = parse_to_dc( $lastrecording, \@deftime );
_debug( $DEBUG > 1, '@dc_lr = ' . Dumper( \@dc_lr ) );
}
@ -417,7 +420,8 @@ else {
"Error: episode $episode already exists in the database\n");
if ($h1->{title} eq $title) {
say "(Episode $episode is an old-style place-holder. Continuing)";
emit( $silent,
"(Episode $episode is an old-style place-holder. Continuing)\n");
}
else {
die "Trying to overwrite an existing show. Aborting\n";
@ -451,7 +455,7 @@ for my $file (
)
)
{
emit( $silent, sprintf( "* %-100s *\n", "» $file" ) );
emit( $silent, sprintf( "* %-100s *\n", "> $file" ) );
}
emit($silent,"\n");
@ -487,6 +491,8 @@ emit(
)
) if $t_time;
emit($silent,"\n");
#
# Report what we have in the 'lastrecording' and 'lastmonth' variables
#
@ -913,10 +919,17 @@ if ($html_outfile || $json_outfile) {
# Settings for creating the HTML fragment
#
if ($html_outfile) {
$outfh = make_filename_and_open($html_outfile,
#
# We get the file handle and the expanded filename
#
($outfh,$html_outfile) = make_filename_and_open($html_outfile,
sprintf( "%d-%02d", $dt_som->year, $dt_som->month ));
}
#
# We generate the HTML fragment whether we're to write it or not, since
# it's needed for making JSON
#
my $vars = {
review_month => $dt_som->month_name,
review_year => $dt_som->year,
@ -951,13 +964,18 @@ if ($html_outfile || $json_outfile) {
if ($html_outfile) {
print $outfh $document;
close($outfh);
#
# Report the output file
#
emit($silent,"HTML is in $html_outfile\n");
}
#-------------------------------------------------------------------------------
# Create the JSON if requested
#-------------------------------------------------------------------------------
if ($json_outfile) {
$outfh = make_filename_and_open($json_outfile,
($outfh, $json_outfile) = make_filename_and_open($json_outfile,
sprintf( "%d-%02d", $dt_som->year, $dt_som->month ));
#
@ -1005,6 +1023,11 @@ if ($html_outfile || $json_outfile) {
my $json = JSON->new->utf8;
say $outfh $json->encode(\%json_data);
#
# Report the output file
#
emit($silent,"JSON is in $json_outfile\n");
$sth1->finish;
}
@ -1015,10 +1038,12 @@ if ($html_outfile || $json_outfile) {
# standalone.
#-------------------------------------------------------------------------------
if ($full_html_outfile) {
my $outfh;
#
# Settings for creating the standalone HTML
#
my $outfh = make_filename_and_open($full_html_outfile,
($outfh,$full_html_outfile) = make_filename_and_open($full_html_outfile,
sprintf( "%d-%02d", $dt_som->year, $dt_som->month ));
my $vars = {
@ -1061,6 +1086,11 @@ if ($full_html_outfile) {
|| die $tt->error(), "\n";
print $outfh $full_document;
#
# Report the output file
#
emit($silent,"Full HTML is in $full_html_outfile\n");
}
$dbh->disconnect;
@ -1600,7 +1630,7 @@ sub ISO8601_Date {
# the file for output
# PARAMETERS: $filename Name of file with or without '%s'
# $subs String to substitute for '%s'
# RETURNS: File handle
# RETURNS: A list containing the file handle and the expanded filename
# DESCRIPTION:
# THROWS: No exceptions
# COMMENTS: None
@ -1618,7 +1648,7 @@ sub make_filename_and_open {
open( $outfh, ">:encoding(UTF-8)", $filename )
or croak "Unable to open $filename for writing: $!";
return $outfh;
return ($outfh,$filename);
}
#=== FUNCTION ================================================================
@ -1959,8 +1989,6 @@ Reports the following (as well as the data for level 1):
=over 4
=item .
Details of the last recording data (and time)
=back
@ -1971,8 +1999,6 @@ Reports the following (as well as the data for level 2):
=over 4
=item .
The generation of comment indexes needed in the comment lists. These are
computed after the query has been run.
@ -1987,26 +2013,16 @@ Reports the following (as well as the data for level 3):
=over 4
=item .
A dump of the '%past' hash which contains details of comments on past shows.
=item .
A dump of the '%current' hash which contains details of comments on this
month's shows.
=item .
A dump of the '@missed_comments' array containing comments that arrived after
the last recording.
=item .
A list of the duplicated episode numbers in '@missed_episodes'
=item .
Another dump of '%past' after it has been cleaned up. Also the count of
comments to past shows and the comment count.
@ -2076,22 +2092,22 @@ Four types of information are collected by the script:
=over 4
=item -
=item B<Host details>
Details of new hosts who have released new shows in the selected month
=item -
=item B<Show details>
Details of shows which have been released in the selected month
=item -
=item B<Comments>
Comments which have been submitted to the HPR website in the selected month.
These need to be related to shows in the current period or in the past.
Comments made about shows which have not yet been released (but are visible on
the website) are not included even though they are made in the current month.
=item -
=item B<Mailing list threads>
A link to the current threads on the mailing list in the past month can be included. This
is done by default but can be skipped if the B<-nomailnotes> option is used.
@ -2137,7 +2153,7 @@ If you wish to write your own template refer to the following lists for the
names of items. Also refer to the default template B<shownote_template.tpl>
for the techniques used there. (Note that B<shownote_template.tpl> is a soft
link to the current default template, such as B<shownote_template12.tpl>, the
link name is currently used in the configuration file).
soft link name is currently used in the configuration file).
The hash and field names available to the template are as follows
@ -2359,12 +2375,14 @@ The configuration file contains the following settings, which are explained
at the end.
#
# .make_shownotes.cfg (2025-03-27)
# .make_shownotes.cfg (2025-04-13)
# Configuration file for make_shownotes version >= 4
#
<settings>
# Format strings (using 'printf' formatting) for building certain required strings
title_template = HPR Community News for %s %s
summary_template = HPR Volunteers talk about shows released and comments posted in %s %s
# Repeat the following line with each of the desired tags to make an
# array-like structure
tags = Community News
@ -2387,8 +2405,8 @@ at the end.
# cache of previous recording dates and times
cache = recording_dates.dat
# Templates
# ---------
# Template Toolkit templates
# --------------------------
# Main note template (actually a soft link)
main_template = shownote_template.tpl
@ -2404,7 +2422,7 @@ at the end.
name = hpr.db
</database>
=head2 Details
=head2 Configuration file details
If any mandatory elements are omitted from the configuration file they are
given default values in the script.

1
Community_News/recording_dates.dat
View File

@ -31,3 +31,4 @@
2025-01-01,2025-01-31 15:00:00
2025-02-01,2025-02-28 16:00:00
2025-03-01,2025-04-04 16:00:00
2025-04-01,2025-05-02 16:00:00