From 467ad5fa9f19f7159c8c5be1efabaecd94f638a7 Mon Sep 17 00:00:00 2001 From: Landon Curt Noll Date: Tue, 19 Mar 2024 17:24:00 -0700 Subject: [PATCH] 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 | 5 +++-- bin/output-index-author.sh | 16 ++++++++++++++-- bin/output-index-inventory.sh | 18 +++++++++++++++--- bin/output-year-index.sh | 20 +++++++++++++++++++- bin/pandoc-wrapper.sh | 17 +++++++++++++---- bin/status2html.sh | 16 ++++++++++++++-- bin/subst.entry-index.sh | 21 ++++++++++++++++----- bin/subst.year-index.sh | 21 ++++++++++++++++----- 8 files changed, 110 insertions(+), 24 deletions(-) diff --git a/1984/decot/index.html b/1984/decot/index.html index 6e0e65dc6..54d115792 100644 --- a/1984/decot/index.html +++ b/1984/decot/index.html @@ -159,8 +159,9 @@ can use this version.

Alternate use:

./decot.alt

Judges’ remarks:

-

This program prints out a string of garbage.

-

The judges also offer this one comment: understand remarks!

+

This program prints out what looks like a fragment of C code.

+

Is this a bug or is this a feature? To help choose +the judges offer this one comment: understand remarks!

Historical remarks:

Some new (in 1984) compilers disliked line 15 of the original source, so we changed it from:

diff --git a/bin/output-index-author.sh b/bin/output-index-author.sh index 15d689ab6..b04356706 100755 --- a/bin/output-index-author.sh +++ b/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 diff --git a/bin/output-index-inventory.sh b/bin/output-index-inventory.sh index 2a31506d9..d1a5b04ed 100755 --- a/bin/output-index-inventory.sh +++ b/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 diff --git a/bin/output-year-index.sh b/bin/output-year-index.sh index 4e5143dfc..33798b164 100755 --- a/bin/output-year-index.sh +++ b/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 diff --git a/bin/pandoc-wrapper.sh b/bin/pandoc-wrapper.sh index 131fa4159..078d51989 100755 --- a/bin/pandoc-wrapper.sh +++ b/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 diff --git a/bin/status2html.sh b/bin/status2html.sh index ba546e6a1..5fa65e0ba 100755 --- a/bin/status2html.sh +++ b/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 diff --git a/bin/subst.entry-index.sh b/bin/subst.entry-index.sh index 94856647a..ea0fa5d35 100755 --- a/bin/subst.entry-index.sh +++ b/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 diff --git a/bin/subst.year-index.sh b/bin/subst.year-index.sh index 01382a5bb..98504e74d 100755 --- a/bin/subst.year-index.sh +++ b/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