Merge pull request #2749 from xexyl/entities

2024-11-07 14:04:17 -08:00
commit 41ccb8c884
@@ -406,7 +406,7 @@
  </a>
  <h1>The International Obfuscated C Code Contest</h1>
  <h2>1986/bright - Most useful obfuscation</h2>
-  <h3>hex dump with cpp compressed that uses lots of << for constants</h3>
+  <h3>hex dump with cpp compressed that uses lots of &lt;&lt; for constants</h3>
 </div>

 <!-- END: this line ends content from: inc/header.default.html -->
@@ -406,7 +406,7 @@
  </a>
  <h1>The International Obfuscated C Code Contest</h1>
  <h2>1987/wall - Most useful obfuscation</h2>
-  <h3>roman numeral -> decimal and vice versa conversion</h3>
+  <h3>roman numeral -&gt; decimal and vice versa conversion</h3>
 </div>

 <!-- END: this line ends content from: inc/header.default.html -->
@@ -406,7 +406,7 @@
  </a>
  <h1>The International Obfuscated C Code Contest</h1>
  <h2>1988/robison - Best abuse of C constructs</h2>
-  <h3>print e in any base using only -- >= and while()</h3>
+  <h3>print e in any base using only -- &gt;&equals; and while()</h3>
 </div>

 <!-- END: this line ends content from: inc/header.default.html -->
@@ -406,7 +406,7 @@
  </a>
  <h1>The International Obfuscated C Code Contest</h1>
  <h2>1990/theorem - Best of Show</h2>
-  <h3>numerically solves the equation y'=f(x y)</h3>
+  <h3>numerically solves the equation y'&equals;f(x y)</h3>
 </div>

 <!-- END: this line ends content from: inc/header.default.html -->
@@ -406,7 +406,7 @@
  </a>
  <h1>The International Obfuscated C Code Contest</h1>
  <h2>1992/albert - Most useful program</h2>
-  <h3>factors multi-precision numbers with factors < MAX_LONG</h3>
+  <h3>factors multi-precision numbers with factors &lt; MAX_LONG</h3>
 </div>

 <!-- END: this line ends content from: inc/header.default.html -->
@@ -817,8 +817,8 @@ are not recognised when written as <code>-rs</code> in prose).</p>
 <li><a href="https://github.com/ioccc-src/temp-test-ioccc/blob/master/2018/burton2/c++98">c++98</a> - reserved words for C++98 standard</li>
 <li><a href="https://github.com/ioccc-src/temp-test-ioccc/blob/master/2018/burton2/c99">c99</a> - reserved words for C99 standard</li>
 <li><a href="https://github.com/ioccc-src/temp-test-ioccc/blob/master/2018/burton2/java8">java8</a> - reserved words for Java v8</li>
-<li><a href="https://github.com/ioccc-src/temp-test-ioccc/blob/master/2018/burton2/kandr2">kandr2</a> - reserved words for K&amp;R2 C</li>
-<li><a href="https://github.com/ioccc-src/temp-test-ioccc/blob/master/2018/burton2/kandr">kandr</a> - reserved words for K&amp;R C</li>
+<li><a href="https://github.com/ioccc-src/temp-test-ioccc/blob/master/2018/burton2/kandr2">kandr2</a> - reserved words for K&amp;amp;R2 C</li>
+<li><a href="https://github.com/ioccc-src/temp-test-ioccc/blob/master/2018/burton2/kandr">kandr</a> - reserved words for K&amp;amp;R C</li>
 <li><a href="https://github.com/ioccc-src/temp-test-ioccc/blob/master/2018/burton2/patch">patch</a> - author supplied patch to fix iocccsize.c source</li>
 <li><a href="https://github.com/ioccc-src/temp-test-ioccc/blob/master/2018/burton2/results">results</a> - results without -k</li>
 <li><a href="https://github.com/ioccc-src/temp-test-ioccc/blob/master/2018/burton2/runtest.sh">runtest.sh</a> - test suite</li>
