From 295e96cad23e75e2c07f079d3feceeea16e20c0b Mon Sep 17 00:00:00 2001 From: Ken Fallon Date: Mon, 18 Aug 2025 13:11:07 +0200 Subject: [PATCH] Piped help to readme --- Community_News/README.md | 674 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 674 insertions(+) create mode 100644 Community_News/README.md diff --git a/Community_News/README.md b/Community_News/README.md new file mode 100644 index 0000000..0924fa4 --- /dev/null +++ b/Community_News/README.md @@ -0,0 +1,674 @@ +./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