add YYYY/README.md processing to bin/new-year.sh

The `bin/new-year.sh` will form `YYYY/README.md` from
the template file: `template/README.md.year`.

In `bin/new-year.sh` changed VERSION from "1.2 2024-07-21"
to "1.3 2024-07-23".

Performed `make www` to accomplish the above and to test under macOS.

bin/new-year.sh

@@ -87,7 +87,7 @@ shopt -s globstar	# enable ** to match all files and zero or more directories an
 
 # set variables referenced in the usage message
 #
-export VERSION="1.2 2024-07-21"
+export VERSION="1.3 2024-07-23"
 NAME=$(basename "$0")
 export NAME
 export V_FLAG=0
@@ -102,6 +102,13 @@ status="$?"
 if [[ $status -eq 0 ]]; then
     TOPDIR=$("$GIT_TOOL" rev-parse --show-toplevel)
 fi
+NUMBER_TOOL=$(type -P number)
+export NUMBER_TOOL
+if [[ -z $NUMBER_TOOL ]]; then
+    echo "$0: FATAL: number tool is not installed or not in \$PATH" 1>&2
+    echo "$0: notice: see the number GitHub repo: https://github.com/lcn2/number" 1>&2
+    exit 5
+fi
 export TOPDIR
 export REPO_URL="https://github.com/ioccc-src/temp-test-ioccc/blob/master"
 export TEMPLATE="template"
@@ -110,6 +117,93 @@ export NOOP=
 export DO_NOT_PROCESS=
 
 
