NAME

make_shownotes - Make HTML show notes for the Hacker Public Radio Community News show

VERSION

This documentation refers to make_shownotes version 0.1.3

USAGE

make_shownotes [-help] [-doc] [-from=DATE] [-[no]comments]
    [-[no]markcomments] [-[no]ctext] [-lastrecording=DATETIME]
    [-[no]silent] [-out=FILE] [-episode=[N|auto]] [-[no]overwrite]
    [-mailnotes[=FILE]] [-anyotherbusiness=FILE] [-template=FILE]
    [-config=FILE] [-interlock=PASSWORD]

OPTIONS

-help

Displays a brief help message describing the usage of the program, and then exits.
-doc

Displays the entirety of the documentation (using a pager), and then exits. To generate a PDF version use:
```
  pod2pdf make_shownotes --out=make_shownotes.pdf
```
-from=DATE

This option is used to indicate the month for which the shownotes are to be generated. The script is able to parse a variety of date formats, but it is recommended that ISO8601 YYYY-MM-DD format be used (for example 2014-06-30).

The day part of the date is ignored and only the month and year parts are used.

If this option is omitted the current month is used.
-[no]comments

This option controls whether the comments pertaining to the selected month are included in the output. If the option is omitted then no comments are included (-nocomments).
-[no]markcomments or -[no]mc

This option controls whether certain comments are marked in the HTML. The default is -nomarkcomments. The option can be abbreviated to -mc and -nomc.

The scenario is that we want to use the notes the script is generating while making a Community News recording and we also want them to be the show notes in the database once the show has been released.

Certain comments relating to shows earlier than this month were already discussed last month because they were made before that show was recorded. We don't want to read them again during this show, so a means of marking them is needed.

The script determines the date of the last recording (or it can be specified with the -lastrecording=DATETIME option, or its abbreviation -lr=DATETIME) and passes it to the template. The template can then compare this date with the dates of the relevant comments and take action to highlight those we don't want to re-read. It is up to the template to do what is necessary to highlight them.

The idea is that we will turn off the marking before the notes are released - they are just for use by the people recording the episode.

Another action is taken during the processing of comments when this option is on. On some months of the year the recording is made during the month itself because the first Monday of the next month is in the first few days of that month. For example, in March 2019 the date of recording is the 30th, and the show is released on April 1st. Between the recording and the release of the show there is time during which more comments could be submitted.

Such comments should be in the notes for March (and these can be regenerated to make sure this is so) but they will not have been read on the March recording. The make_shownotes script detects this problem and, if -markcomments is set (and comments enabled) will show a list of any eligible comments in a red highlighted box. This is so that the volunteers recording the show can ensure they read comments that have slipped through this loophole. The display shows the entire comment including the contents, but disappears when the notes are refreshed with -nomarkcomments (the default).

In this mode the preamble warning about comments to be ignored used to be included, but now it is skipped if there are no such comments. This means one switch can serve two purposes.
-lastrecording=DATETIME or -lr=DATETIME

As mentioned for -markcomments, the date of the last recording can be computed in the assumption that it's on the Saturday before the first Monday of the month at 18:00. However, on rare occasions it may be necessary to record on an earlier date and time, which cannot be computed. This value can be defined with this option.

The format can be an ISO 8601 date followed by a 24-hour time, such as '2020-01-25 18:00'. If the time is omitted it defaults to 18:00.
-[no]ctext

This option controls whether the comment text itself is listed with comments. This is controlled by the template, but the current default template only shows the text in the Past shows section of the output. The default state is -noctext in which the comment texts are not written.
-[no]silent

This option controls whether the script reports details of its progress to STDERR. If the option is omitted the report is generated (-nosilent).

The script reports: the month it is working on, the name of the output file (if appropriate) and details of the process of writing notes to the database (if the -episode=[N|auto] option is selected).
-mailnotes[=FILE]

