diff --git a/Community_News/README.md b/Community_News/README.md index 0924fa4..db4f8e1 100644 --- a/Community_News/README.md +++ b/Community_News/README.md @@ -1,674 +1,685 @@ -./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