+# output_english_ordinal
+#
+# Write the English ordinal form of a non-negative integer to standard output (stdout).
+# We also capitalize the first letter of each English word.
+#
+# NOTE: We restrict the integer to non-negative simply because the contest starts
+#	with the first: the NUMBER_TOOL handles negative integers.
+#
+# NOTE: We also restrict the integer to <= 999 because the NUMBER_TOOL starts
+#       to write multi-line English names at 1000 and we don't want to parse
+#       such multi-line output.   So we leave it up to the IOCCC judges who
+#       are judging the 1000th IOCCC to improve this code.  :-)
+#
+# usage:
+#       output_english_ordinal integer
+#
+# returns:
+#       0 ==> no errors detected
+#     > 0 ==> function error number
+#
+function output_english_ordinal
+{
+    local INTEGER;	    # integer argument
+    local ENGLISH_NAME;	    # integer in English form
+    local CAP_ENGLISH_NAME; # ENGLISH_NAME with first letters Capitalized
+
+    # parse args
+    #
+    if [[ $# -ne 1 ]]; then
+        echo "$0: ERROR: in output_english_ordinal: expected 1 arg, found $#" 1>&2
+        return 1
+    fi
+    INTEGER="$1"
+    if [[ $INTEGER =~ ^-?[0-9]+$ ]]; then
+	:
+    else
+	echo "$0: ERROR: in output_english_ordinal: argument is not an integer: $INTEGER" 1>&2
+	return 2
+    fi
+    if [[ $INTEGER -lt 0 ]]; then
+	echo "$0: ERROR: in output_english_ordinal: integer is negative: $INTEGER" 1>&2
+	return 3
+    fi
+    if [[ $INTEGER -gt 999 ]]; then
+	echo "$0: ERROR: in output_english_ordinal: integer must be < 999 (see comment): $INTEGER" 1>&2
+	return 4
+    fi
+
+    # obtain the English name for INTEGER
+    #
+    ENGLISH_NAME=$("$NUMBER_TOOL" -- "$INTEGER")
+    status="$?"
+    if [[ $status -ne 0 ]]; then
+	echo "$0: ERROR: in output_english_ordinal: $NUMBER_TOOL -- $INTEGER failed," \
+	     "error code: $status" 1>&2
+	return 5
+    fi
+    if [[ -z $ENGLISH_NAME ]]; then
+	echo "$0: ERROR: in output_english_ordinal: ENGLISH_NAME is empty" 1>&2
+	return 6
+    fi
+
+    # Capitalize first letters in ENGLISH_NAME
+    #
+    CAP_ENGLISH_NAME=$(echo "$ENGLISH_NAME" | awk '{for(i=1;i<=NF;i++){ $i=toupper(substr($i,1,1)) substr($i,2) }}1')
+    status="$?"
+    if [[ $status -ne 0 ]]; then
+	echo "$0: ERROR: in output_english_ordinal: echo $ENGLISH_NAME | awk ... failed," \
+	     "error code: $status" 1>&2
+	return 7
+    fi
+    if [[ -z $CAP_ENGLISH_NAME ]]; then
+	echo "$0: ERROR: in output_english_ordinal: ENGLISH_NAME is empty" 1>&2
+	return 8
+    fi
+
+    # Output the English name as a Cardinal
+    #
+    echo "$CAP_ENGLISH_NAME" | sed -E \
+	-e 's/One$/First/' -e 's/Two$/Second/' -e 's/Three$/Third/' -e 's/Four$/Forth/' \
+	-e 's/Five$/Fifth/' -e 's/Six$/Sixth/' -e 's/Seven$/Seventh/' -e 's/Eight$/Eighth/' \
+	-e 's/Nine$/Ninth/' -e 's/Ten$/Tenth/' -e 's/Eleven$/Eleventh/' -e 's/Twelve$/Twelfth/' \
+	-e 's/teen$/teenth/' -e 's/ty$/tieth/' -e 's/dred$/dredth/'
+    return 0
+}
+
+
 # usage
 #
 export USAGE="usage: $0 [-h] [-v level] [-V] [-d topdir] [-n] [-N] year
@@ -292,6 +386,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]: REPO_URL=$REPO_URL" 1>&2
+    echo "$0: debug[3]: NUMBER_TOOL=$NUMBER_TOOL" 1>&2
     echo "$0: debug[3]: TEMPLATE=$TEMPLATE" 1>&2
     echo "$0: debug[3]: NOOP=$NOOP" 1>&2
     echo "$0: debug[3]: DO_NOT_PROCESS=$DO_NOT_PROCESS" 1>&2
@@ -429,51 +524,6 @@ elif [[ $V_FLAG -ge 3 && ! -e $YEAR_FILE ]]; then
 fi
 
 
-# form an empty YYYY/.filelist file if needed
-#
-export YEAR_FILELIST="$YEAR/.filelist"
-if [[ -z $NOOP ]]; then
-
-    # case: .filelist does not exist
-    #
-    if [[ ! -e $YEAR_FILELIST ]]; then
-
-	if [[ $V_FLAG -ge 3 ]]; then
-	    echo "$0: debug[3]: about to: touch $YEAR_FILELIST" 1>&2
-	fi
-	touch "$YEAR_FILELIST"
-	status="$?"
-        if [[ $status -ne 0 ]]; then
-            echo "$0: ERROR: touch $YEAR_FILELIST filed," \
-	         "error code: $status" 1>&2
-            exit 18
-        elif [[ $V_FLAG -ge 1 ]]; then
-            echo "$0: debug[1]: created: $YEAR_FILELIST" 1>&2
-        fi
-
-	if [[ $V_FLAG -ge 3 ]]; then
-	    echo "$0: debug[3]: about to: make genfilelist YEARS=$YEAR" 1>&2
-	fi
-	make genfilelist YEARS="$YEAR"
-	status="$?"
-        if [[ $status -ne 0 ]]; then
-            echo "$0: ERROR: make genfilelist YEARS=$YEAR filed," \
-	         "error code: $status" 1>&2
-            exit 19
-        elif [[ $V_FLAG -ge 1 ]]; then
-            echo "$0: debug[1]: updated: $YEAR_FILELIST" 1>&2
-        fi
-
-    elif [[ ! -f $YEAR_FILE ]]; then
-	echo "$0: ERROR: .filelist exists but is not a file: $YEAR_FILELIST" 1>&2
-	exit 20
-    fi
-
-elif [[ $V_FLAG -ge 3 && ! -e $YEAR_FILELIST ]]; then
-    echo "$0: debug[3]: -n disabled creating .filelist: $YEAR_FILELIST" 1>&2
-fi
-
-
 # create a temporary Makefile
 #
 export TMP_MAKEFILE=".tmp.$NAME.MAKEFILE.$$.tmp"
@@ -484,13 +534,13 @@ trap 'rm -f $TMP_MAKEFILE; exit' 0 1 2 3 15
 rm -f "$TMP_MAKEFILE"
 if [[ -e $TMP_MAKEFILE ]]; then
     echo "$0: ERROR: cannot remove temporary Makefile: $TMP_MAKEFILE" 1>&2
-    exit 21
+    exit 18
 fi
 echo '# author_handle,entry_id,entry_id,entry_id,…,,,,,,,,,,,,,,,' > \
   "$TMP_MAKEFILE"
 if [[ ! -e $TMP_MAKEFILE ]]; then
     echo "$0: ERROR: cannot create temporary Makefile: $TMP_MAKEFILE" 1>&2
-    exit 22
+    exit 19
 fi
 
 
@@ -505,7 +555,7 @@ status="$?"
 if [[ $status -ne 0 ]]; then
     echo "$0: ERROR: make new_year NEW_YEAR=\"$YEAR\" >> \"$TMP_MAKEFILE\" failed," \
 	 "error code: $status" 1>&2
-    exit 23
+    exit 20
 fi
 sed -n -e '/^# END - DO NOT REMOVE THIS LINE - make new_year also uses this #/,$p' "$MAKE_FILE" >> "$TMP_MAKEFILE"
 
@@ -539,13 +589,13 @@ if [[ -z $NOOP ]]; then
         if [[ $status -ne 0 ]]; then
             echo "$0: ERROR: mv -f -- $TMP_MAKEFILE $MAKE_FILE filed," \
 	         "error code: $status" 1>&2
-            exit 24
+            exit 21
         elif [[ $V_FLAG -ge 1 ]]; then
             echo "$0: debug[1]: updated Makefile: $MAKE_FILE" 1>&2
         fi
         if [[ ! -s $MAKE_FILE ]]; then
             echo "$0: ERROR: not a non-empty Makefile: $MAKE_FILE" 1>&2
-            exit 25
+            exit 22
         fi
 
 	# update .top
@@ -558,7 +608,7 @@ if [[ -z $NOOP ]]; then
         if [[ $status -ne 0 ]]; then
 	    echo "$0: ERROR: make -fC$YEAR genpath_top >/dev/null failed," \
 		 "error code: $status" 1>&2
-	    exit 26
+	    exit 23
         elif [[ $V_FLAG -ge 1 ]]; then
             echo "$0: debug[1]: updated .top" 1>&2
 	fi
@@ -571,6 +621,125 @@ elif [[ $V_FLAG -ge 3 ]]; then
 fi
 
 
+# Add the template README.md if there is no YYYY/README.md file
+#
+export YEAR_README="$YEAR/README.md"
+if [[ -z $NOOP ]]; then
+
+    # case: YYYY/README.md does not exist
+    #
+    if [[ ! -e $YEAR_README ]]; then
+
+	# verify that the template directory exists
+	#
+	if [[ ! -d $TEMPLATE ]]; then
+	    echo "$0: ERROR: YYYY/README.md: $YEAR_README does not exist and" \
+		 "template is missing: $TEMPLATE" 1>&2
+	    exit 24
+	fi
+
+	# verify that the YYYY/README.md template is a file
+	#
+	export YEAR_README_TEMPLATE="$TEMPLATE/README.md.year"
+	if [[ ! -f $YEAR_README_TEMPLATE ]]; then
+	    echo "$0: ERROR: YYYY/README.md: $YEAR_README does not exist and" \
+		 "template README.md.year is missing: $YEAR_README_TEMPLATE" 1>&2
+	    exit 25
+	fi
+
+	# determine the IOCCC ordinal
+	#
+	CONTEST_NUMNER=$(sed -n "/$YEAR/=" "$TOP_FILE")
+	if [[ -z $CONTEST_NUMNER ]]; then
+	    echo "$0: ERROR: failed to determine content number for YYYY: $YEAR in: $TOP_FILE" 1>&2
+	    exit 26
+	fi
+	OUTPUT_ENGLISH_ORDINAL=$(output_english_ordinal "$CONTEST_NUMNER")
+	status="$?"
+	if [[ $status -ne 0 ]]; then
+	    echo "$0: ERROR: output_english_ordinal $CONTEST_NUMNER failed," \
+		 "error code: $status" 1>&2
+	    exit 27
+	fi
+	if [[ -z $OUTPUT_ENGLISH_ORDINAL ]]; then
+	    echo "$0: ERROR: failed to determine content orignal for YYYY: $YEAR for contest: $CONTEST_NUMNER" 1>&2
+	    exit 28
+	fi
+
+	# form year README.md
+	#
+	if [[ $V_FLAG -ge 3 ]]; then
+	    echo "$0: debug[3]: about to: sed -e ... $YEAR_README_TEMPLATE > $YEAR_README" 0>&2
+	fi
+	sed -e "s/%%YEAR%%/$YEAR/g" \
+	    -e "s/%%OUTPUT_ENGLISH_ORDINAL%%/$OUTPUT_ENGLISH_ORDINAL/g" \
+	    "$YEAR_README_TEMPLATE" > "$YEAR_README"
+	status="$?"
+        if [[ $status -ne 0 ]]; then
+            echo "$0: ERROR: sed -e .. $YEAR_README_TEMPLATE > $YEAR_README filed," \
+	         "error code: $status" 1>&2
+            exit 29
+        elif [[ $V_FLAG -ge 1 ]]; then
+            echo "$0: debug[1]: updated YYYY/README.md $YEAR_README" 1>&2
+        fi
+
+    # case: YYYY exists but is not a file
+    #
+    elif [[ ! -d $YEAR ]]; then
+	echo "$0: ERROR: YYYY/README.md exists but is not a file: $YEAR_README" 1>&2
+	exit 30
+    fi
+
+elif [[ $V_FLAG -ge 3 && ! -f $YEAR_README ]]; then
+    echo "$0: debug[3]: -n disabled creating YYYY/README.md: $YEAR_README" 1>&2
+fi
+
+
+# form YYYY/.filelist file if needed
+#
+export YEAR_FILELIST="$YEAR/.filelist"
+if [[ -z $NOOP ]]; then
+
+    # case: .filelist does not exist
+    #
+    if [[ ! -e $YEAR_FILELIST ]]; then
+
+	if [[ $V_FLAG -ge 3 ]]; then
+	    echo "$0: debug[3]: about to: touch $YEAR_FILELIST" 1>&2
+	fi
+	touch "$YEAR_FILELIST"
+	status="$?"
+        if [[ $status -ne 0 ]]; then
+            echo "$0: ERROR: touch $YEAR_FILELIST filed," \
+	         "error code: $status" 1>&2
+            exit 31
+        elif [[ $V_FLAG -ge 1 ]]; then
+            echo "$0: debug[1]: created: $YEAR_FILELIST" 1>&2
+        fi
+
+	if [[ $V_FLAG -ge 3 ]]; then
+	    echo "$0: debug[3]: about to: make genfilelist YEARS=$YEAR" 1>&2
+	fi
+	make genfilelist YEARS="$YEAR"
+	status="$?"
+        if [[ $status -ne 0 ]]; then
+            echo "$0: ERROR: make genfilelist YEARS=$YEAR filed," \
+	         "error code: $status" 1>&2
+            exit 32
+        elif [[ $V_FLAG -ge 1 ]]; then
+            echo "$0: debug[1]: updated: $YEAR_FILELIST" 1>&2
+        fi
+
+    elif [[ ! -f $YEAR_FILE ]]; then
+	echo "$0: ERROR: .filelist exists but is not a file: $YEAR_FILELIST" 1>&2
+	exit 33
+    fi
+
+elif [[ $V_FLAG -ge 3 && ! -e $YEAR_FILELIST ]]; then
+    echo "$0: debug[3]: -n disabled creating .filelist: $YEAR_FILELIST" 1>&2
+fi
+
+
 # All Done!!! All Done!!! -- Jessica Noll, Age 2
 #
 exit 0

template/README.md.year

@@ -0,0 +1,50 @@
+# %%OUTPUT_ENGLISH_ORDINAL%% International Obfuscated C Code Contest
+
+
+## Standard IOCCC stuff
+
+%%XXX%% - put text here - XXX
+
+View the `index.html` web page for the given winning entry for information on how
+on how to compile it and how to run the winning program.
+Look at the winning source and try to figure how it does what it does!
+You may then wish to look at the Author's remarks for even more details.
+
+Some C compilers are not quite as good as they should be.  If yours is
+lacking, you may need to compile using clang or gcc instead of your local
+compiler.
+
+The primary website can be found at [www.ioccc.org](https://www.ioccc.org).
+
+
+## Remarks on some of the winning entries
+
+%%XXX%% - add text here - XXX
+
+
+## %%XXX%% - other remarks if needed - XXX
+
+%%XXX%% - add text here if needed - XXX
+
+
+## Final Comments
+
+%%XXX%% - add final text here - XXX
+
+**IMPORTANT NOTE**: See [contact.html](../contact.html) for up to date contact details
+as well as details on how to provide fixes to any of the entries.
+See also the [IOCCC FAQ](../faq.html) for additional information on the IOCCC.
+
+<!--
+
+    Copyright © 1984-%%YEAR%% 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/
+
+-->