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.
2024-06-12 14:29:39 -07:00
1 parent b9aea412aa
commit e4fa460de4
@@ -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:

 ``` <!---sh-->
    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:

 ``` <!---sh-->
    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:

 ``` <!---sh-->
    bin/gen-status.sh -v 1 closed
 ```

-To force the  `contest_status` to be open:
+To force the `contest_status` to be open:

 ``` <!---sh-->
    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:

 ``` <!---sh-->
    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:

 ``` <!---sh-->
    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:

 ``` <!---sh-->
    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:

 ``` <!---sh-->
    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)
@@ -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.
@@ -402,22 +402,22 @@ repo</a>.</p>
 <pre><code>    bin/all-years.sh -v 1 bin/gen-year-index.sh -v 1</code></pre>
 <p>Or for example:</p>
 <pre><code>    bin/all-years.sh -v 1 bin/chk-entry.sh</code></pre>
-<p>We recommend that this tool be invoked via the top level <code>Makefile</code>:</p>
+<p>We recommend that this tool be invoked via the top level <code>Makefile</code> by:</p>
 <pre><code>    make verify_entry_files</code></pre>
 <h3 id="chk-entry.sh"><a href="../bin/chk-entry.sh">chk-entry.sh</a></h3>
-<p>Check that files required by an entry match the entry’s manifest as found in
-<code>.entry.json</code>.</p>
+<p>Check an entry directory to verify that both the files in its manifest
+(<code>.entry.json</code>) exist and that no other files exist.</p>
 <p>For example:</p>
 <pre><code>    bin/chk-entry.sh 2020/ferguson1</code></pre>
 <h3 id="filelist.entry.json.awk"><a href="../bin/filelist.entry.json.awk">filelist.entry.json.awk</a></h3>
-<p>Generate the list of files in the entry’s manifest, <code>.entry.json</code>.</p>
+<p>Generate a list of files in an entry’s manifest (the <code>.entry.json</code> file).</p>
 <p>For example:</p>
 <pre><code>    awk -f bin/filelist.entry.json.awk 2020/ferguson1/.entry.json</code></pre>
 <h3 id="find-missing-links.sh"><a href="../bin/find-missing-links.sh">find-missing-links.sh</a></h3>
 <p>Find all markdown links to local files that do not exist.</p>
-<p>This tool does <strong>NOT</strong> check of a remote URL exists.
+<p>This tool does <strong>NOT</strong> check that a remote URL exists.
 This tool only checks on links to local files.</p>
-<p>This tool does <strong>NOT</strong> check links into a given place in a file.
+<p>This tool does <strong>NOT</strong> check links in a given place in a file.
 This tool only checks that local files linked by markdown exist.</p>
 <p>This tool does <strong>NOT</strong> check HTML file links.
 This tool only checks markdown based links.</p>
@@ -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 <strong>NOT</strong> an IOCCC markdown best practice.</p>
-<p>See <a href="../markdown.html">IOCCC markdown best practices</a> for more info.</p>
+<p>See <a href="../markdown.html">IOCCC markdown best practices</a> for more details.</p>
 <h3 id="gen-authors.sh"><a href="../bin/gen-authors.sh">gen-authors.sh</a></h3>
-<p>Generate the top level <code>/authors.html</code> page.</p>
+<p>Generate the top level <code>./authors.html</code> page.</p>
 <p>Usage:</p>
 <pre><code>    bin/gen-authors.sh -v 1</code></pre>
 <h3 id="gen-location.sh"><a href="../bin/gen-location.sh">gen-location.sh</a></h3>
-<p>Generate the top level <code>/location.html</code> page.</p>
+<p>Generate the top level <code>./location.html</code> page.</p>
 <p>Usage:</p>
 <pre><code>    bin/gen-location.sh -v 1</code></pre>
 <h3 id="gen-other-html.sh"><a href="../bin/gen-other-html.sh">gen-other-html.sh</a></h3>
-<p>Generate entry HTML files (other than README.md to index.html) from markdown
-files.</p>
+<p>Generate entry HTML files (other than the README.md to index.html files) from
+markdown files.</p>
 <p>Usage:</p>
 <pre><code>    bin/gen-other-html.sh -v 1</code></pre>
 <h3 id="gen-sitemap.sh"><a href="../bin/gen-sitemap.sh">gen-sitemap.sh</a></h3>
 <p>Generate an XML sitemap for the IOCCC website.</p>
 <p>Usage:</p>
 <pre><code>    bin/gen-sitemap.sh -v 1</code></pre>
-<p>We recommend that this tool be invoked via the top level <code>Makefile</code>:</p>
+<p>We recommend that this tool be invoked via the top level <code>Makefile</code> by:</p>
 <pre><code>    make gen_sitemap</code></pre>
 <h3 id="gen-status.sh"><a href="../bin/gen-status.sh">gen-status.sh</a></h3>
 <p>Generate <code>status.json</code> according to the modification dates of <code>status.json</code>
-and <code>news.html</code>.</p>
-<p>Without argument, the <code>contest_status</code> is unchanged.</p>
+and <code>news.md</code>.</p>
+<p>Without an argument, the <code>contest_status</code> is unchanged.</p>
 <p>Usage:</p>
 <pre><code>    bin/gen-status.sh -v 1</code></pre>
 <p>To force the <code>contest_status</code> to be closed:</p>
@@ -462,7 +462,7 @@ and <code>news.html</code>.</p>
 <pre><code>    bin/gen-status.sh -v 1 open</code></pre>
 <p>To see other valid statuses:</p>
 <pre><code>    bin/gen-status -h</code></pre>
-<p>We recommend that this tool be invoked via the top level <code>Makefile</code>:</p>
+<p>We recommend that this tool be invoked via the top level <code>Makefile</code> by:</p>
 <pre><code>    make gen_status</code></pre>
 <h3 id="gen-top-html.sh"><a href="../bin/gen-top-html.sh">gen-top-html.sh</a></h3>
 <p>Generate a number of top level HTML pages for the IOCCC websites.</p>
@@ -483,35 +483,35 @@ and <code>news.html</code>.</p>
 <li><a href="../news.html">news.html</a></li>
 <li><a href="../thanks-for-help.html">thanks-for-help.html</a></li>
 </ul>
-<p>We recommend that this tool be invoked via the top level <code>Makefile</code>:</p>
+<p>We recommend that this tool be invoked via the top level <code>Makefile</code> by:</p>
 <pre><code>    make gen_top_html</code></pre>
 <h3 id="gen-year-index.sh"><a href="../bin/gen-year-index.sh">gen-year-index.sh</a></h3>
-<p>Generate an <code>index.html</code> page for an given IOCCC year.</p>
+<p>Generate an <code>index.html</code> page for a given IOCCC year.</p>
 <p>Usage:</p>
 <pre><code>    bin/gen-year-index.sh -v 1 2020</code></pre>
-<p>We recommend that this tool be invoked via the top level <code>Makefile</code>:</p>
+<p>We recommend that this tool be invoked via the top level <code>Makefile</code> by:</p>
 <pre><code>    make gen_year_index</code></pre>
 <h3 id="gen-years.sh"><a href="../bin/gen-years.sh">gen-years.sh</a></h3>
-<p>Generate the top level <code>/years.html</code> page.</p>
+<p>Generate the top level <code>./years.html</code> page.</p>
 <p>Usage:</p>
 <pre><code>    bin/gen-years.sh -v 1</code></pre>
-<p>We recommend that this tool be invoked via the top level <code>Makefile</code>:</p>
+<p>We recommend that this tool be invoked via the top level <code>Makefile</code> by:</p>
 <pre><code>    make gen_years</code></pre>
 <h3 id="md2html.sh"><a href="../bin/md2html.sh">md2html.sh</a></h3>
 <p>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 <a href="../inc/index.html">inc directory</a>.</p>
 <p>The <a href="../inc/md2html.cfg">../inc/md2html.cfg</a> configuration file is
-used by <a href="md2html.sh">md2html.sh</a> to drive the generation process.</p>
+used by <a href="../bin/md2html.sh">md2html.sh</a> to drive the generation process.</p>
 <h3 id="output-index-author.sh"><a href="../bin/output-index-author.sh">output-index-author.sh</a></h3>
 <p>Output author’s or authors’ related HTML details for an entry’s index.html
 page.</p>
 <h3 id="output-index-inventory.sh"><a href="../bin/output-index-inventory.sh">output-index-inventory.sh</a></h3>
 <p>Output the inventory in HTML form for an entry’s index.html page.</p>
 <h3 id="output-year-index.sh"><a href="../bin/output-year-index.sh">output-year-index.sh</a></h3>
-<p>Output markdown of wining entry links for a given year.</p>
+<p>Output markdown of a winning entry links for a given year.</p>
 <h3 id="pandoc-wrapper.sh"><a href="../bin/pandoc-wrapper.sh">pandoc-wrapper.sh</a></h3>
-<p>Wrapper tool to run pandoc.</p>
+<p>Wrapper tool to run <code>pandoc(1)</code>.</p>
 <h3 id="quick-readme2index.sh"><a href="../bin/quick-readme2index.sh">quick-readme2index.sh</a></h3>
 <p>Builds an entry’s <code>index.html</code> file if the entry directory
 does not have a non-empty <code>index.hmtl</code> file, or if either