improve leading comments in some bin tools

Helped clarify how some tools are indirectly invoked by improving
some of the leading comments in selected bin tools.

Changed `bin/output-index-author.sh` VERSION from "1.5 2024-03-04"
to "1.5.1 2024-03-19".

Changed `bin/output-index-inventory.sh` VERSION from "1.2.1 2024-03-18"
to "1.2.2 2024-03-19".

Changed `bin/output-year-index.sh` VERSION from "1.1 2024-02-27"
to "1.1.1 2024-03-19".

Changed `bin/pandoc-wrapper.sh` VERSION from "1.5.1 2024-03-18"
to "1.5.2 2024-03-19".

Changed `bin/status2html.sh` VERSION from "1.1 2024-03-10"
to "1.1.1 2024-03-19".

Changed `bin/subst.entry-index.sh` VERSION from "1.3 2024-03-02"
to "1.3.1 2024-03-19".

Changed `bin/subst.year-index.sh` VERSION from "1.1 2024-03-02"
to "1.1.1 2024-03-19".

Ran `make www` to check tools and `1984/decot/index.html` was updated.

1984/decot/index.html

@@ -159,8 +159,9 @@ can use this version.</p>
 <h3 id="alternate-use">Alternate use:</h3>
 <div class="sourceCode" id="cb5"><pre class="sourceCode sh"><code class="sourceCode bash"><span id="cb5-1"><a href="#cb5-1" aria-hidden="true" tabindex="-1"></a><span class="ex">./decot.alt</span></span></code></pre></div>
 <h2 id="judges-remarks">Judges’ remarks:</h2>
-<p>This program prints out a string of garbage.</p>
-<p>The judges also offer this one comment: understand remarks!</p>
+<p>This program prints out what looks like a fragment of C code.</p>
+<p>Is this a <strong>bug</strong> or is this a <strong>feature</strong>? To help choose
+the judges offer this one comment: understand remarks!</p>
 <h3 id="historical-remarks">Historical remarks:</h3>
 <p>Some new (in 1984) compilers disliked line 15 of the original source, so we
 changed it from:</p>

bin/output-index-author.sh

@@ -3,10 +3,22 @@
 # output-index-author.sh - output author(s) related HTML for an entry's index.html page
 #
 # This tool is intended to be used as a "before tool" during HTML phase number 20.
+# In particular, lines in the inc/md2html.cfg configuration file of the form:
+#
+#	-b
+#	bin/output-index-author.sh
+#
+# will cause tools such as bin/md2html.sh to execute this code.
 #
-# This tool is intended to be invoked by a tool such as "readme2index.sh".
 # The final arg will be in YYYY/dir form, and will be called from
 # the topdir directory under which the YYYY/dir entry directory must be found.
+# Tools such as bin/readme2index.sh, when run via bin/all-run.sh:
+#
+#	bin/all-run.sh -v 3 bin/readme2index.sh -v 1
+#
+# will supply the YYYY/dir arg.  This may be more easily done via make:
+#
+#	make entry_index
 #
 # Copyright (c) 2023,2024 by Landon Curt Noll.  All Rights Reserved.
 #
@@ -89,7 +101,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.5 2024-03-04"
+export VERSION="1.5.1 2024-03-19"
 NAME=$(basename "$0")
 export NAME
 export V_FLAG=0

bin/output-index-inventory.sh

@@ -2,11 +2,23 @@
 #
 # output-index-inventory.sh - output the inventory in HTML form for an entry's index.html page
 #
-# This tool is intended to be used as a "before tool" during HTML phase number 22.
+# This tool is intended to be used as an "after tool" during HTML phase number 22.
+# In particular, lines in the inc/md2html.cfg configuration file of the form:
+#
+#	-a
+#	bin/output-index-inventory.sh
+#
+# will cause tools such as bin/md2html.sh to execute this code.
 #
-# This tool is intended to be invoked by a tool such as "readme2index.sh".
 # The final arg will be in YYYY/dir form, and will be called from
 # the topdir directory under which the YYYY/dir entry directory must be found.
+# Tools such as bin/readme2index.sh, when run via bin/all-run.sh:
+#
+#	bin/all-run.sh -v 3 bin/readme2index.sh -v 1
+#
+# will supply the YYYY/dir arg.  This may be more easily done via make:
+#
+#	make entry_index
 #
 # Copyright (c) 2024 by Landon Curt Noll.  All Rights Reserved.
 #
@@ -89,7 +101,7 @@ shopt -s globstar	# enable '**' to match all files and zero or more directories
 
 # set variables referenced in the usage message
 #
-export VERSION="1.2.1 2024-03-18"
+export VERSION="1.2.2 2024-03-19"
 NAME=$(basename "$0")
 export NAME
 export V_FLAG=0

bin/output-year-index.sh

@@ -9,6 +9,24 @@
 #
 #	bin/output-year-index.sh
 #
+# This tool is intended to be used as an "after tool" during HTML phase number 22.
+# In particular, lines in the inc/md2html.cfg configuration file of the form:
+#
+#	-a
+#	bin/output-year-index.sh
+#
+# will cause tools such as bin/md2html.sh to execute this code.
+#
+# The final arg will be in YYYY form, and will be called from
+# the topdir directory under which the YYYY directory must be found.
+# Tools such as bin/gen-year-index.sh, when run via bin/all-run.sh:
+#
+#	bin/all-years.sh -v 1 bin/gen-year-index.sh -v 1
+#
+# will supply the YYYY arg.  This may be more easily done via make:
+#
+#	make gen_year_index
+#
 # Copyright (c) 2024 by Landon Curt Noll.  All Rights Reserved.
 #
 # Permission to use, copy, modify, and distribute this software and