If desired, the show notes may include a section about recent discussions on the HPR mailing list. Obviously, this text will change every month, so this option provides a way in which an external file can be included in the show notes.

The filename may be omitted which is a way in which a BLOCK directive can be placed in the template and used rather than the file. The BLOCK must be named default_mail because this is the name the script uses in this circumstance. See shownote_template8.tpl for an example of its use.

The template must contain instructions to include the file or block. The file name is stored in a variable 'includefile' in the template. Directives of the following form may be added to achive this:
```
  [%- IF includefile.defined %]
  Constant header, preamble, etc
  [%- INCLUDE $includefile %]
  Other constant text or tags
  [%- END %]
```
The first directive causes the whole block to be ignored if there is no -mailnotes option. The use of the INCLUDE directive means that the included file may contain Template directives itself if desired.

See existing templates for examples of how this is done.
-anyotherbusiness=FILE or -aob=FILE

If desired the shownotes may contain an 'Any other business' section. This is implemented in a template thus:
```
  [% IF aob == 1 -%]
  <h2>Any other business</h2>
  [% INCLUDE $aobfile -%]
  [%- END %]
```
The template variable aob is set to 1 if a (valid) file has been provided, and the name of the file is in aobfile.

The included file is assumed to be HTML.
-out=FILE

This option defines an output file to receive the show notes. If the option is omitted the notes are written to STDOUT, allowing them to be redirected if required.

The output file name may contain the characters '%s'. This denotes the point at which the year and month in the format YYYY-MM are inserted. For example if the script is being run for July 2014 the option:
```
  -out=shownotes_%s.html
```
will cause the generation of the file:
```
  shownotes_2014-07.html
```
-episode=[N|auto]

This option provides a means of specifying an episode number in the database to receive the show notes.

It either takes a number, or it takes the string 'auto' which makes the script find the correct show number.

First the episode number has to have been reserved in the database. This is done by running the script 'reserve_cnews'. This makes a reservation with the title "HPR Community News for <monthname> <year>". Normally Community News slots are reserved several months in advance.

Close to the date of the Community News show recording this script can be run to write show notes to the database. For example:
```
  ./make_shownotes -from=1-Dec-2014 -out=/dev/null \
      -comm -tem=shownote_template5.tpl -ep=auto
```
This will search for the episode with the title "HPR Community News for December 2014" and will add notes if the field is empty. Note that it is necessary to direct the output to /dev/null since the script needs to write a copy of the notes to STDOUT or to a file. In this case we request comments to be added to the notes, and we use the template file shownote_template5.tpl which generates an HTML snippet suitable for the database.

The writing of the notes to the database will fail if the field is not empty. See the -overwrite option for how to force the notes to be written.

If the -episode=[N|auto] option is omitted no attempt is made to write to the database.
-[no]overwrite

This option is only relevant in conjunction with the -episode=[N|auto] option. If -overwrite is chosen the new show notes will overwrite any notes already in the database. If -nooverwrite is selected, or the option is omitted, no over writing will take place - it will only be possible to write notes to the database if the field is empty.
-template=FILE

This option defines the template used to generate the notes. The template is written using the Template toolkit language.

If the option is omitted then the script uses the file shownote_template.tpl in the same directory as the script. If this file does not exist then the script will exit with an error message.

For convenience shownote_template.tpl is a soft link which points to the file which is the current default. This allows the development of versions without changing the usual way this script is run.
-config=FILE

This option allows an alternative configuration file to be used. This file defines the location of the database, its port, its name and the username and password to be used to access it. This feature was added to allow the script to access alternative databases or the live database over an SSH tunnel.

See the CONFIGURATION AND ENVIRONMENT section below for the file format.

If the option is omitted the default file is used: .hpr_db.cfg
-interlock=PASSWORD

This option was added to handle the case where the notes for a Community News episode have been posted after the show was recorded, but, since the recording date was not the last day of the month further comments could be added after upload. Logically these comments belong in the previous month's shownotes, so we'd need to add them retrospecively.

