From 4ffe4f84a226305de5005d8c56c885338137e428 Mon Sep 17 00:00:00 2001
From: Landon Curt Noll <github-mail@asthe.com>
Date: Mon, 16 Jun 2025 19:26:42 -0700
Subject: [PATCH] improve tools as requirements of final judging rounds

We moved the building of an initial entry `README.md` file functionality
form `bin/cvt-submission.sh` to a new `bin/gen-readme.sh` tool.

Add `bin/gen-readme.sh` VERSION "2.0.0 2025-06-16".

Update `bin/cvt-submission.sh` to ignore while running `chkentry(1)`,
any submission top level `REDAME.md` file.

Removed unused template file `template/entry/README_md`.

Changed `bin/cvt-submission.sh` allowed  minimum `chkentry(1)` VERSION from "1.1.5"
to "2.0.5".

Changed `bin/cvt-submission.sh` VERSION from "2.0.5 2025-05-18"
to "2.1.0 2025-06-16".

Update sitemap.

Tested the above via `make gen_top_html timestamp` on macOS.
---
 bin/README.md                 |  18 ++
 bin/cvt-submission.sh         |  82 +++++---
 bin/gen-readme.sh             | 364 ++++++++++++++++++++++++++++++++++
 bin/index.html                |  10 +
 sitemap.xml                   |  18 +-
 template/entry/README.md.head |  26 ++-
 template/entry/README.md.tail |   2 +-
 template/entry/README_md      |  58 ------
 8 files changed, 481 insertions(+), 97 deletions(-)
 create mode 100755 bin/gen-readme.sh
 delete mode 100644 template/entry/README_md

