Update 'README.md'

Add Ken Fallon

GETTING_STARTED.md

@@ -0,0 +1,202 @@
+# Clone the repository
+
+If git is not installed on the operating system, please install it now 
+(see the git documentation for [instructions on installing git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git)).
+
+To retrieve the code from the repository on anhonesthost.net (a username and 
+password are required), run:
+
+`git clone https://repo.anhonesthost.net/rho_n/hpr_generator.git`
+
+To retrieve the code from the repository on gitlab.com, run: 
+
+`git clone https://gitlab.com/roan.horning/hpr_generator.git`
+
+On success, an "hpr_generator" directory will be created in the folder from 
+which the clone command was executed containing a local copy of the git repository.
+
+# Install required Perl modules
+
+Installing the Perl modules is the most finicky part of the installation process. 
+The needed Perl modules can be found using the operating system's package 
+manager or using the modules found in the 
+[Comprehensive Perl Archive Network (CPAN)](https://www.cpan.org/).
+
+## Installing modules on Debian based Linux distributions
+
+Run command (tested on Debian 11):
+
+```
+apt install libconfig-std-perl \
+	libtemplate-perl \
+	libtemplate-plugin-dbi-perl \
+	libdbd-sqlite3-perl libdate-calc-perl \
+	libtie-dbi-perl
+```
+
+## Using CPAN to install the modules
+
+A cross platform method to install the needed modules is the Perl CPAN application. 
+Make sure both the [make](https://www.gnu.org/software/make/manual/make.html) 
+command and the [cpan](https://perldoc.perl.org/CPAN) command are available. 
+Install them using the operating system's package manager, or from source.
+
+Run commands:
+
+```
+cpan Config::Std
+cpan Template
+cpan Template::Plugin::DBI
+cpan DBD::SQLite
+cpan Date::Calc
+cpan Tie::DBI
+```
+
+# Create the HPR database
+
+The hpr_generator relies on information from a database to generate many of the 
+files for the website (for example: index.html, series/index.html, 
+hpr_mp3.rss, etc). This data is available from a MySQL dump file found on 
+hackerpublicradio.org at URL "https://www.hackerpublicradio.org/hpr.sql".
+
+The first step is to download the hpr.sql file. This can be done using your 
+browser, or by running one of the following commands:
+
+`curl https://www.hackerpublicradio.org/hpr.sql --output ./hpr.sql`
+
+or
+
+`wget --directory-prefix=./ https://www.hackerpublicradio.org/hpr.sql`
+
+## Creating an SQLite database file
+
+The SQL of the hpr.sql file must be converted from MySQL specific statements to 
+SQLite specific statements. The mysql2sqlite script found in the utils directory 
+is used for this conversion. First remove the lines from hpr.sql that 
+mysql2sqlite can't handle:
+
+`sed '/^DELIMITER ;;/,/^DELIMITER ;/d' < ./hpr.sql > ./hpr-sqlite.sql`
+
+Next run the mysql2sqlite script piping its output into the sqlite3 
+program which creates the hpr.db file:
+
+`./utils/mysql2sqlite ./hpr-sqlite.sql | sqlite3 ./hpr.db`
+
+For convenience, the update-sqlite-db.sh script in the utils directory
+automates the above steps (including downloading the hpr.sql file). 
+From the root of the local hpr_generator repository run:
+
+`./utils/update-sqlite-db.sh`
+
+# Configure the site-generator
+
+In your favorite text editor, open the site.cfg file found in the root of the 
+"hpr_generator" folder. Full details about options for configuring the site.cfg 
+file are found in the comments within the file.
+
+## Configuring the database connection
+
+Any database supported by the Perl:DBI and Perl::DBD modules can be used with 
+the site-generator program. Currently the hpr_generator project works with 
+a MySQL or SQLite database.
+
+Find the [DBI] section of the file. It should look like the following
+
+```
+[DBI]
+# Configuration settings for SQLite
+#database: sqlite
+#driver: dbi:SQLite:hpr.db 
+#user:        (not used - leave blank)
+#password:    (not used - leave blank)
+# Configuration settings for MySQL
+#database: mysql
+#driver: dbi:mysql:database=hpr_hpr:hostname=localhost 
+#user: hpr-generator  (Suggested user with read-only privileges)
+#password: *********  (Password for user)
+```
+
+### SQLite
+
+Remove the comment character from the start of the database and driver 
+option lines:
+
+ ```
+# Configuration settings for SQLite
+database: sqlite
+driver: dbi:SQLite:hpr.db 
+#user:        (not used - leave blank)
+#password:    (not used - leave blank)
+```
+
+The hpr.db section of the driver option `dbi:SQLite:hpr.db` is the path 
+to the sqlite file. The default assumes the hpr.db file is located in the same
+directory as the site-generator. 
+
+### MySQL
+
+Remove the comment character from the start of the database, driver, 
+user, and password option lines:
+
+ ```
+# Configuration settings for MySQL
+database: mysql
+driver: dbi:mysql:database=hpr_hpr:hostname=localhost 
+user: hpr-generator
+password: *********
+```
+
+This assumes that the MySQL database service is available at the localhost 
+hostname, that the database name (hpr_hpr) is the database created from 
+the hpr.sql dump file or manually created by you, that the user (hpr-generator) 
+was added by you and has read rights to the hpr_hpr database, and that the 
+password (replace ********* with the actual password) matches the password set 
+for the hpr-generator database user.
+
+## Configuring the website for viewing locally
+
+For HTML links to work when viewing the files on your local machine using the 
+"file://" protocal (i.e. using the "Open..." command in your browser, each HTML 
+file must include a \<base\> meta-data tag in the \<head\> section of its 
+contents. To configure this in the site.cfg file, find the [root_template] 
+section. It should look like the following:
+
+```
+[root_template]
+content: page.tpl.html
+#baseurl: OPTIONAL [i.e. file://<full path to local website directory>]
+```
+Below the #baseurl comment line add:
+
+```
+baseurl: file://</path/to>/hpr_generator/public_html
+```
+
+Replace \<path/to\> with the full path to the hpr_generator directory. For 
+example: `file:///home/rho_n/development/hpr_generator/public_html`
+
+## Configuring the website media file links
+
+If you do not want to host all the media files (currently, audio files and 
+transcription files), you can configure the `media_baseurl` option. This can 
+be added to the [root_template] section of the site.cfg file. Suggested 
+external site is archive.org. To use this site add:
+
+```
+media_baseurl: https://archive.org/download/hpr$eps_id/
+```
+
+# Run the site-generator
+
+Run the site generator form the hpr_generator directory:
+
+```
+./site-generator --all
+```
+
+This will generate all the files for the website. For more examples and to see 
+all available options run:
+
+```
+./site-generator --help
+```

README.md

@@ -35,7 +35,8 @@ Static web page generator for the Hacker Public Radio website.
     * Tie::DBI
     * DBD::SQLite or DBD:mysql
     * Date::Calc
-
+* See the Getting Started tutorial (GETTING_STARTED.md) for more details on 
+  installing the HPR generator.
 ## Usage
 Generate two specific pages:
 `site-generator index about`		
@@ -65,3 +66,5 @@ and add the label "**Feature Request**".
 
 ## Authors and acknowledgment
 * Roan "Rho`n" Horning 
+* gordons
+* Ken Fallon

templates/content-comments_viewer.tpl.html

@@ -1,5 +1,4 @@
 <!--% PROCESS 'shared-episode-summary.tpl.html' %-->
-<!--% PROCESS 'shared-avatar.tpl.html' %-->
 <!--% PROCESS 'shared-utils.tpl.html' %-->
 <!--% PROCESS 'shared-listen-now.tpl.html' %-->
 <!--% PROCESS "queries-episode-${constants.database}.tpl.html" %-->

templates/content-correspondent.tpl.html

@@ -55,8 +55,7 @@
 		<!--% this_host = hosts.$id %-->
 		<h2 class="title">Correspondent</h2>
 		<h2><!--% this_host.host %--></h2>
-		<p><img src="<!--% absolute_path(baseurl) %-->images/<!--% get_avatar(this_host.hostid) %-->" 
+		<p><!--% get_avatar(this_host.hostid, this_host.host) %--><br>
-				height="80" alt="Host Image" /><br>
 		<label>Host ID</label>: <!--% this_host.hostid %--><br><br>
 		<label>email:</label> <u><!--% this_host.email %--></u><br>
 		<label>episodes:</label> <strong><!--% hpr_show_count + twat_show_count %--></strong>

templates/content-correspondents.tpl.html

@@ -1,9 +1,10 @@
 <!--% PROCESS 'shared-utils.tpl.html' %-->
+<!--% PROCESS 'shared-avatar.tpl.html' %-->
 <article>
 	<h2 class="title">Correspondents</h2>
 	<p>For more information on how to become a Correspondent see our <a href="<!--% absolute_path(baseurl) %-->contribute.html">contribute</a></center> page. To add a logo here, either email one to admin at hpr or setup your email on <a href="https://en.gravatar.com/">Gravatar</a>. To protect your browsing privacy we gather the images every hour and serve them directly from HPR.<p />
 <!--% USE DBI(constants.driver, constants.user, constants.password) %-->
-<!--% PROCESS 'shared-avatar.tpl.html' %-->
+<!--% host_cnt = 0 %-->
 	<table class="hosts">
 	<th >Avatar</th>
 	<th >Name &amp; Host ID</th>
@@ -17,14 +18,14 @@
 		on h.hostid = e.hostid '
 	) %-->
 	<tr height="80">
-	<td><img src="<!--% absolute_path(baseurl) %-->images/<!--% get_avatar(host.hostid) %-->" height="80" width="80" alt="avatar" /></td>
+	<td><!--% get_avatar(host.hostid, host.host, host_cnt > 8) %--></td>
 
 		<td><strong><!--% host.host %--></strong><br>
 
 			Host ID: <a href="<!--% absolute_path(baseurl) %-->correspondents/<!--% zero_pad_left(host.hostid) %-->.html"><!--% host.hostid %--></a></td>
 		<td><!--% host.license %--></td>
 		<td><!--% host.date %--></td>
-	</tr>
+	</tr><!--% host_cnt = host_cnt + 1 %-->
 	<!--% END %-->
 	</table>
 	<p><a href="<!--% absolute_path(baseurl) %-->contribute.html">Become a Correspondent</a></p>

templates/content-episode.tpl.html

@@ -16,10 +16,10 @@
 		<h3><!--% episode.summary %--></h3>
 		<p class="meta"><!--% episode_navigation %-->
 		</p>
-<p><!--% IF get_avatar(episode.hostid) != 'hpr_logo.png' %-->
+<p><!--% show_avatar(episode.hostid, episode.host) %-->
-<img src="<!--% absolute_path(baseurl) %-->images/<!--% get_avatar(episode.hostid) %-->" height="80" width="80" alt="" /></a><br><!--% END %-->
 Hosted by <a href="<!--% absolute_path(baseurl) %-->correspondents/<!--% zero_pad_left(episode.hostid) %-->.html"><!--% episode.host %--></a> on <span><!--% episode.date %--></span> is flagged as <span><!--% display_explicit(episode.explicit) %--></span> and is released under a <span><!--% episode.license %--> license</span>. <br>
 <!--% display_tags(episode.tags) %--> <br>
+<!--% listen_now(episode, "hpr", baseurl, media_baseurl) %-->
 <!--% display_listen_in(episode.id) %--> | 
 <!--% display_comments_tally(episode.id, episode.eps_tally) %-->
 </p>
@@ -28,10 +28,7 @@ Hosted by <a href="<!--% absolute_path(baseurl) %-->correspondents/<!--% zero_pa
 	</header>
 	<div><!--% episode.notes %--></div>
 <footer>
-
 <!--% show_transcript(episode, "hpr", baseurl, media_baseurl) %-->
-
-<!--% listen_now(episode, "hpr", baseurl, media_baseurl) %-->
 <p>
 <!--% episode_navigation %-->
 </p>

templates/content-index.tpl.html

@@ -1,11 +1,28 @@
 <!--% PROCESS 'shared-avatar.tpl.html' %-->
-<!--% PROCESS 'host-thumbnail.tpl.html' %-->
 <!--% PROCESS 'shared-utils.tpl.html' %-->
 <!--% PROCESS 'shared-listen-now.tpl.html' %-->
 <!--% PROCESS 'shared-show-transcript.tpl.html' %-->
 <!--% PROCESS 'shared-call_for_shows.tpl.html' %-->
 <!--% INCLUDE 'content-index-announcement.tpl.html' %-->
 <!--% PROCESS "queries-index-${constants.database}.tpl.html" %-->
+<!--% MACRO tidy_notes(all_lines) BLOCK %-->
+<!--% lines = all_lines %-->
+<!--% after_html = all_lines %-->
+<!--% img_re = '(?six)^(.*?)\<img ([^\>]+\>)(.+)$' %-->
+<!--% lazy_re = '(?i)loading="lazy"' %-->
+<!--% WHILE (matches = lines.match(img_re)) %-->
+<!--% img_tag = matches.1 %-->
+<!--% after_html = matches.2 %-->
+<!--% matches.0 %-->
+<!--% IF (img_tag.search(lazy_re)) %-->
+    <img <!--% img_tag %-->
+<!--% ELSE %-->
+    <img loading="lazy" <!--% img_tag %-->
+<!--% END %-->
+<!--% lines = after_html %-->
+<!--% END %-->
+<!--% after_html %-->
+<!--% END %-->
 <hr>
   <article>
     <header>
@@ -44,21 +61,17 @@
 	<header>
 			<h1><a href="<!--% absolute_path(baseurl) %-->eps/hpr<!--% zero_pad_left(latest_episodes.id) %-->/index.html">hpr<!--% latest_episodes.id %--> :: <!--% latest_episodes.title %--></a></h1>
 		<h3><!--% latest_episodes.summary%--></h3>
-		<p class="meta"$><!--% IF get_avatar(latest_episodes.hostid) != 'hpr_logo.png' %-->
+		<p class="meta"$><!--% show_avatar(latest_episodes.hostid, latest_episodes.host, host_cnt) %-->
-			<a href="<!--% absolute_path(baseurl) %-->correspondents/<!--% zero_pad_left(latest_episodes.hostid) %-->.html">
+	Hosted by <a href="<!--% absolute_path(baseurl) %-->correspondents/<!--% zero_pad_left(latest_episodes.hostid) %-->.html"><!--% latest_episodes.host %--></a> on <!--% latest_episodes.date %--> is flagged as <!--% display_explicit(latest_episodes.explicit) %--> and released under a <!--% latest_episodes.license %--> license. <br>
-				<!--% host_thumb(get_avatar(latest_episodes.hostid), latest_episodes.host, host_cnt) %-->
-			</a><!--% END %-->
-	<br>Hosted by <a href="<!--% absolute_path(baseurl) %-->correspondents/<!--% zero_pad_left(latest_episodes.hostid) %-->.html"><!--% latest_episodes.host %--></a> on <!--% latest_episodes.date %--> is flagged as <!--% display_explicit(latest_episodes.explicit) %--> and released under a <!--% latest_episodes.license %--> license. <br>
 <!--% display_tags(latest_episodes.tags) %--><br>
+<!--% listen_now(latest_episodes, "hpr", baseurl, media_baseurl) %-->
 <small><!--% display_listen_in(latest_episodes.id) %--> <!--% show_series(latest_episodes.series, latest_episodes.seriesid) %--> | 
 <!--% display_comments_tally(latest_episodes.id, latest_episodes.eps_tally) %--></small>
 		</p>
 	</header>
-		<!--% latest_episodes.notes %-->
+		<!--% tidy_notes(latest_episodes.notes) %-->
 	<footer>
 	<!--% show_transcript(latest_episodes, "hpr", baseurl, media_baseurl) %-->
-
-	<!--% listen_now(latest_episodes, "hpr", baseurl, media_baseurl) %-->
 	</footer>
 </article>
 <!--% host_cnt = host_cnt + 1 %-->

templates/content-twat_episode.tpl.html

@@ -52,10 +52,10 @@
 		<h3><!--% episode.summary %--></h3>
 		<p class="meta"><!--% episode_navigation %-->
 		</p>
-<p><!--% IF get_avatar(episode.hostid) != 'hpr_logo.png' %-->
+<p><!--% show_avatar(episode.hostid, episode.host) %-->
-<img src="<!--% absolute_path(baseurl) %-->images/<!--% get_avatar(episode.hostid) %-->" height="80" width="80" alt="" /></a><br><!--% END %-->
 Hosted by <a href="<!--% absolute_path(baseurl) %-->correspondents/<!--% zero_pad_left(episode.hostid) %-->.html"><!--% episode.host %--></a> on <span><!--% episode.date %--></span> is flagged as <span><!--% display_explicit(episode.explicit) %--></span> and is released under a <span><!--% episode.license %--> license</span>. <br>
 <!--% display_tags(episode.tags) %--> <br>
+<!--% listen_now(episode, "twat", baseurl, media_baseurl) %-->
 <!--% display_listen_in(episode.id, "twat") %-->  
 </p>
 <h3><!--% show_series(episode.series, episode.seriesid, "Part of the series") %--></h3> 
@@ -63,7 +63,6 @@ Hosted by <a href="<!--% absolute_path(baseurl) %-->correspondents/<!--% zero_pa
 	</header>
 	<div><!--% episode.notes %--></div>
 <footer>
-<!--% listen_now(episode, "twat", baseurl, media_baseurl) %-->
 <p>
 <!--% episode_navigation %-->
 </p>

templates/host-thumbnail.tpl.html

@@ -1,3 +0,0 @@
-<!--% MACRO host_thumb(avatar, host_name, host_cnt) BLOCK %-->
-<img src="<!--% absolute_path(baseurl) %-->images/<!--% avatar %-->" height="80" width="80" alt="Thumbnail of <!--% host_name | html %-->" <!--% IF host_cnt %-->loading="lazy"<!--% END %--> />
-<!--% END %-->

templates/navigation-about.tpl.html

@@ -6,5 +6,5 @@
 			<li><a href="<!--% absolute_path(baseurl) %-->correspondents/index.html">Hosts</a></li>
 			<li><a href="<!--% absolute_path(baseurl) %-->contact.html">Contact</a></li>
 			<li><a href="<!--% absolute_path(baseurl) %-->promote.html">Promote HPR</a></li>
-			<li><a href="<!--% absolute_path(baseurl) %-->comments_viewer.php">Show Comments</a></li>
+			<li><a href="<!--% absolute_path(baseurl) %-->comments_viewer.html">Show Comments</a></li>
 		</ul>

templates/shared-avatar.tpl.html

@@ -1,5 +1,16 @@
-<!--% MACRO get_avatar(host_id) BLOCK  %-->
+<!--% MACRO lazy_load(is_lazy) BLOCK %-->
+<!--% IF is_lazy %-->loading="lazy"<!--% END %-->
+<!--% END %-->
+<!--% MACRO get_avatar_src(host_id) BLOCK  %-->
 <!--% TRY %-->
 <!--% USE File ("./public_html/images/hosts/${host_id}.png") %-->hosts/<!--% File.name %-->
 <!--% CATCH File %-->hpr_logo.png<!--% END %-->
 <!--% END %-->
+<!--% MACRO get_avatar(host_id, host_name, is_lazy_loaded) BLOCK %-->
+<img src="<!--% absolute_path(baseurl) %-->images/<!--% get_avatar_src(host_id) %-->" height="80" width="80" alt="Thumbnail of <!--% host_name | html %-->" <!--% lazy_load(is_lazy_loaded) %--> />
+<!--% END %-->
+<!--% MACRO show_avatar(host_id, host_name, is_lazy_loaded) BLOCK %-->
+<!--% IF get_avatar_src(host_id) != 'hpr_logo.png' %-->
+<a href="<!--% absolute_path(baseurl) %-->correspondents/<!--% zero_pad_left(host_id) %-->.html"><!--% get_avatar(host_id, host_name, is_lazy_loaded) %--></a><br>
+<!--% END %-->
+<!--% END %-->

utils/update-hpr-db.sh

@@ -0,0 +1,54 @@
+#!/bin/bash - 
+#===============================================================================
+#
+#          FILE: update-hpr-db.sh
+# 
+#         USAGE: ./update-hpr-db.sh 
+# 
+#   DESCRIPTION: Download MySQL hpr.sql file and create SQLite3 file
+# 
+#       OPTIONS: ---
+#  REQUIREMENTS: lib_utils.sh
+#          BUGS: ---
+#         NOTES: ---
+#        AUTHOR: Roan "Rho`n" Horning (roan.horning@gmail.com)
+#  ORGANIZATION: 
+#       CREATED: 03/05/2023 07:21:29 PM
+#      REVISION:  ---
+#       LICENSE: GNU AGPLv3 
+#
+#    This program is free software: you can redistribute it and/or modify
+#    it under the terms of the GNU Affero General Public License as published by
+#    the Free Software Foundation, either version 3 of the License, or
+#    (at your option) any later version.
+#
+#    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.  See the
+#    GNU Affero General Public License for more details.
+#
+#    You should have received a copy of the GNU Affero General Public License
+#    along with this program.  If not, see <https://www.gnu.org/licenses/>.	
+#
+#===============================================================================
+
+set -o nounset                              # Treat unset variables as an error
+
+BASEDIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"
+
+#
+# Load library functions
+#
+LIB="$BASEDIR/lib_utils.sh"
+[ -e $LIB ] || { echo "Unable to load functions.\n$LIB not found."; exit; }
+source $LIB
+
+WORKING_DIR=`make_working_dir`
+
+download_hpr_sql $WORKING_DIR
+
+make_hpr_sqlite_db $WORKING_DIR
+
+copy_to_public_dir $WORKING_DIR `pwd`
+
+clean_working_dir $WORKING_DIR