@@ -14,10 +14,12 @@ files and other content from the [IOCCC GitHub
 repo](https://github.com/ioccc-src/temp-test-ioccc).


-## [bin/](index.html) tools
+## [bin/](index.html) tools options
+
+With the exception of the `awk(1)` and `sed(1)` scripts, all the tools in this
+directory support a number of options that can be used to get help, diagnose
+problems, see progress etc. These options are described below.

-All tools in this directory support a number of options that can be used to get
-help, diagnose problems, see progress etc. These options are as follows:

 ### Get help / usage string of a tool

@@ -35,9 +37,9 @@ from the root directory (of the repo/website), you would do:

 ### Set verbosity level of a tool

-If you want verbosity, say for debugging purposes or to see what is
-going on more, you should use the `-v level` option. For instance if you wish to
-see what is going on with the
+If you want verbosity, say for debugging purposes or to see what is going on
+more (than the default), you should use the `-v level` option. For instance if
+you wish to see what is going on with the
 [quick-readme2index.sh](index.html#quick-readme2index) tool, you might do:


@@ -412,6 +414,28 @@ Usage:
 In this case the command will list all the files of the
 [2020/ferguson1](../2020/ferguson1/index.html) winning entry.

+<div id="html-sed">
+### [html.sed](%%REPO_URL%%/bin/html.sed)
+</div>
+
+Translates certain characters in their corresponding HTML entities. For example
+`<` is converted to `&lt;` and `>` is converted to `&gt;`. This is important to
+satisfy html lints.
+
+This script is used in [md2html.sh](#md2html) via
+[output-index-inventory.sh](#output-index-inventory) and
+[subst.entry-index.sh](#subst-entry-index).
+
+Usage:
+
+``` <!---sh-->
+    cmd | sed -f bin/html.sed
+
+    sed -f bin/html.sed file > output
+
+    sed -i -f bin/html.sed file
+```
+

 <div id="find-missing-links">
 ### [find-missing-links.sh](%%REPO_URL%%/bin/find-missing-links.sh)
@@ -1,6 +1,6 @@
 #!/usr/bin/env sed
 #
-# bin/html.sed - translate certain characters to HTML & entities
+# html.sed - translate certain characters to HTML & entities
 #
 # This script was written in 2024 November by:
 #
@@ -11,9 +11,13 @@
 # "Because sometimes even the IOCCC Judges need some help." :-)
 #
 # This script will take certain characters, for instance '<', and convert them
-# to their respective html entity, for instance '&lt;', so that html lints do
+# to their respective HTML entity, for instance '&lt;', so that HTML lints do
 # not complain.
 #
+# For a list of the other HTML entities, should others be needed, see:
+#
+#       https://www.w3schools.com/html/html_entities.asp
+#
 # usage:
 #
 #	cmd | sed -f bin/html.sed
@@ -22,11 +26,14 @@
 #
 #	sed -i -f bin/html.sed file
 #
-# VERSION="1.0 2024-11-04"
+# VERSION="1.1 2024-11-07"

 # IMPORTANT NOTE: the '&amp;' substitution MUST come first! This is because the
 # other substitutions have '&'s in them and if the '&amp;' came after it would
 # corrupt the '&'s in the string.
-s/&/\&amp;/g
-s/</\&lt;/g
-s/>/\&gt;/g
+s/&/\\\&amp;/g
+s/</\\\&lt;/g
+s/>/\\\&gt;/g
+s/|/\\\&verbar;/g
+s/=/\\\&equals;/g
+s/%/\\\&percnt;/g
@@ -436,9 +436,10 @@ content, for the <a href="https://www.ioccc.org">official IOCCC website</a>.</p>
 fragments from the <a href="../inc/index.html">inc directory</a> as well as various JSON
 files and other content from the <a href="https://github.com/ioccc-src/temp-test-ioccc">IOCCC GitHub
 repo</a>.</p>
-<h2 id="bin-tools"><a href="index.html">bin/</a> tools</h2>
-<p>All tools in this directory support a number of options that can be used to get
-help, diagnose problems, see progress etc. These options are as follows:</p>
+<h2 id="bin-tools-options"><a href="index.html">bin/</a> tools options</h2>
+<p>With the exception of the <code>awk(1)</code> and <code>sed(1)</code> scripts, all the tools in this
+directory support a number of options that can be used to get help, diagnose
+problems, see progress etc. These options are described below.</p>
 <h3 id="get-help-usage-string-of-a-tool">Get help / usage string of a tool</h3>
 <p>If you need to remember the syntax of the tool or get certain notes about
 different options, you can use the <code>-h</code> option.</p>
@@ -446,9 +447,9 @@ different options, you can use the <code>-h</code> option.</p>
 from the root directory (of the repo/website), you would do:</p>
 <pre><code>    bin/all-run.sh -h</code></pre>
 <h3 id="set-verbosity-level-of-a-tool">Set verbosity level of a tool</h3>
-<p>If you want verbosity, say for debugging purposes or to see what is
-going on more, you should use the <code>-v level</code> option. For instance if you wish to
-see what is going on with the
+<p>If you want verbosity, say for debugging purposes or to see what is going on
+more (than the default), you should use the <code>-v level</code> option. For instance if
+you wish to see what is going on with the
 <a href="index.html#quick-readme2index">quick-readme2index.sh</a> tool, you might do:</p>
 <pre><code>    bin/quick-readme2index.sh -v 3</code></pre>
 <p>to set the verbosity level to <code>3</code>. The default for verbosity is <code>0</code>, no
@@ -681,6 +682,21 @@ from the <code>TOPDIR</code>.</p>
 <pre><code>    awk -f bin/filelist.entry.json.awk 2020/ferguson1/.entry.json</code></pre>
 <p>In this case the command will list all the files of the
 <a href="../2020/ferguson1/index.html">2020/ferguson1</a> winning entry.</p>
+<div id="html-sed">
+<h3 id="html.sed"><a href="https://github.com/ioccc-src/temp-test-ioccc/blob/master/bin/html.sed">html.sed</a></h3>
+</div>
+<p>Translates certain characters in their corresponding HTML entities. For example
+<code>&lt;</code> is converted to <code>&amp;lt;</code> and <code>&gt;</code> is converted to <code>&amp;gt;</code>. This is important to
+satisfy html lints.</p>
+<p>This script is used in <a href="#md2html">md2html.sh</a> via
+<a href="#output-index-inventory">output-index-inventory.sh</a> and
+<a href="#subst-entry-index">subst.entry-index.sh</a>.</p>
+<p>Usage:</p>
+<pre><code>    cmd | sed -f bin/html.sed
+
+    sed -f bin/html.sed file &gt; output
+
+    sed -i -f bin/html.sed file</code></pre>
 <div id="find-missing-links">
 <h3 id="find-missing-links.sh"><a href="https://github.com/ioccc-src/temp-test-ioccc/blob/master/bin/find-missing-links.sh">find-missing-links.sh</a></h3>
 </div>
@@ -3,6 +3,18 @@
 #
 # md2html.sh - convert markdown into an IOCCC HTML file via config file
 #
+# This script was written in 2024 by:
+#
+#   chongo (Landon Curt Noll, http://www.isthe.com/chongo/index.html) /\oo/\
+#
+# with useful improvements by:
+#
+#	@xexyl
+#	https://xexyl.net		Cody Boone Ferguson
+#	https://ioccc.xexyl.net
+#
+# "Because sometimes even the IOCCC Judges need some help." :-)
+#
 # Convert a markdown file into a HTML file for the IOCCC website,
 # using the bin/md2html.cfg configuration file.  Conversion from
 # markdown to HTML is performed via the 'pandoc wrapper tool'.
@@ -146,7 +158,7 @@ shopt -s lastpipe	# run last command of a pipeline not executed in the backgroun

 # set variables referenced in the usage message
 #
-export VERSION="1.7 2024-09-27"
+export VERSION="1.8 2024-11-07"
 NAME=$(basename "$0")
 export NAME
 export V_FLAG=0
@@ -216,11 +228,12 @@ export USAGE="usage: $0 [-h] [-v level] [-V] [-d topdir] [-D docroot/] [-n] [-N]
 	-a tool		run 'after tool' during HTML phase number 20 (def: do not output after pandoc wrapper tool)
 	-a .		skip HTML phase number 22 (def: do nothing during HTML phase number 22)

-	-s token=value	substitute %%token%% with value except in HTML phase numbers 20-29 (def: do not substitute any tokens)
-			NOTE: The 'token' string may not contain a ; (semicolon), a = (equal), or a % (percent).
-			NOTE: The 'value' string may not contain a ; (semicolon), nor & (ampersand).
-			NOTE: A later '-s token=value' will override an earlier '-s token=value' for the same 'token'.
-			NOTE: Multiple '-s token=value' are cumulative for the unique set of 'token's.
+        -s token=value  substitute %%token%% with value except in HTML phase numbers 20-29 (def: do not substitute any tokens)
+                        NOTE: The 'token' string may not contain an = (equal), | (pipe) or a % (percent) symbol.
+                        NOTE: The 'value' string may not contain a | (pipe) symbol
+                        NOTE: A later '-s token=value' will override an earlier '-s token=value' for the same 'token'.
+                        NOTE: Multiple '-s token=value' are cumulative for the unique set of 'token's.
+
 	-S		Failure to replace a %%token%% is not an error (def: exit non-zero for non-substituted tokens)

 	-o tool		use 'output tool' to generate option lines (def: do not)
@@ -554,7 +567,7 @@ function parse_command_line
 	    fi
 	    ;;
 	s) # parse: -s token=value
-	    case "$OPTARG" in
+            case "$OPTARG" in
 	    *=*) # parse name=value
 		NAME=${OPTARG%%=*}
 		VALUE=${OPTARG#*=}
@@ -567,14 +580,14 @@ function parse_command_line
 	    esac
 	    #
 	    case "$NAME" in
-	    *\;*)
-		echo "$0: ERROR: in -s token=value, the token may not contain a ; (semicolon) character: $NAME" 1>&2
+	    *=*)
+		echo "$0: ERROR: in -s token=value, the token may not contain an = (equal) character: $NAME" 1>&2
 		echo 1>&2
 		echo "$USAGE" 1>&2
 		exit 3
 		;;
-	    *=*)
-		echo "$0: ERROR: in -s token=value, the token may not contain an = (equal) character: $NAME" 1>&2
+	    *\|*)
+		echo "$0: ERROR: in -s token=value, the token may not contain a | (pipe) character: $NAME" 1>&2
 		echo 1>&2
 		echo "$USAGE" 1>&2
 		exit 3