Up until the addition of this option the script would not allow the regeneration of the notes. This option requires a password to enable the feature, but the password is in a constant inside the script. This means that it's difficult to run in this mode by accident, but not particulary difficult if it's really needed.

Take care not to run in this mode if the notes have been edited after they were generated!

DESCRIPTION

Overview

This script generates notes for the next Hacker Public Radio Community News show. It does this by collecting various details of activity from the HPR database and passing them to a template. The default template is called shownote_template.tpl and this generates HTML, but any suitable textual format could be generated if required, by using a different template.

Data Gathering

Four types of information are collected by the script:

Details of new hosts who have released new shows in the selected month

Details of shows which have been released in the selected month

Details of topics on the mailing list in the past month can be included. This
is only done if the **-mailnotes=FILE** option is used. This option must
reference a file of HTML, which may contain Template directives if required.

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.

Comments are only gathered if the **-comments** option is selected.

Report Generation

The four components listed above are formatted in the following way by the default template.

New Hosts

These are formatted as a list of links to the hostid with the host's name.
Shows

These are formatted into an HTML table containing the show number, title and host name. The show title is a link to the show page on the HPR website. The host name is a link to the host page on the website.
Mailing list discussions

If there have been significant topics on the mailing list in the month in question then these can be summarised in this section. This is done by preparing an external HTML file and referring to it with the -mailnotes=FILE option. If this is done then the file is included into the template.

See the explanation of the -mailnotes option for more details.
Comments

These are formatted with <article> tags separated by horizontal lines. A <header> shows the author name and title and a <footer> displays a link to the show and the show's host and the show title is also included. The body of the article contains the comment text with line breaks.

Variable, Field and Hash names

If you wish to write your own template refer to the following lists for the names of items. Also refer to the default template shownote_template.tpl for the techniques used there. (Note that shownote_template.tpl is a link to the current default template, such as shownote_template8.tpl).

The hash and field names available to the template are as follows

Global variables

  Variable Name          Details
  -------------          -------
  review_month           The month name of the report date
  review_year            The year of the report date
  comment_count          The number of comments in total
  past_count             The number of comments on old shows
  skip_comments          Set when -comments is omitted
  mark_comments          Set when -markcomments is used
  ctext                  Set when the comment bodies in the 'Past shows'
                         section are to be shown
  last_recording         The date the last recording was made
                          (computed if -markcomments is selected) in
                          Unixtime format
  last_month             The month prior to the month for which the notes are
                         being generated (computed if -markcomments is
                         selected) in 'YYYY-MM' format

New Hosts

The name of the hash in the template is hosts. The hash might be empty if there are no new hosts in the month. See the default template for how to handle this.
```
  Field Name     Details
  ----------     -------
  host           Name of host
  hostid         Host id number
```

Show Details

The name of the hash in the template is shows. Note that there are more fields available than are used in the default template. Note also that certain field names are aliases to avoid clashes (e.g. eps_hostid and ho_hostid).

  Field Name     Details
  ----------     -------
  eps_id         Episode number
  date           Episode date
  title          Episode title
  length         Episode duration
  summary        Episode summary
  notes          Episode show notes
  eps_hostid     The numerical host id from the 'eps' table
  series         The series number from the 'eps' table
  explicit       The explicit marker for the show
  eps_license    The license for the show
  tags           The show's tags as a comma-delimited string
  version        ?Obsolete?
  eps_valid      The valid value from the 'eps' table
  ho_hostid      The host id number form the 'hosts' table
  ho_host        The host name
  email          The hosts's email address (true address - caution)
  profile        The host's profile
  ho_license     The default license for the host
  ho_valid       The valid value from the 'hosts' table

Mailing List Notes

The variable includefile contains the path to the file (which may only be located in the same directory as the script).

Comment Details

