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

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:

    bin/chk-entry.sh 2020/ferguson1

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:

    awk -f bin/filelist.entry.json.awk 2020/ferguson1/.entry.json

find-missing-links.sh

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.

gen-authors.sh

-

Generate the top level /authors.html page.

+

Generate the top level ./authors.html page.

Usage:

    bin/gen-authors.sh -v 1

gen-location.sh

-

Generate the top level /location.html page.

+

Generate the top level ./location.html page.

Usage:

    bin/gen-location.sh -v 1

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:

    bin/gen-other-html.sh -v 1

gen-sitemap.sh

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

gen-status.sh

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

gen-top-html.sh

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

    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:

        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

    gen-years.sh

    -

    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

    md2html.sh

    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-index-author.sh

    Output author’s or authors’ related HTML details for an entry’s index.html page.

    output-index-inventory.sh

    Output the inventory in HTML form for an entry’s index.html page.

    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

    -

    Wrapper tool to run pandoc.

    +

    Wrapper tool to run pandoc(1).

    quick-readme2index.sh

    Builds an entry’s index.html file if the entry directory does not have a non-empty index.hmtl file, or if either