@@ -90,7 +108,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.1 2024-02-27"
+export VERSION="1.1.1 2024-03-19"
 NAME=$(basename "$0")
 export NAME
 export V_FLAG=0

bin/pandoc-wrapper.sh

@@ -2,10 +2,19 @@
 #
 # pandoc-wrapper.sh - wrapper tool to run pandoc
 #
-# This tool is intended to be used as a 'pandoc wrapper tool' during HTML phase number 21.
+# This tool is intended to be used as a 'pandoc wrapper tool' by bin/md2html.sh
+# during HTML phase number 21.
 #
-# This tool is intended to be invoked by a tool such as 'readme2index.sh"
-# and as such, the leading options will include "-p pandoc_wrapper" and -P "optstr",
+# This tool is also run by other bin tools such as:
+#
+#	bin/output-index-author.sh
+#	bin/output-index-inventory.sh
+#	bin/output-year-index.sh
+#	bin/quick-readme2index.sh
+#	bin/readme2index.sh
+#	bin/status2html.sh.
+#
+# The leading options will include "-p pandoc_wrapper" and -P "optstr",
 # the final arg will be in YYYY/dir form, and will be called from
 # the topdir directory under which the YYYY/dir entry directory must be found.
 #
@@ -90,7 +99,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.5.1 2024-03-18"
+export VERSION="1.5.2 2024-03-19"
 NAME=$(basename "$0")
 export NAME
 export V_FLAG=0

bin/status2html.sh

@@ -3,8 +3,20 @@
 # status2html.sh - output status.json HTML for the status.html page
 #
 # This tool is intended to be used as a "before tool" during HTML phase number 20.
+# In particular, lines in the inc/md2html.cfg configuration file of the form:
 #
-# This tool is intended to be invoked by a tool such as "bin/gen-status.sh"
+#	-b
+#	bin/status2html.sh
+#
+# will cause tools such as bin/gen-status.sh to execute this code.
+#
+# The usual way to run bin/gen-status.sh is via:
+#
+#	bin/gen-status.sh -v 1
+#
+# This may be more easily done via make:
+#
+#	make gen_status
 #
 # Copyright (c) 2024 by Landon Curt Noll.  All Rights Reserved.
 #
@@ -87,7 +99,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.1 2024-03-10"
+export VERSION="1.1.1 2024-03-19"
 NAME=$(basename "$0")
 export NAME
 export V_FLAG=0

bin/subst.entry-index.sh

@@ -2,12 +2,23 @@
 #
 # subst.entry-index.sh - print substitutions for a entry's index.html
 #
-# This tool is used in conjunction with the inc/md2html.cfg configuration
-# file, and the tools that use that use that configuration file such as "bin/md2html.sh".
+# This tool is intended to be used as a "output tool" during getopt phases 1 and 3.
+# In particular, lines in the inc/md2html.cfg configuration file of the form:
 #
-# It is usually invoked by:
+#	-o
+#	bin/subst.entry-index.sh
 #
-#	-o bin/subst.entry-index.sh
+# will cause tools such as bin/md2html.sh to execute this code.
+#
+# The final arg will be in YYYY/dir form, and will be called from
+# the topdir directory under which the YYYY/dir entry directory must be found.
+# Tools such as bin/readme2index.sh, when run via bin/all-run.sh:
+#
+#	bin/all-run.sh -v 3 bin/readme2index.sh -v 1
+#
+# will supply the YYYY/dir arg.  This may be more easily done via make:
+#
+#	make entry_index
 #
 # IMPORTANT: Each command line option / argument MUST be printed on a separate line!
 #
@@ -92,7 +103,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.3 2024-03-02"
+export VERSION="1.3.1 2024-03-19"
 NAME=$(basename "$0")
 export NAME
 export V_FLAG=0

bin/subst.year-index.sh

@@ -2,12 +2,23 @@
 #
 # subst.year-index.sh - print substitutions for a year's index.html
 #
-# This tool is used in conjunction with the inc/md2html.cfg configuration
-# file, and the tools that use that use that configuration file such as "bin/md2html.sh".
+# This tool is intended to be used as a "output tool" during getopt phases 1 and 3.
+# In particular, lines in the inc/md2html.cfg configuration file of the form:
 #
-# It is usually invoked by:
+#	-o
+#	bin/subst.year-index.sh
 #
-#	-o bin/subst.year-index.sh
+# will cause tools such as gen-year-index.sh to execute this code.
+#
+# The final arg will be in YYYY form, and will be called from
+# the topdir directory under which the YYYY directory must be found.
+# Tools such as bin/gen-year-index.sh, when run via bin/all-run.sh:
+#
+#	bin/all-years.sh -v 1 bin/gen-year-index.sh -v 1
+#
+# will supply the YYYY arg.  This may be more easily done via make:
+#
+#	make gen_year_index
 #
 # IMPORTANT: Each command line option / argument MUST be printed on a separate line!
 #
@@ -92,7 +103,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.1 2024-03-02"
+export VERSION="1.1.1 2024-03-19"
 NAME=$(basename "$0")
 export NAME
 export V_FLAG=0