diff --git a/bin/README.md b/bin/README.md
index 04202c20d..7dc18636f 100644
--- a/bin/README.md
+++ b/bin/README.md
@@ -573,6 +573,24 @@ We recommend that this tool be invoked via the top level `Makefile`:
 ```
 
 
+<div id="gen-readme">
+### [gen-readme.sh](%%REPO_URL%%/bin/gen-readme.sh)
+</div>
+
+Generate a `README.md` file a submission's `remarks.md` and the
+template files in [template/entry/README.md.head](%%REPO_URL%%/template/entry/README.md.head)
+and [template/entry/README.md.tail](%%REPO_URL%%/template/entry/README.md.tail).
+
+Usage:
+
+``` <!---sh-->
+    bin/gen-readme.sh -v 1 YYYY template/entry/README.md.head YYYY/dir/remarks.md template/entry/README.md.tail YYYY/dir/README.md
+```
+
+While this tool is used by [cvt-submission](#cvt-submission), it may also
+be used by hand by the [Judges](../judges.html) during the final judging rounds.
+
+
 <div id="gen-sitemap">
 ### [gen-sitemap.sh](%%REPO_URL%%/bin/gen-sitemap.sh)
 </div>
diff --git a/bin/cvt-submission.sh b/bin/cvt-submission.sh
index 8ff0035f6..47433babb 100755
--- a/bin/cvt-submission.sh
+++ b/bin/cvt-submission.sh
@@ -124,7 +124,7 @@ export LC_ALL="C"
 
 # set variables referenced in the usage message
 #
-export VERSION="2.0.5 2025-05-18"
+export VERSION="2.1.0 2025-06-16"
 NAME=$(basename "$0")
 export NAME
 export V_FLAG=0
@@ -139,6 +139,7 @@ status="$?"
 if [[ $status -eq 0 ]]; then
     TOPDIR=$("$GIT_TOOL" rev-parse --show-toplevel)
 fi
+export TOPDIR
 #
 VERGE=$(type -P verge)
 export VERGE
@@ -180,7 +181,7 @@ if [[ -z "$CHKENTRY_TOOL" ]]; then
     echo "$0: Notice: then if needed: make clobber all install" 1>&2
     exit 5
 fi
-export MIN_CHKENTRY_VERSION="1.1.5"
+export MIN_CHKENTRY_VERSION="2.0.5"
 CHKENTRY_VERSION=$("$CHKENTRY_TOOL" -V | head -1 | awk '{print $3;}')
 if ! "$VERGE" "$CHKENTRY_VERSION" "$MIN_CHKENTRY_VERSION"; then
     echo "$0: FATAL: chkentry version: $CHKENTRY_VERSION < minimum version: $MIN_CHKENTRY_VERSION" 1>&2
@@ -190,6 +191,7 @@ if ! "$VERGE" "$CHKENTRY_VERSION" "$MIN_CHKENTRY_VERSION"; then
     echo "$0: notice: then: cd jparse && sudo make install clobber" 1>&2
     exit 5
 fi
+export GEN_README_TOOL="$TOPDIR/bin/gen-readme.sh"
 #
 GTAR_TOOL=$(type -P gtar)
 export GTAR_TOOL
@@ -198,7 +200,6 @@ if [[ -z "$GIT_TOOL" ]]; then
     exit 5
 fi
 #
-export TOPDIR
 export REPO_TOP_URL="https://github.com/ioccc-src/winner"
 # GitHub puts individual files under the "blob/master" sub-directory.
 export REPO_URL="$REPO_TOP_URL/blob/master"
@@ -230,7 +231,7 @@ export X_3="X""X""X"
 # usage
 #
 export USAGE="usage: $0 [-h] [-v level] [-V] [-d topdir]
-	[-c chkentry] [-T tarball_dir]
+	[-c chkentry] [-g gen-readme.sh] [-T tarball_dir]
         [-i input_data] [-n] [-N] YYYY/dir
 
 	-h		print help message and exit
@@ -239,6 +240,7 @@ export USAGE="usage: $0 [-h] [-v level] [-V] [-d topdir]
 
 	-d topdir	set topdir (def: $TOPDIR)
 	-c chkentry	path to the chkentry tool (def: $CHKENTRY_TOOL)
+	-g gen-readme.sh	path to the gen-readme.sh tool (def: $GEN_README_TOOL)
 
 	-T tarball_dir	where to form the compressed tarball of modified files (def: $TARBALL_DIR)
 
@@ -789,7 +791,7 @@ function write_author_handle_file
 
 # parse command line
 #
-while getopts :hv:Vd:c:i:T:nN flag; do
+while getopts :hv:Vd:c:g:i:T:nN flag; do
   case "$flag" in
     h) echo "$USAGE" 1>&2
 	exit 2
@@ -803,6 +805,8 @@ while getopts :hv:Vd:c:i:T:nN flag; do
 	;;
     c) CHKENTRY_TOOL="$OPTARG"
 	;;
+    g) GEN_README_TOOL="$OPTARG"
+	;;
     i) INPUT_DATA_FILE="$OPTARG"
 	;;
     T) TARBALL_DIR="$OPTARG"
@@ -1129,6 +1133,7 @@ if [[ $V_FLAG -ge 3 ]]; then
     echo "$0: debug[3]: GIT_TOOL=$GIT_TOOL" 1>&2
     echo "$0: debug[3]: TOPDIR=$TOPDIR" 1>&2
     echo "$0: debug[3]: CHKENTRY_TOOL=$CHKENTRY_TOOL" 1>&2
+    echo "$0: debug[3]: GEN_README_TOOL=$GEN_README_TOOL" 1>&2
     echo "$0: debug[3]: VERGE=$VERGE" 1>&2
     echo "$0: debug[3]: JSTRDECODE=$JSTRDECODE" 1>&2
     echo "$0: debug[3]: MIN_JSTRDECODE_VERSION=$MIN_JSTRDECODE_VERSION" 1>&2
@@ -1237,6 +1242,22 @@ if [[ ! -x $CHKENTRY_TOOL ]]; then
 fi
 
 
+# firewall - verify gen-readme.sh tool
+#
+if [[ ! -e $GEN_README_TOOL ]]; then
+    echo "$0: ERROR: gen-readme.sh file does not exist: $GEN_README_TOOL" 1>&2
+    exit 5
+fi
+if [[ ! -f $GEN_README_TOOL ]]; then
+    echo "$0: ERROR: gen-readme.sh is not a file: $GEN_README_TOOL" 1>&2
+    exit 5
+fi
+if [[ ! -x $GEN_README_TOOL ]]; then
+    echo "$0: ERROR: cannot find an executable gen-readme.sh tool: $GEN_README_TOOL" 1>&2
+    exit 5
+fi
+
+
 # verify that YEAR is already in .top
 #
 if ! grep -E -q "^$YEAR_DIR$" "$TOP_FILE"; then
@@ -1429,22 +1450,24 @@ fi
 #
 if [[ $V_FLAG -ge 1 ]]; then
     echo "$0: debug[1]: about to run: $CHKENTRY_TOOL -v 1" \
-	 "-i .auth.json.xz -i .prev -i .submit.sh -i .txz -i .num.sh -i .orig -i .path" \
-	 "-- $YYYY_DIR" 1>&2
-    "$CHKENTRY_TOOL" -v 1 -i .auth.json.xz -i .prev -i .submit.sh -i .txz -i .num.sh -i .orig -i .path -- "$YYYY_DIR"
+	 "-i .auth.json.xz -i .prev -i .submit.sh -i .txz -i .num.sh -i .orig" \
+	 "-i .path -i README.md -- $YYYY_DIR" 1>&2
+    "$CHKENTRY_TOOL" -v 1 -i .auth.json.xz -i .prev -i .submit.sh -i .txz -i .num.sh -i .orig \
+			  -i .path -i README.md -- "$YYYY_DIR"
     status="$?"
     if [[ $status -ne 0 ]]; then
-	echo "$0: ERROR: $CHKENTRY_TOOL -v 1 -i .auth.json.xz -i .prev -i .submit.sh -i .txz -i .num.sh -i .orig -i .path" \
-	     "-- $YYYY_DIR failed," \
+	echo "$0: ERROR: $CHKENTRY_TOOL -v 1 -i .auth.json.xz -i .prev -i .submit.sh -i .txz -i .num.sh -i .orig" \
+	     "-i .path -i README.md -- $YYYY_DIR failed," \
 	      "error code: $status" 1>&2
 	exit 7
     fi
 else
-    "$CHKENTRY_TOOL" -i .auth.json.xz -i .prev -i .submit.sh -i .txz -i .num.sh -i .orig -i .path -- "$YYYY_DIR"
+    "$CHKENTRY_TOOL" -i .auth.json.xz -i .prev -i .submit.sh -i .txz -i .num.sh -i .orig \
+		     -i .path -i README.md -- "$YYYY_DIR"
     status="$?"
     if [[ $status -ne 0 ]]; then
-	echo "$0: $CHKENTRY_TOOL -i .auth.json.xz -i .prev -i .submit.sh -i .txz -i .num.sh -i .orig -i .path" \
-	     "-- $YYYY_DIR failed," \
+	echo "$0: $CHKENTRY_TOOL -i .auth.json.xz -i .prev -i .submit.sh -i .txz -i .num.sh -i .orig" \
+	     "-i .path -i README.md -- $YYYY_DIR failed," \
 	      "error code: $status" 1>&2
 	exit 7
     fi
@@ -2349,13 +2372,16 @@ if [[ -z $NOOP ]]; then
 	if [[ $V_FLAG -ge 3 ]]; then
 	    echo  "$0: debug[3]: forming README.md: $README_MD"
 	fi
-	cat "$TEMPLATE_README_MD_HEAD" > "$README_MD"
-	if [[ -f $YYYY_DIR/remarks.md ]]; then
-	    cat "$YYYY_DIR/remarks.md" >> "$README_MD"
-	else
-	    echo "$X_3 - no remarks.md file was found" >> "$README_MD"
+	"$GEN_README_TOOL" "$YEAR_DIR" "$TEMPLATE_README_MD_HEAD" "$YYYY_DIR/remarks.md" "$TEMPLATE_README_MD_TAIL" "$README_MD"
+	status="$?"
+	if [[ $status -ne 0 ]]; then
+	    echo "$0: ERROR: $GEN_README_TOOL $YEAR_DIR $TEMPLATE_README_MD_HEAD $YYYY_DIR/remarks.md" \
+		 "$TEMPLATE_README_MD_TAIL $README_MD failed," \
+		 "error code: $status" 1>&2
+	    exit 59
 	fi
-	sed -e "s/$X_3-YEAR-$X_3/$YEAR_DIR/" "$TEMPLATE_README_MD_TAIL" >> "$README_MD"
+    elif [[ $V_FLAG -ge 3 ]]; then
+	echo "$0: debug[3]: README.md file already exists, skipping forming: $README_MD" 1>&2
     fi
 
     # write manifest csv line for README.md
@@ -2379,7 +2405,7 @@ if [[ -z $NOOP ]]; then
     if [[ $status -ne 0 ]]; then
         echo "$0: ERROR: LC_ALL=C sort -t, -k2n -k1,1 -k3,6 $TMP_MANIFEST_CSV -o $TMP_MANIFEST_CSV failed," \
              "error code: $status" 1>&2
-        exit 59
+        exit 60
     elif [[ $V_FLAG -ge 3 ]]; then
         echo "$0: debug[3]: sorted temporary manifest csv file: $TMP_MANIFEST_CSV" 1>&2
     fi
@@ -2422,7 +2448,7 @@ if [[ -z $NOOP ]]; then
     if [[ $status -ne 0 ]]; then
 	echo "$0: ERROR: $JPARSE_TOOL -q -- $TMP_ENTRY_JSON filed," \
 	     "error code: $status" 1>&2
-	exit 60
+	exit 61
     elif [[ $V_FLAG -ge 3 ]]; then
 	echo "$0: debug[3]: valid JSON: $TMP_ENTRY_JSON" 1>&2
     fi
@@ -2454,13 +2480,13 @@ if [[ -z $NOOP ]]; then
         if [[ $status -ne 0 ]]; then
             echo "$0: ERROR: mv -f -- $TMP_ENTRY_JSON $ENTRY_JSON filed," \
 	         "error code: $status" 1>&2
-            exit 61
+            exit 62
         elif [[ $V_FLAG -ge 1 ]]; then
             echo "$0: debug[1]: updated .entry.json: $ENTRY_JSON" 1>&2
         fi
         if [[ ! -s $ENTRY_JSON ]]; then
             echo "$0: ERROR: not a non-empty .entry.json: $ENTRY_JSON" 1>&2
-            exit 62
+            exit 63
         fi
     fi
 
@@ -2494,7 +2520,7 @@ for EXTRA_FILE in $EXTRA_FILE_SET; do
 		if [[ $status -ne 0 ]]; then
 		    echo "$0: ERROR: $OTHERMD2HTML_SH -v $V_FLAG -- $YYYY_DIR/$EXTRA_FILE filed," \
 			 "error code: $status" 1>&2
-		    exit 63
+		    exit 64
 		fi
 	    elif [[ $V_FLAG -ge 3 ]]; then
 		echo "$0: debug[3]: -n disabled forming HTML: $YYYY_DIR/$HTML_FILE" 1>&2
@@ -2527,7 +2553,7 @@ if [[ $status -ne 0 ]]; then
 	if [[ $status -ne 0 ]]; then
 	    echo "$0: ERROR: chmod +w $ALLYEAR filed," \
 		 "error code: $status" 1>&2
-	    exit 64
+	    exit 65
 	fi
 
 	# append YYYY_DIR to .allyear
@@ -2541,7 +2567,7 @@ if [[ $status -ne 0 ]]; then
 	if [[ $status -ne 0 ]]; then
 	    echo "$0: ERROR: sort -f -d -u $ALLYEAR -o $ALLYEAR filed," \
 		 "error code: $status" 1>&2
-	    exit 65
+	    exit 66
 	fi
 
     elif [[ $V_FLAG -ge 1 ]]; then
@@ -2566,7 +2592,7 @@ if [[ -z $NOOP ]]; then
 	if [[ $status -ne 0 ]]; then
 	    echo "$0: ERROR: $MD2HTML_SH -v $V_FLAG -- $README_MD $INDEX_HTML filed," \
 		 "error code: $status" 1>&2
-	    exit 66
+	    exit 67
 	fi
     fi
 
@@ -2590,7 +2616,7 @@ if [[ $status -ne 0 ]]; then
     echo "$0: ERROR: rm -f -v -- $INFO_JSON $AUTH_JSON $AUTH_JSON.xz $REMARKS_MD $YYYY_DIR/.prev" \
 	 "$YYYY_DIR/.submit.sh $YYYY_DIR/.txz $YYYY_DIR/.num.sh $YYYY_DIR/.orig filed," \
 	 "error code: $status" 1>&2
-    exit 65
+    exit 68
 fi
 
 
diff --git a/bin/gen-readme.sh b/bin/gen-readme.sh
new file mode 100755
index 000000000..4d2dfa6f4
--- /dev/null
+++ b/bin/gen-readme.sh
@@ -0,0 +1,364 @@
+#!/usr/bin/env bash
+#
+# cvt-submission.sh - Form README.md from remarks.md and 2 templates
+#
+# Given a submission (that may be in the final rounds of judging
+# but may not not yet have won the IOCCC) form a README.md file
+# using the contents of the remarks.md and templates from
+# template/entry/README.md.head and template/entry/README.md.tail.
+#
+# This script was written in 2025 by:
+#
+#   chongo (Landon Curt Noll, http://www.isthe.com/chongo/index.html) /\oo/\
+#
+# Copyright (c) 2025 by Landon Curt Noll.  All Rights Reserved.
+#
+# Permission to use, copy, modify, and distribute this software and
+# its documentation for any purpose and without fee is hereby granted,
+# provided that the above copyright, this permission notice and text
+# this comment, and the disclaimer below appear in all of the following:
+#
+#       supporting documentation
+#       source copies
+#       source works derived from this source
+#       binaries derived from this source or from derived source
+#
+# LANDON CURT NOLL DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE,
+# INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO
+# EVENT SHALL LANDON CURT NOLL BE LIABLE FOR ANY SPECIAL, INDIRECT OR
+# CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF
+# USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
+# OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
+# PERFORMANCE OF THIS SOFTWARE.
+#
+# chongo (Landon Curt Noll, http://www.isthe.com/chongo/index.html) /\oo/\
+#
+# Share and enjoy! :-)
+
+
+# firewall - run only with a bash that is version 5.1.8 or later
+#
+# The "/usr/bin/env bash" command must result in using a bash that
+# is version 5.1.8 or later.
+#
+# We could relax this version and insist on version 4.2 or later.  Versions
+# of bash between 4.2 and 5.1.7 might work.  However, to be safe, we will require
+# bash version 5.1.8 or later.
+#
+# WHY 5.1.8 and not 4.2?  This safely is done because macOS Homebrew bash we
+# often use is "version 5.2.26(1)-release" or later, and the RHEL Linux bash we
+# use often use is "version 5.1.8(1)-release" or later.  These versions are what
+# we initially tested.  We recommend you either upgrade bash or install a newer
+# version of bash and adjust your $PATH so that "/usr/bin/env bash" finds a bash
+# that is version 5.1.8 or later.
+#
+# NOTE: The macOS shipped, as of 2024 March 15, a version of bash is something like
+#	bash "version 3.2.57(1)-release".  That macOS shipped version of bash
+#	will NOT work.  For users of macOS we recommend you install Homebrew,
+#	(see https://brew.sh), and then run "brew install bash" which will
+#	typically install it into /opt/homebrew/bin/bash, and then arrange your $PATH
+#	so that "/usr/bin/env bash" finds "/opt/homebrew/bin" (or whatever the
+#	Homebrew bash is).
+#
+# NOTE: And while MacPorts might work, we noticed a number of subtle differences
+#	with some of their ported tools to suggest you might be better off
+#	with installing Homebrew (see https://brew.sh).  No disrespect is intended
+#	to the MacPorts team as they do a commendable job.  Nevertheless we ran
+#	into enough differences with MacPorts environments to suggest you
+#	might find a better experience with this tool under Homebrew instead.
+#
+if [[ -z ${BASH_VERSINFO[0]} ||
+	 ${BASH_VERSINFO[0]} -lt 5 ||
+	 ${BASH_VERSINFO[0]} -eq 5 && ${BASH_VERSINFO[1]} -lt 1 ||
+	 ${BASH_VERSINFO[0]} -eq 5 && ${BASH_VERSINFO[1]} -eq 1 && ${BASH_VERSINFO[2]} -lt 8 ]]; then
+    echo "$0: ERROR: bash version needs to be >= 5.1.8: $BASH_VERSION" 1>&2
+    echo "$0: Warning: bash version >= 4.2 might work but 5.1.8 was the minimum we tested" 1>&2
+    echo "$0: Notice: For macOS users: install Homebrew (see https://brew.sh), then run" \
+	 ""brew install bash" and then modify your \$PATH so that \"#!/usr/bin/env bash\"" \
+	 "finds the Homebrew installed (usually /opt/homebrew/bin/bash) version of bash" 1>&2
+    exit 4
+fi
+
+
+# setup bash file matching
+#
+# We must declare arrays with -ag or -Ag, and we need loops to "export" modified variables.
+# This requires a bash with a version 4.2 or later.  See the larger comment above about bash versions.
+#
+shopt -s nullglob	# enable expanded to nothing rather than remaining unexpanded
+shopt -u failglob	# disable error message if no matches are found
+shopt -u dotglob	# disable matching files starting with .
+shopt -u nocaseglob	# disable strict case matching
+shopt -u extglob	# enable extended globbing patterns
+shopt -s globstar	# enable ** to match all files and zero or more directories and subdirectories
+
+
+# IOCCC requires use of C locale
+#
+export LANG="C"
+export LC_CTYPE="C"
+export LC_NUMERIC="C"
+export LC_TIME="C"
+export LC_COLLATE="C"
+export LC_MONETARY="C"
+export LC_MESSAGES="C"
+export LC_PAPER="C"
+export LC_NAME="C"
+export LC_ADDRESS="C"
+export LC_TELEPHONE="C"
+export LC_MEASUREMENT="C"
+export LC_IDENTIFICATION="C"
+export LC_ALL="C"
+
+
+# set variables referenced in the usage message
+#
+export VERSION="2.0.0 2025-06-16"
+NAME=$(basename "$0")
+export NAME
+export V_FLAG=0
+#
+export NOOP=
+export DO_NOT_PROCESS=
+#
+export FORCE=""
+#
+export X_3="X""X""X"
+
+
+# usage
+#
+export USAGE="usage: $0 [-h] [-v level] [-V] [-d topdir]
+	[-c chkentry] [-T tarball_dir]
+        [-i input_data] [-n] [-N] YYYY README.md.head remarks.md README.md.tail README.md
+
+	-h		print help message and exit
+	-v level	set verbosity level (def level: 0)
+	-V		print version string and exit
+
+	-f		force overwrite of README.md if it exists (def: do not overwrite)
+
+	-n		go thru the actions, but do not update any files (def: do the action)
+	-N		do not process anything, just parse arguments (def: process something)
+
+	YYYY		IOCCC year
+	README.md.head	path to the README.md.head header file
+	remarks.md	path to the submission remarks.md file
+	README.md.tail	path to the README.md.tail trailer file
+	README.md	path to the README.md file to create
+
+Exit codes:
+     0         all OK
+     1	       failed to create or overwrite README.md
+     2         -h and help string printed or -V and version string printed
+     3         command line error
+     4         bash version is too old
+     5	       YYYY is not a valid year
+     6	       command line file not found or not readable
+ >= 10         internal error
+
+$NAME version: $VERSION"
+
+
+# parse command line
+#
+while getopts :hv:VfnN flag; do
+  case "$flag" in
+    h) echo "$USAGE" 1>&2
+	exit 2
+	;;
+    v) V_FLAG="$OPTARG"
+	;;
+    V) echo "$VERSION"
+	exit 2
+	;;
+    f) FORCE="true"
+	;;
+    n) NOOP="-n"
+	;;
+    N) DO_NOT_PROCESS="-N"
+	;;
+    \?) echo "$0: ERROR: invalid option: -$OPTARG" 1>&2
+	echo 1>&2
+	echo "$USAGE" 1>&2
+	exit 3
+	;;
+    :) echo "$0: ERROR: option -$OPTARG requires an argument" 1>&2
+	echo 1>&2
+	echo "$USAGE" 1>&2
+	exit 3
+	;;
+    *) echo "$0: ERROR: unexpected value from getopts: $flag" 1>&2
+	echo 1>&2
+	echo "$USAGE" 1>&2
+	exit 3
+	;;
+  esac
+done
+#
+# remove the options
+#
+shift $(( OPTIND - 1 ));
+#
+if [[ $V_FLAG -ge 5 ]]; then
+    echo "$0: debug[5]: file argument count: $#" 1>&2
+fi
+#
+# verify arg count and parse args
+#
+if [[ $# -ne 5 ]]; then
+    echo "$0: ERROR: expected 5 args, found: $#" 1>&2
+    echo 1>&2
+    echo "$USAGE" 1>&2
+    exit 3
+fi
+export YYYY="$1"
+export TEMPLATE_README_MD_HEAD="$2"
+export REMARKS_MD="$3"
+export TEMPLATE_README_MD_TAIL="$4"
+export README_MD="$5"
+
+
+# firewall - command line args
+#
+if ! [[ $YYYY =~ [0-9][0-9][0-9][0-9] ]]; then
+    echo "$0: ERROR: YYYY is not a valid 4 digit year: $YYYY" 1>&2
+    exit 5
+fi
+if [[ $YYYY -lt 1984 || $YYYY -gt 2099 ]]; then
+    echo "$0: ERROR: YYYY is not a valid IOCCC year (1984 thru 2099): $YYYY" 1>&2
+    exit 5
+fi
+if [[ ! -f $TEMPLATE_README_MD_HEAD ]]; then
+    echo "$0: ERROR: missing template README.md.head file: $TEMPLATE_README_MD_HEAD" 1>&2
+    exit 6
+fi
+if [[ ! -r $TEMPLATE_README_MD_HEAD ]]; then
+    echo "$0: ERROR: template README.md.head file not readable: $TEMPLATE_README_MD_HEAD" 1>&2
+    exit 6
+fi
+if [[ ! -f $REMARKS_MD ]]; then
+    echo "$0: ERROR: missing template remarks.md file: $REMARKS_MD" 1>&2
+    exit 6
+fi
+if [[ ! -r $REMARKS_MD ]]; then
+    echo "$0: ERROR: template remarks.md file not readable: $REMARKS_MD" 1>&2
+    exit 6
+fi
+if [[ ! -f $TEMPLATE_README_MD_TAIL ]]; then
+    echo "$0: ERROR: missing template README.md.tail file: $TEMPLATE_README_MD_TAIL" 1>&2
+    exit 6
+fi
+if [[ ! -r $TEMPLATE_README_MD_TAIL ]]; then
+    echo "$0: ERROR: template README.md.tail file not readable: $TEMPLATE_README_MD_TAIL" 1>&2
+    exit 6
+fi
+if [[ -z $FORCE && -e $README_MD ]]; then
+    echo "$0: ERROR: -f was not used and readme.md exists: $README_MD" 1>&2
+    exit 1
+fi
+
+
+# set umask to avoid group writable files
+#
+umask 0022
+
+
+# print running info if verbose
+#
+# If -v 3 or higher, print exported variables in order that they were exported.
+#
+if [[ $V_FLAG -ge 3 ]]; then
+    echo "$0: debug[3]: LANG=$LANG" 1>&2
+    echo "$0: debug[3]: LC_CTYPE=$LC_CTYPE" 1>&2
+    echo "$0: debug[3]: LC_NUMERIC=$LC_NUMERIC" 1>&2
+    echo "$0: debug[3]: LC_TIME=$LC_TIME" 1>&2
+    echo "$0: debug[3]: LC_COLLATE=$LC_COLLATE" 1>&2
+    echo "$0: debug[3]: LC_MONETARY=$LC_MONETARY" 1>&2
+    echo "$0: debug[3]: LC_MESSAGES=$LC_MESSAGES" 1>&2
+    echo "$0: debug[3]: LC_PAPER=$LC_PAPER" 1>&2
+    echo "$0: debug[3]: LC_NAME=$LC_NAME" 1>&2
+    echo "$0: debug[3]: LC_ADDRESS=$LC_ADDRESS" 1>&2
+    echo "$0: debug[3]: LC_TELEPHONE=$LC_TELEPHONE" 1>&2
+    echo "$0: debug[3]: LC_MEASUREMENT=$LC_MEASUREMENT" 1>&2
+    echo "$0: debug[3]: LC_IDENTIFICATION=$LC_IDENTIFICATION" 1>&2
+    echo "$0: debug[3]: LC_ALL=$LC_ALL" 1>&2
+    echo "$0: debug[3]: VERSION=$VERSION" 1>&2
+    echo "$0: debug[3]: NAME=$NAME" 1>&2
+    echo "$0: debug[3]: V_FLAG=$V_FLAG" 1>&2
+    echo "$0: debug[3]: NOOP=$NOOP" 1>&2
+    echo "$0: debug[3]: DO_NOT_PROCESS=$DO_NOT_PROCESS" 1>&2
+    echo "$0: debug[3]: FORCE=$FORCE" 1>&2
+    echo "$0: debug[3]: X_3=$X_3" 1>&2
+    echo "$0: debug[3]: YYYY=$YYYY" 1>&2
+    echo "$0: debug[3]: TEMPLATE_README_MD_HEAD=$TEMPLATE_README_MD_HEAD" 1>&2
+    echo "$0: debug[3]: REMARKS_MD=$REMARKS_MD" 1>&2
+    echo "$0: debug[3]: TEMPLATE_README_MD_TAIL=$TEMPLATE_README_MD_TAIL" 1>&2
+    echo "$0: debug[3]: README_MD=$README_MD" 1>&2
+fi
+
+# form README.md
+#
+if [[ -z $NOOP ]]; then
+
+    if [[ $V_FLAG -ge 3 ]]; then
+	echo  "$0: debug[3]: forming README.md: $README_MD"
+    fi
+
+    # pre-remove README.md
+    #
+    # If README.md exists, then the only way we can get here is if -f was used.
+    # If README.md does not exist, then rm -f does no harm and will not fail.
+    #
+    rm -f "$README_MD"
+    status="$?"
+    if [[ $status -ne 0 ]]; then
+	echo "$0: ERROR: rm -f $README_MD failed," \
+	     "error code: $status" 1>&2
+	exit 1
+    fi
+
+    # start with the header
+    #
+    cat "$TEMPLATE_README_MD_HEAD" > "$README_MD"
+    status="$?"
+    if [[ $status -ne 0 ]]; then
+	echo "$0: ERROR: cat $TEMPLATE_README_MD_HEAD > $README_MD failed," \
+	     "error code: $status" 1>&2
+	exit 1
+    fi
+
+    # append the submission remarks.md contents
+    #
+    cat "$REMARKS_MD" >> "$README_MD"
+    status="$?"
+    if [[ $status -ne 0 ]]; then
+	echo "$0: ERROR: cat $REMARKS_MD >> $README_MD failed," \
+	     "error code: $status" 1>&2
+	exit 1
+    fi
+
+    # append the trailer with the year substituted
+    #
+    sed -e "s/$X_3-YEAR-$X_3/$YYYY/" "$TEMPLATE_README_MD_TAIL" >> "$README_MD"
+    status="$?"
+    if [[ $status -ne 0 ]]; then
+	echo "$0: ERROR: sed -e 's/$X_3-YEAR-$X_3/$YYYY/' $TEMPLATE_README_MD_TAIL >> $README_MD failed," \
+	     "error code: $status" 1>&2
+	exit 1
+    fi
+
+    if [[ $V_FLAG -ge 1 ]]; then
+	echo  "$0: debug[1]: formed README.md: $README_MD"
+    fi
+
+# case: with -n
+#
+elif [[ $V_FLAG -ge 3 ]]; then
+    echo "$0: debug[3]: -n disabled forming README_MD" 1>&2
+fi
+
+
+# All Done!!! All Done!!! -- Jessica Noll, Age 2
+#
+exit 0
diff --git a/bin/index.html b/bin/index.html
index 36080e867..7f939c47a 100644
--- a/bin/index.html
+++ b/bin/index.html
@@ -764,6 +764,16 @@ markdown files, of all entries.</p>
 <pre><code>    bin/gen-other-html.sh -v 1</code></pre>
 <p>We recommend that this tool be invoked via the top level <code>Makefile</code>:</p>
 <pre><code>    make gen_other_html</code></pre>
+<div id="gen-readme">
+<h3 id="gen-readme.sh"><a href="https://github.com/ioccc-src/winner/blob/master/bin/gen-readme.sh">gen-readme.sh</a></h3>
+</div>
+<p>Generate a <code>README.md</code> file a submission’s <code>remarks.md</code> and the
+template files in <a href="https://github.com/ioccc-src/winner/blob/master/template/entry/README.md.head">template/entry/README.md.head</a>
+and <a href="https://github.com/ioccc-src/winner/blob/master/template/entry/README.md.tail">template/entry/README.md.tail</a>.</p>
+<p>Usage:</p>
+<pre><code>    bin/gen-readme.sh -v 1 YYYY template/entry/README.md.head YYYY/dir/remarks.md template/entry/README.md.tail YYYY/dir/README.md</code></pre>
+<p>While this tool is used by <a href="#cvt-submission">cvt-submission</a>, it may also
+be used by hand by the <a href="../judges.html">Judges</a> during the final judging rounds.</p>
 <div id="gen-sitemap">
 <h3 id="gen-sitemap.sh"><a href="https://github.com/ioccc-src/winner/blob/master/bin/gen-sitemap.sh">gen-sitemap.sh</a></h3>
 </div>
diff --git a/sitemap.xml b/sitemap.xml
index 2e674f9b4..4cc3fcd29 100644
--- a/sitemap.xml
+++ b/sitemap.xml
@@ -15226,7 +15226,7 @@
 </url>
 <url>
     <loc>https://www.ioccc.org/bin/cvt-submission.sh</loc>
-    <lastmod>2025-05-18T11:09:29+00:00</lastmod>
+    <lastmod>2025-06-17T02:12:37+00:00</lastmod>
 </url>
 <url>
     <loc>https://www.ioccc.org/bin/entry2csv.sh</loc>
@@ -15260,6 +15260,10 @@
     <loc>https://www.ioccc.org/bin/gen-other-html.sh</loc>
     <lastmod>2025-04-16T20:59:19+00:00</lastmod>
 </url>
+<url>
+    <loc>https://www.ioccc.org/bin/gen-readme.sh</loc>
+    <lastmod>2025-06-16T20:20:40+00:00</lastmod>
+</url>
 <url>
     <loc>https://www.ioccc.org/bin/gen-sitemap.sh</loc>
     <lastmod>2025-04-28T20:09:17+00:00</lastmod>
@@ -15286,11 +15290,11 @@
 </url>
 <url>
     <loc>https://www.ioccc.org/bin/index.html</loc>
-    <lastmod>2025-01-10T06:49:56+00:00</lastmod>
+    <lastmod>2025-06-17T00:53:52+00:00</lastmod>
 </url>
 <url>
     <loc>https://www.ioccc.org/bin/index.html</loc>
-    <lastmod>2025-01-10T06:49:56+00:00</lastmod>
+    <lastmod>2025-06-17T00:53:52+00:00</lastmod>
 </url>
 <url>
     <loc>https://www.ioccc.org/bin/jfmt-wrapper.sh</loc>
@@ -15358,11 +15362,11 @@
 </url>
 <url>
     <loc>https://www.ioccc.org/bin/README.md</loc>
-    <lastmod>2025-01-10T06:43:52+00:00</lastmod>
+    <lastmod>2025-06-16T20:30:35+00:00</lastmod>
 </url>
 <url>
     <loc>https://www.ioccc.org/bin/README.md</loc>
-    <lastmod>2025-01-10T06:43:52+00:00</lastmod>
+    <lastmod>2025-06-16T20:30:35+00:00</lastmod>
 </url>
 <url>
     <loc>https://www.ioccc.org/bin/sgi.sh</loc>
@@ -15486,7 +15490,7 @@
 </url>
 <url>
     <loc>https://www.ioccc.org/Makefile</loc>
-    <lastmod>2025-05-18T10:06:42+00:00</lastmod>
+    <lastmod>2025-06-17T02:18:34+00:00</lastmod>
 </url>
 <url>
     <loc>https://www.ioccc.org/markdown.html</loc>
@@ -15598,7 +15602,7 @@
 </url>
 <url>
     <loc>https://www.ioccc.org/status.html</loc>
-    <lastmod>2025-06-07T02:03:20+00:00</lastmod>
+    <lastmod>2025-06-17T02:21:57+00:00</lastmod>
 </url>
 <url>
     <loc>https://www.ioccc.org/status.json</loc>
diff --git a/template/entry/README.md.head b/template/entry/README.md.head
index 8f754f252..a0b981bcc 100644
--- a/template/entry/README.md.head
+++ b/template/entry/README.md.head
@@ -1,3 +1,6 @@
+Award: XXX - suggest award title - XXX
+
+XXX - once the .entry.json file is built by cvt-submission.sh - remove all text from top thru this line - XXX
 ## To build:
 
 ``` <!---sh-->
