From e4fa460de4e4a7ad4ec8c39cae84e84fca150c6b Mon Sep 17 00:00:00 2001
From: Cody Boone Ferguson <53008573+xexyl@users.noreply.github.com>
Date: Wed, 12 Jun 2024 14:29:39 -0700
Subject: [PATCH] Minor fixes in bin/README.md
A few typos were fixed.
One tool had the description reworded a bit to make it (hopefully) a bit
clearer.
A link was fixed but I am not sure if, since it's a script, it should
link to the GitHub repo or not, like with other markdown files. I
changed it to use the %%var%% that the bin/README.md file uses. This is
one reason links have not been checked. The other reason is I have not
gone through the entire file yet.
I notice some tools do not have example usage and those could be added
too.
There was an apparent typo in bin/find-missing-links.sh and this same
typo was fixed in bin/README.md. I am not sure exactly what was meant,
however, so it might need further modifications.
I have (the caveats above notwithstanding) gone up through
pandoc-wrapper.sh or just before it.
Regenerated bin/index.html.
---
bin/README.md | 50 +++++++++++++++++++--------------------
bin/find-missing-links.sh | 4 ++--
bin/index.html | 46 +++++++++++++++++------------------
3 files changed, 50 insertions(+), 50 deletions(-)
diff --git a/bin/README.md b/bin/README.md
index 656657b97..b529931cf 100644
--- a/bin/README.md
+++ b/bin/README.md
@@ -45,7 +45,7 @@ Or for example:
bin/all-years.sh -v 1 bin/chk-entry.sh
```
-We recommend that this tool be invoked via the top level `Makefile`:
+We recommend that this tool be invoked via the top level `Makefile` by:
```
make verify_entry_files
@@ -54,8 +54,8 @@ We recommend that this tool be invoked via the top level `Makefile`:
### [chk-entry.sh](%%DOCROOT_SLASH%%bin/chk-entry.sh)
-Check that files required by an entry match the entry's manifest as found in
-`.entry.json`.
+Check an entry directory to verify that both the files in its manifest
+(`.entry.json`) exist and that no other files exist.
For example:
@@ -66,7 +66,7 @@ For example:
### [filelist.entry.json.awk](%%DOCROOT_SLASH%%bin/filelist.entry.json.awk)
-Generate the list of files in the entry's manifest, `.entry.json`.
+Generate a list of files in an entry's manifest (the `.entry.json` file).
For example:
@@ -79,10 +79,10 @@ For example:
Find all markdown links to local files that do not exist.
-This tool does **NOT** check of a remote URL exists.
+This tool does **NOT** check that a remote URL exists.
This tool only checks on links to local files.
-This tool does **NOT** check links into a given place in a file.
+This tool does **NOT** check links in a given place in a file.
This tool only checks that local files linked by markdown exist.
This tool does **NOT** check HTML file links.
@@ -103,12 +103,12 @@ If this tool claims that a file is missing that does exist,
look for a malformed markdown line and/or use of markdown
that is **NOT** an IOCCC markdown best practice.
-See [IOCCC markdown best practices](../markdown.html) for more info.
+See [IOCCC markdown best practices](../markdown.html) for more details.
### [gen-authors.sh](%%DOCROOT_SLASH%%bin/gen-authors.sh)
-Generate the top level `/authors.html` page.
+Generate the top level `./authors.html` page.
Usage:
@@ -119,7 +119,7 @@ Usage:
### [gen-location.sh](%%DOCROOT_SLASH%%bin/gen-location.sh)
-Generate the top level `/location.html` page.
+Generate the top level `./location.html` page.
Usage:
@@ -130,8 +130,8 @@ Usage:
### [gen-other-html.sh](%%DOCROOT_SLASH%%bin/gen-other-html.sh)
-Generate entry HTML files (other than README.md to index.html) from markdown
-files.
+Generate entry HTML files (other than the README.md to index.html files) from
+markdown files.
Usage:
@@ -150,7 +150,7 @@ Usage:
bin/gen-sitemap.sh -v 1
```
-We recommend that this tool be invoked via the top level `Makefile`:
+We recommend that this tool be invoked via the top level `Makefile` by:
```
make gen_sitemap
@@ -160,9 +160,9 @@ We recommend that this tool be invoked via the top level `Makefile`:
### [gen-status.sh](%%DOCROOT_SLASH%%bin/gen-status.sh)
Generate `status.json` according to the modification dates of `status.json`
-and `news.html`.
+and `news.md`.
-Without argument, the `contest_status` is unchanged.
+Without an argument, the `contest_status` is unchanged.
Usage:
@@ -170,13 +170,13 @@ Usage:
bin/gen-status.sh -v 1
```
-To force the `contest_status` to be closed:
+To force the `contest_status` to be closed:
```
bin/gen-status.sh -v 1 closed
```
-To force the `contest_status` to be open:
+To force the `contest_status` to be open:
```
bin/gen-status.sh -v 1 open
@@ -188,7 +188,7 @@ To see other valid statuses:
bin/gen-status -h
```
-We recommend that this tool be invoked via the top level `Makefile`:
+We recommend that this tool be invoked via the top level `Makefile` by:
```
make gen_status
@@ -220,7 +220,7 @@ Examples of top level HTML pages built by this tool include:
- [news.html](../news.html)
- [thanks-for-help.html](../thanks-for-help.html)
-We recommend that this tool be invoked via the top level `Makefile`:
+We recommend that this tool be invoked via the top level `Makefile` by:
```
make gen_top_html
@@ -229,7 +229,7 @@ We recommend that this tool be invoked via the top level `Makefile`:
### [gen-year-index.sh](%%DOCROOT_SLASH%%bin/gen-year-index.sh)
-Generate an `index.html` page for an given IOCCC year.
+Generate an `index.html` page for a given IOCCC year.
Usage:
@@ -237,7 +237,7 @@ Usage:
bin/gen-year-index.sh -v 1 2020
```
-We recommend that this tool be invoked via the top level `Makefile`:
+We recommend that this tool be invoked via the top level `Makefile` by:
```
make gen_year_index
@@ -246,7 +246,7 @@ We recommend that this tool be invoked via the top level `Makefile`:
### [gen-years.sh](%%DOCROOT_SLASH%%bin/gen-years.sh)
-Generate the top level `/years.html` page.
+Generate the top level `./years.html` page.
Usage:
@@ -254,7 +254,7 @@ Usage:
bin/gen-years.sh -v 1
```
-We recommend that this tool be invoked via the top level `Makefile`:
+We recommend that this tool be invoked via the top level `Makefile` by:
```
make gen_years
@@ -268,7 +268,7 @@ markdown files (permanent markdown files or temporarily generated
markdown files) and HTML fragments from the [inc directory](../inc/index.html).
The [../inc/md2html.cfg](../inc/md2html.cfg) configuration file is
-used by [md2html.sh](md2html.sh) to drive the generation process.
+used by [md2html.sh](%%DOCROOT_SLASH%%bin/md2html.sh) to drive the generation process.
### [output-index-author.sh](%%DOCROOT_SLASH%%bin/output-index-author.sh)
@@ -284,12 +284,12 @@ Output the inventory in HTML form for an entry's index.html page.
### [output-year-index.sh](%%DOCROOT_SLASH%%bin/output-year-index.sh)
-Output markdown of wining entry links for a given year.
+Output markdown of a winning entry links for a given year.
### [pandoc-wrapper.sh](%%DOCROOT_SLASH%%bin/pandoc-wrapper.sh)
-Wrapper tool to run pandoc.
+Wrapper tool to run `pandoc(1)`.
### [quick-readme2index.sh](%%DOCROOT_SLASH%%bin/quick-readme2index.sh)
diff --git a/bin/find-missing-links.sh b/bin/find-missing-links.sh
index be14946b2..859907635 100755
--- a/bin/find-missing-links.sh
+++ b/bin/find-missing-links.sh
@@ -4,10 +4,10 @@
#
# Find all markdown links to local files that do not exist.
#
-# This tool does **NOT** check of a remote URL exists.
+# This tool does **NOT** check that a remote URL exists.
# This tool only checks on links to local files.
#
-# This tool does **NOT** check links into a given place in a file.
+# This tool does **NOT** check links in a given place in a file.
# This tool only checks that local files linked by markdown exist.
#
# This tool does **NOT** check HTML file links.
diff --git a/bin/index.html b/bin/index.html
index db7668b9c..935b59113 100644
--- a/bin/index.html
+++ b/bin/index.html
@@ -402,22 +402,22 @@ repo.
bin/all-years.sh -v 1 bin/gen-year-index.sh -v 1
Or for example:
bin/all-years.sh -v 1 bin/chk-entry.sh
-We recommend that this tool be invoked via the top level Makefile:
+We recommend that this tool be invoked via the top level Makefile by:
make verify_entry_files
-Check that files required by an entry match the entry’s manifest as found in
-.entry.json.
+Check an entry directory to verify that both the files in its manifest
+(.entry.json) exist and that no other files exist.
For example:
bin/chk-entry.sh 2020/ferguson1
-Generate the list of files in the entry’s manifest, .entry.json.
+Generate a list of files in an entry’s manifest (the .entry.json file).
For example:
awk -f bin/filelist.entry.json.awk 2020/ferguson1/.entry.json
Find all markdown links to local files that do not exist.
-This tool does NOT check of a remote URL exists.
+
This tool does NOT check that a remote URL exists.
This tool only checks on links to local files.
-This tool does NOT check links into a given place in a file.
+
This tool does NOT check links in a given place in a file.
This tool only checks that local files linked by markdown exist.
This tool does NOT check HTML file links.
This tool only checks markdown based links.
@@ -430,30 +430,30 @@ might generate an error about a file that does exist.
If this tool claims that a file is missing that does exist,
look for a malformed markdown line and/or use of markdown
that is NOT an IOCCC markdown best practice.
-See IOCCC markdown best practices for more info.
+See IOCCC markdown best practices for more details.
-Generate the top level /authors.html page.
+Generate the top level ./authors.html page.
Usage:
bin/gen-authors.sh -v 1
-Generate the top level /location.html page.
+Generate the top level ./location.html page.
Usage:
bin/gen-location.sh -v 1
-Generate entry HTML files (other than README.md to index.html) from markdown
-files.
+Generate entry HTML files (other than the README.md to index.html files) from
+markdown files.
Usage:
bin/gen-other-html.sh -v 1
Generate an XML sitemap for the IOCCC website.
Usage:
bin/gen-sitemap.sh -v 1
-We recommend that this tool be invoked via the top level Makefile:
+We recommend that this tool be invoked via the top level Makefile by:
make gen_sitemap
Generate status.json according to the modification dates of status.json
-and news.html.
-Without argument, the contest_status is unchanged.
+and news.md.
+Without an argument, the contest_status is unchanged.
Usage:
bin/gen-status.sh -v 1
To force the contest_status to be closed:
@@ -462,7 +462,7 @@ and news.html.
bin/gen-status.sh -v 1 open
To see other valid statuses:
bin/gen-status -h
-We recommend that this tool be invoked via the top level Makefile:
+We recommend that this tool be invoked via the top level Makefile by:
make gen_status
Generate a number of top level HTML pages for the IOCCC websites.
@@ -483,35 +483,35 @@ and news.html.
news.html
thanks-for-help.html
-We recommend that this tool be invoked via the top level Makefile:
+We recommend that this tool be invoked via the top level Makefile by:
make gen_top_html
-Generate an index.html page for an given IOCCC year.
+Generate an index.html page for a given IOCCC year.
Usage:
bin/gen-year-index.sh -v 1 2020
-We recommend that this tool be invoked via the top level Makefile:
+We recommend that this tool be invoked via the top level Makefile by:
make gen_year_index
-Generate the top level /years.html page.
+Generate the top level ./years.html page.
Usage:
bin/gen-years.sh -v 1
-We recommend that this tool be invoked via the top level Makefile:
+We recommend that this tool be invoked via the top level Makefile by:
make gen_years
This is the primary tool that forms IOCCC generated HTML content from
markdown files (permanent markdown files or temporarily generated
markdown files) and HTML fragments from the inc directory.
The ../inc/md2html.cfg configuration file is
-used by md2html.sh to drive the generation process.
+used by md2html.sh to drive the generation process.
Output author’s or authors’ related HTML details for an entry’s index.html
page.
Output the inventory in HTML form for an entry’s index.html page.
-Output markdown of wining entry links for a given year.
+Output markdown of a winning entry links for a given year.
-Wrapper tool to run pandoc.
+Wrapper tool to run pandoc(1).
Builds an entry’s index.html file if the entry directory
does not have a non-empty index.hmtl file, or if either