@@ -589,14 +602,8 @@ function parse_command_line
 	    esac
 	    #
 	    case "$VALUE" in
-	    *\;*)
-		echo "$0: ERROR: in -s token=value, the value may not contain a ; (semicolon) character: $NAME" 1>&2
-		echo 1>&2
-		echo "$USAGE" 1>&2
-		exit 3
-		;;
-	    *\&*)
-		echo "$0: ERROR: in -s token=value, the value may not contain an & (ampersand) character: $NAME" 1>&2
+	    *\|*)
+		echo "$0: ERROR: in -s token=value, the value may not contain a | (pipe) character: $NAME" 1>&2
 		echo 1>&2
 		echo "$USAGE" 1>&2
 		exit 3
@@ -916,7 +923,7 @@ function append_html_phase
    # parse args
    #
    if [[ $# -ne 6 ]]; then
-	echo "$0: ERROR: append_html_phase requires 2 args, found: $#" 1>&2
+	echo "$0: ERROR: append_html_phase requires 6 args, found: $#" 1>&2
 	# We have to return non-zero but we don't have the args to know STARTING_EXIT_CODE.
 	# We might as well use 7 since that is an HTML phase exit code
 	return 7
@@ -1600,7 +1607,7 @@ fi
 #
 if [[ $V_FLAG -ge 7 ]]; then
    for n in "${!TOKEN[@]}"; do
-	echo "$0: debug[7]: -s token replacement: sed -e s;%%$n%%;${TOKEN[$n]};g" 1>&2
+	echo "$0: debug[7]: -s token replacement: sed -e s|%%$n%%|${TOKEN[$n]}|g" 1>&2
    done
 fi

@@ -1644,7 +1651,7 @@ if [[ -z $NOOP ]]; then
    # load the sed script with sed commands from any "-s token=value"
    #
    for n in "${!TOKEN[@]}"; do
-	echo "s;%%$n%%;${TOKEN[$n]};g" >> "$TMP_SED_SCRIPT"
+	echo "s|%%$n%%|${TOKEN[$n]}|g" >> "$TMP_SED_SCRIPT"
    done
    if [[ $V_FLAG -ge 5 ]]; then
 	echo "$0: debug[5]: temporary sed script starts below: $TMP_SED_SCRIPT" 1>&2
@@ -1655,7 +1662,7 @@ elif [[ $V_FLAG -ge 3 ]]; then
    echo "$0: debug[3]: because of -n, temporary sed script is not formed: $TMP_SED_SCRIPT" 1>&2
    echo "$0: debug[3]: the temporary sed script that would have been written starts below: $TMP_SED_SCRIPT" 1>&2
    for n in "${!TOKEN[@]}"; do
-	echo "s;%%$n%%;${TOKEN[$n]};g" 1>&2
+	echo "s|%%$n%%|${TOKEN[$n]}|g" 1>&2
    done
    echo "$0: debug[3]: the temporary sed script that would have been written ends above: $TMP_SED_SCRIPT" 1>&2
 fi
@@ -1799,7 +1806,7 @@ if [[ -z $NOOP ]]; then
    sed -E -e 's/^```[[:space:]]<!---[^-][^-]*-->/```/' -f "$TMP_SED_SCRIPT" "$INPUT_MD" >> "$TMP_STRIPPED_MD"
    status="$?"
    if [[ $status -ne 0 ]]; then
-	echo "$0: ERROR: token substation and strip code block command language from $INPUT_MD into file:" \
+	echo "$0: ERROR: token substitution and strip code block command language from $INPUT_MD into file:" \
 	     "$TMP_INPUT_MD failed, error code: $status" 1>&2
 	exit 25
    fi
@@ -2,6 +2,18 @@
 #
 # subst.entry-index.sh - print substitutions for a entry's index.html
 #
+# This script was written in 2024 by:
+#
+#   chongo (Landon Curt Noll, http://www.isthe.com/chongo/index.html) /\oo/\
+#
+# with useful improvements by:
+#
+#	@xexyl
+#	https://xexyl.net		Cody Boone Ferguson
+#	https://ioccc.xexyl.net
+#
+# "Because sometimes even the IOCCC Judges need some help." :-)
+#
 # This tool is intended to be used as a "output tool" during getopt phases 1 and 3.
 # In particular, lines in the bin/md2html.cfg configuration file of the form:
 #
@@ -200,6 +212,9 @@ Exit codes:

 $NAME version: $VERSION"

+# We need this here as the functions refer to it. We will check that it exists
+# before using it, however.
+export HTML_SED="$BIN_DIR/html.sed"

 # Write the award name to standard output (stdout)
 #
@@ -239,12 +254,12 @@ function output_award
    #
    PATTERN='$..award'
    if [[ $V_FLAG -ge 5 ]]; then
-	echo  "$0: debug[5]: about to run: $JVAL_WRAPPER -b -q -- $ENTRY_JSON_PATH '$PATTERN' | $JSTRENCODE -N -" 1>&2
+	echo  "$0: debug[5]: about to run: $JVAL_WRAPPER -b -q -- $ENTRY_JSON_PATH '$PATTERN' | $JSTRENCODE -N - | sed -f $HTML_SED" 1>&2
    fi
-    "$JVAL_WRAPPER" -b -q "$ENTRY_JSON_PATH" "$PATTERN" | "$JSTRENCODE" -N -
+    "$JVAL_WRAPPER" -b -q "$ENTRY_JSON_PATH" "$PATTERN" | "$JSTRENCODE" -N - | sed -f "$HTML_SED"
    status_codes=("${PIPESTATUS[@]}")
    if [[ ${status_codes[*]} =~ [1-9] ]]; then
-	echo "$0: ERROR: in output_award: $JVAL_WRAPPER -b -q -- $ENTRY_JSON_PATH '$PATTERN' | $JSTRENCODE -N - failed," \
+	echo "$0: ERROR: in output_award: $JVAL_WRAPPER -b -q -- $ENTRY_JSON_PATH '$PATTERN' | $JSTRENCODE -N - | sed -f $HTML_SED failed," \
 	     "error codes: ${status_codes[*]}" 1>&2
 	return 5
    fi
@@ -290,12 +305,12 @@ function output_abstract
    #
    PATTERN='$..abstract'
    if [[ $V_FLAG -ge 5 ]]; then
-	echo  "$0: debug[5]: about to run: $JVAL_WRAPPER -b -q -- $ENTRY_JSON_PATH '$PATTERN' | $JSTRENCODE -N -" 1>&2
+	echo  "$0: debug[5]: about to run: $JVAL_WRAPPER -b -q -- $ENTRY_JSON_PATH '$PATTERN' | $JSTRENCODE -N - | sed -f $HTML_SED" 1>&2
    fi
-    "$JVAL_WRAPPER" -b -q "$ENTRY_JSON_PATH" "$PATTERN" | "$JSTRENCODE" -N -
+    "$JVAL_WRAPPER" -b -q "$ENTRY_JSON_PATH" "$PATTERN" | "$JSTRENCODE" -N - | sed -f "$HTML_SED"
    status_codes=("${PIPESTATUS[@]}")
    if [[ ${status_codes[*]} =~ [1-9] ]]; then
-	echo "$0: ERROR: in output_abstract: $JVAL_WRAPPER -b -q -- $ENTRY_JSON_PATH '$PATTERN | $JSTRENCODE -N - failed," \
+	echo "$0: ERROR: in output_abstract: $JVAL_WRAPPER -b -q -- $ENTRY_JSON_PATH '$PATTERN | $JSTRENCODE -N - | sed -f $HTML_SED failed," \
 	     "error codes: ${status_codes[*]}" 1>&2
 	return 5
    fi
@@ -492,6 +507,23 @@ if [[ ! -r $ENTRY_NAVBAR_AWK ]]; then
    exit 5
 fi

+# verify we have our sed script
+#
+if [[ ! -e $HTML_SED ]]; then
+    echo "$0: ERROR: bin/html.sed does not exist: $HTML_SED" 1>&2
+    exit 5
+fi
+if [[ ! -f $HTML_SED ]]; then
+    echo "$0: ERROR: bin/html.sed is not a file: $HTML_SED" 1>&2
+    exit 5
+fi
+if [[ ! -r $HTML_SED ]]; then
+    echo "$0: ERROR: bin/html.sed is not a readable file: $HTML_SED" 1>&2
+    exit 5
+fi
+
+
+

 # verify that ENTRY_PATH is a entry directory
 #
@@ -614,6 +646,7 @@ if [[ $V_FLAG -ge 3 ]]; then
    echo "$0: debug[3]: INC_DIR=$INC_DIR" 1>&2
    echo "$0: debug[3]: BIN_PATH=$BIN_PATH" 1>&2
    echo "$0: debug[3]: BIN_DIR=$BIN_DIR" 1>&2
+    echo "$0: debug[3]: HTML_SED=$HTML_SED" 1>&2
    echo "$0: debug[3]: JVAL_WRAPPER=$JVAL_WRAPPER" 1>&2
    echo "$0: debug[3]: ENTRY_JSON=$ENTRY_JSON" 1>&2
    echo "$0: debug[3]: YEAR_DIR=$YEAR_DIR" 1>&2