./make_shownotes -doc make_shownotes version 0.4.5 NAME make_shownotes - Make show notes for the Hacker Public Radio Community News show VERSION This documentation refers to make_shownotes version 0.4.5 USAGE make_shownotes [-help] [-documentation|-man] [-config=FILE] [-from=DATE] [-[no]comments] [-[no]silent] [-[no]mailnotes] [-lastrecording=DATETIME] [-full-html=FILE] [-html=FILE] [-json=FILE] [-debug=N] OPTIONS -help Displays a brief help message describing the usage of the program, and then exits. -documentation or -man 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 -config=FILE The script uses a configuration file to hold the various parameters it needs to run. This option allows an alternative configuration file to be used. This file defines many settings including the location of the database. See the CONFIGURATION AND ENVIRONMENT section below for the file format. If the option is omitted the default file is used: .make_shownotes.cfg, which is expected to be in the same directory as the script itself. -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 must be present but is ignored and only the month and year parts are used (to internally denote the first day of the month). If this option is omitted the current month is used. Of course, this may cause problems if the notes are to generated for an earlier (or later) month, which is why this option exists. -[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). Output file options: -html=FILE, -full-html=FILE, -json=FILE There are three output file types that can be generated by the script. At least one must be present: HTML fragment (-html=FILE) This file will contain the HTML to be added to the HPR database. The page for the show, when it is released, will be a full web page, with standard header and footer, and the contents will come from this HTML fragment in the database. Action will be needed in addition to the script to add this file to the database, but how this is done is outside the scope of this documentation. Standalone HTML (-full-html=FILE) The file created in this case will contain a full, stand-alone HTML page. It is intended to be circulated to the co-hosts recording the episode to make it easier to access various information sources during the recording. In the file the comments relating to past shows will show the full text, and there will be indications of comments that were read in the last recording, and any that were missed. In order to highlight comments read, and those missed in the previous recording the script needs to know the date and time of the recording. This information should be in a date cache file referenced in the configuration file (usually recording_dates.dat). This file is updated when the monthly mail message is generated (see make_email). If, for any reason, this has not happened, the information can be provided with the -lastrecording=DATETIME option (alternatively written as -lr=DATETIME). See below for more information. JSON details (-json=FILE) This file will contain JSON data which is intended to be used to upload the episode to the database. How this is done is outside the scope of this document. The format used is very close to that used in the workflow which is used to upload episodes submitted through the upload forms. In all cases 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: -html=shownotes_%s.html This will cause the generation of the file: shownotes_2014-07.html -lastrecording=DATETIME or -lr=DATETIME As mentioned for -full-html=FILE, and later in the MARKING COMMENTS section, the script needs the date of the last recording when marking comments. This can be extracted from the file referenced in the configuration data using the setting cache. By default the name of this file is recording_dates.dat, and its contents are managed when the script make_email is run and by this script. If for any reason the date and time of the last recording is missing, these values can be defined with this option, and these values will be written to the cache file (or modified, if necessary). The format can be an ISO 8601 date followed by a 24-hour time, such as '2020-01-25 15:00:00'. If the time is omitted it defaults to the value of starttime in the configuration file. The script will update the cache file with the date and time used in this option if the relevant entry is missing. Also, if an entry is present but the values are different from those provided with the option, the relevant entry will be updated. Note that the DATETIME value must contain the date of the last recording. This will be checked, and written to the cache file prefixed by a "key" consisting of the first day of the month BEFORE the month being reviewed. For example, when generating the notes for August 2025 the following command will be needed if there is no last recording date (for July 2025) in the cache: ./make_shownotes -from=2025-08-01 -full-html=full_shownotes_%s.html \ -mail -comments -lr="2025-08-01 15:00:00" Here we need the last recording date for the show reviewing HPR shows in July 2025. The date and time for this recording was in early August (Friday before the first Monday of September 2025-09-01), as shown. This combination will result in the addition of the following line to the cache file: 2025-07-01,2025-08-01 15:00:00 As mentioned, the addition of such date and time information to the cache will normally be performed by make_email, which performs the date computations itself, unlike this script. This feature in this script is an alternative for special cases. -[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 requested output files and details of the process of generating these files. -[no]mailnotes If desired, the show notes may include a section linking to recent discussions on the HPR Mailman mailing list. The current template (defined in the configuration file by the variable main_template, shownote_template12.tpl) simply contains a section like the following: [%- IF mailnotes == 1 -%]

Mailing List discussions

Policy decisions surrounding HPR are taken by the community as a whole. This discussion takes place on the Mailing List which is open to all HPR listeners and contributors. The discussions are open and available on the HPR server under Mailman.

The threaded discussions this month can be found here:

[% mailthreads %] [%- END %] The TT2 variables such as mailinglist and mailthreads are defined earlier in the template. -debug=N Enables debugging mode when N > 0 (zero is the default, no debugging output). The levels are: Values are: 1 TBA 2 Reports the following (as well as the data for level 1): Details of the last recording data (and time) 3 Reports the following (as well as the data for level 2): The generation of comment indexes needed in the comment lists. These are computed after the query has been run. 4 See the DESCRIPTION section for an explanation of the data structures mentioned here. Reports the following (as well as the data for level 3): A dump of the '%past' hash which contains details of comments on past shows. A dump of the '%current' hash which contains details of comments on this month's shows. A dump of the '@missed_comments' array containing comments that arrived after the last recording. A list of the duplicated episode numbers in '@missed_episodes' Another dump of '%past' after it has been cleaned up. Also the count of comments to past shows and the comment count. MARKING COMMENTS Explaining the marking of comments in the full HTML file: This is only relevant when generating the full stand-alone HTML ("handout") for circulation to the volunteers recording the Community News episode. In this output the comments sent in to past shows (those before the review month) include their full texts in order to make reading them easier. Normally comments (to shows in the reviewed month) are read as the shows themselves are reviewed, so the full texts are not needed in this handout. In addition to this, there is a possibility that certain comments relating to past shows 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. As well as this, some comments may have been missed in the last month because the recording was made before the end of the review month. 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 the next 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 generating full notes 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 script extracts the date of the last recording from the cache file (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 that don't want to be re-read or were missed last month. It is up to the template to do what is necessary to highlight them. 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 (defined in the configuration file) 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: Host details Details of new hosts who have released new shows in the selected month Show details Details of shows which have been released in the selected month 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. 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 -nomailnotes option is used. 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. Comments These are formatted with
tags separated by horizontal lines. A
shows the author name and title and a