@@ -5,20 +8,33 @@
 ```
 
 
+### Bugs and (Mis)features:
+
+XXX - remove this section if not needed - XXX
+
+
 ## To use:
 
 ``` <!---sh-->
-    ./prog
+    ./prog XXX - add or remove args for a default or represenative run - XXX
+```
+
+
+## Try:
+
+``` <!---sh-->
+    ./try.sh
 ```
 
 
 ## Alternate code:
 
-XXX
+XXX - remove this section if not needed - XXX
 
 
 ### Alternate build:
 
+XXX - remove this section if not needed - XXX
 ``` <!---sh-->
     make alt
 ```
@@ -26,6 +42,7 @@ XXX
 
 ### Alternate use:
 
+XXX - remove this section if not needed - XXX
 ``` <!---sh-->
     ./prog.alt
 ```
@@ -33,8 +50,11 @@ XXX
 
 ## Judges' remarks:
 
-XXX
+XXX - write stuff here - XXX
+
+Please see [IOCCC markdown guidelines](https://www.ioccc.org/markdown.html) - XXX - remove this line - XXX
 
 
 ## Author's remarks:
 
+
diff --git a/template/entry/README.md.tail b/template/entry/README.md.tail
index 3683a1b1f..2e8aa6816 100644
--- a/template/entry/README.md.tail
+++ b/template/entry/README.md.tail
@@ -2,7 +2,7 @@
 
 <!--
 
-    Copyright © 1984-XXX-YEAR-XXX by Landon Curt Noll. All Rights Reserved.
+    Copyright © 1984-XXX-YEAR-XXX by Landon Curt Noll and Leonid A. Broukhis.  All Rights Reserved.
 
     You are free to share and adapt this file under the terms of this license:
 
diff --git a/template/entry/README_md b/template/entry/README_md
deleted file mode 100644
index e3b09a858..000000000
--- a/template/entry/README_md
+++ /dev/null
@@ -1,58 +0,0 @@
-## To build:
-
-``` <!---sh-->
-    make all
-```
-
-
-## To use:
-
-``` <!---sh-->
-    ./XXX
-```
-
-
-## Alternate code:
-
-XXX
-
-
-### Alternate build:
-
-``` <!---sh-->
-    make alt
-```
-
-
-### Alternate use:
-
-NOTE: this version might not work on some systems like macOS.
-
-``` <!---sh-->
-    ./XXX.alt
-```
-
-
-## Judges' remarks:
-
-XXX
-
-
-## Author's remarks:
-
-XXX-remarks.md-XXX
-
-
-<!--
-
-    Copyright © 1984-XXX-YEAR-XXX by Landon Curt Noll. All Rights Reserved.
-
-    You are free to share and adapt this file under the terms of this license:
-
-        Creative Commons Attribution-ShareAlike 4.0 International (CC BY-SA 4.0)
-
-    For more information, see:
-
-        https://creativecommons.org/licenses/by-sa/4.0/
-
--->