Two hashes are created for comments. The hash named past contains comments to shows before the current month, and current contains comments to this month's shows. Note that these hashes are only populated if the -comments option is provided. Both hashes have the same structure.

  Field Name             Details
  ----------             -------
  episode                Episode number
  identifier_url         Full show URL
  title                  Episode title
  date                   Episode date
  host                   Host name
  hostid                 Host id number
  timestamp              Comment timestamp in ISO8601 format
  comment_author_name    Name of the commenter
  comment_title          Title of comment
  comment_text           Text of the comment
  comment_timestamp_ut   Comment timestamp in Unixtime format
  in_range               Boolean (0/1) denoting whether the comment was made
                         in the target month
  index                  The numerical index of the comment for a given show

The purpose of the in_range value is to denote whether a comment was made in the target month. This is used in the script to split the comments into the past and current hashes. It is therefore of little use in the template, but is retained in case it might be useful. The index value can be used in the template to refer to the comment, make linking URLs etc. It is generated by the script (unfortunately it couldn't be done in the SQL).

Filters

A filter called decode_entities is available to the template. The reason for creating this was when the HTML of a comment is being listed as text (Unicode actually). Since comment text is stored in the database as HTML with entities when appropriate this is needed to prevent the plain text showing & and the like verbatim. It is currently used in comments_only.tpl.

DIAGNOSTICS

Unable to find configuration file ...

The nominated configuration file in -config=FILE (or the default file) cannot be found.
Episode number must be greater than zero

The -episode=N option must use a positive number.
Episode must be a number or 'auto'

The -episode= option must be followed by a number or the word 'auto'
Error: Unable to find includefile ...

The include file referred to in the error message is missing.
Error: Unable to find template ...

The template file referred to in the error message is missing.
Invalid -from=DATE option '...'

The date provided through the -from=DATE option is invalid. Use an ISO8601 date in the format YYYY-MM-DD.
Unable to open ... for writing: ...

The file specified in the -out=FILE option cannot be written to. This may be because you do not have permission to write to the file or directory. Further information about why this failed should be included in the message.
Unable to initialise for writing: ...

The script was unable to open STDOUT for writing the report. Further information about why this failed should be included in the message.
Error: wrong show selected

The -episode=N option has been selected and the script is checking the numbered show but has not found a Community News title.
Error: show ... has a date in the past

The -episode= option has been selected and a Community News show entry has been found in the database. However, this entry is for today's show or is in the past, which is not permitted. It is possible to override this restriction by using the -interlock=PASSWORD option. See the relevant documentation for details.
Error: show ... already has notes

The -episode= option has been selected and a Community News show entry has been found in the database. However, this entry already has notes associated with it and the -overwrite option has not been specified.
Error: episode ... does not exist in the database

The -episode=N option has been selected but the script cannot find this episode number in the database.
Error: Unable to find an episode for this month's notes

The -episode=auto option has been selected but the script cannot find the episode for the month being processed.

Possible reasons for this are that the show has not been reserved in the database or that the title is not as expected. Use reserve_cnews to reserve the slot. The title should be "HPR Community News for <monthname> <year>".

CONFIGURATION AND ENVIRONMENT

The script obtains the credentials it requires to open the HPR database from a configuration file. The name of the file it expects is .hpr_db.cfg in the directory holding the script. To change this will require changing the script.

The configuration file format is as follows:

<database>
    host = 127.0.0.1
    port = PORT
    name = DATABASE
    user = USERNAME
    password = PASSWORD
</database>

DEPENDENCIES

Carp
Config::General
Date::Calc
Date::Parse
DateTime
DateTime::Duration
DBI
Getopt::Long
Pod::Usage
Template
Template::Filters

BUGS AND LIMITATIONS

There are no known bugs in this module. Please report problems to Dave Morriss (Dave.Morriss@gmail.com) Patches are welcome.

AUTHOR

Dave Morriss (Dave.Morriss@gmail.com)

LICENCE AND COPYRIGHT

This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. See perldoc perlartistic.

This program is distributed in the hope that it will be useful but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

Back to Community_News page