Merge pull request #2564 from xexyl/technical-details

2024-07-11 00:54:45 -07:00
commit b9d55b141e
@@ -608,7 +608,7 @@ Your submission must satisfy BOTH the maximum size <a href="rules.html#rule2a">R
 This IOCCC size tool imposes a 2nd limit on C code size (see <a href="rules.html#rule2a">Rule 2a</a>. To check your
 code against <a href="rules.html#rule2">Rule 2</a>:
 </p>
-<pre><code>    ./iocccsize prog.c</code></pre>
+<pre><code>    iocccsize prog.c</code></pre>
 <p>The IOCCC size tool algorithm may be summarized as follows:</p>
 <blockquote>
 <p>The size tool counts most C reserved words (keyword, secondary, and selected
@@ -664,59 +664,103 @@ matters, we give you a brief overview below.
 <p class="leftbar">
 The synopsis of the <code>mkiocccentry(1)</code> tool is:
 </p>
-<pre><code>    ./mkiocccentry [options] work_dir prog.c \
+<pre><code>    mkiocccentry [options] work_dir prog.c \
         Makefile remarks.md [file ...]</code></pre>
 <p class="leftbar">
-… where the <code>work_dir</code> is a directory that is used to form the
+… where <code>work_dir</code> is a directory that will be used to build the submission
-xz compressed tarball that <code>txzchk(1)</code> validates, <code>prog.c</code> is your submission
+tarball, <code>prog.c</code> is your submission source code, <code>Makefile</code> is your submission’s
-source code, <code>Makefile</code> is your <code>Makefile</code>, <code>remarks.md</code> is your remarks and
+<code>Makefile</code>, <code>remarks.md</code> are your remarks (that will be the basis of the
-<code>[file ...]</code> are any additional files you wish to provide.
+<code>README.md</code> file which will be used to form the <code>index.html</code> file if your
 submission wins) and the remaining args are the paths to any other files you
 wish to submit.
 </p>
 <p class="leftbar">
-If the <code>work_dir</code> already exists it is an error. In the case this happens you
+See the <a href="rules.html">Rules</a> and in particular <a href="rules.html#rule17">Rule 17</a> for
-will have to choose a different directory, or if it is safe to remove, you may
+the requirements of these files.
-do so and try again.
+</p>
 <p class="leftbar">
 The <code>work_dir</code> <strong>MUST</strong> already exist, as a directory, and it is an error if it
 is not a directory that can be written to. In this directory your submission
 directory will be created, with the name based on your IOCCC registration
 username <strong>in the form of a UUID</strong> and submission number; see the
 <a href="rules.html">rules</a> for more details on this, and in particular <a href="rules.html#rule17">Rule
 17</a>.
 </p>
 <p class="leftbar">
 If the subdirectory in the work directory already exists, you will have to move
 it or remove it or otherwise specify a different work directory as it needs to
 be empty and the <code>mkiocccentry(1)</code> tool does not check this for you
 as it could do nothing about anyway. This subdirectory is where your files will be
 <strong>copied</strong> to. Your submission tarball (which you will upload to the submit
 server) that <code>txzchk(1)</code> will validate will be placed in the work directory, and
 its contents will be the subdirectory with your submission’s files.
 </p>
 <p class="leftbar">
 The <code>mkiocccentry(1)</code> tool will ask you for information about your
 submission as well as author details and it will run the <code>iocccsize(1)</code> tool; if
 either <a href="rules.html#rule2a">Rule 2a</a> or <a href="rules.html#rule2b">Rule 2b</a> are broken,
-it will give you the option to ignore them, if you are willing to risk this. The
+it will give you the option to ignore them, if you are willing to risk this.
-tool will also do a rudimentary check on the <code>Makefile</code> and run other checks as
+</p>
-well. You can override warnings but doing so puts you at risk of violating
+<p class="leftbar">
-<a href="rules.html">rules</a>.
+The tool will also do a rudimentary check on the <code>Makefile</code> and run other checks as
 well. You can override warnings as well but doing so puts you at risk of
 violating the <a href="rules.html">rules</a>.
 </p>
 <p class="leftbar">
 If you’re brave you can use the <code>-W</code> option to ignore all warnings but this is a
 big risk; the <code>-y</code> option will assume ‘<em>yes</em>’ to most questions but this is also a
 big risk.
 </p>
 <p class="leftbar">
 On the other hand, some <strong>issues are an error</strong> and the xz compressed
 tarball <strong>will not be formed</strong>. For instance, if <code>chkentry(1)</code> fails to validate
 the <code>.auth.json</code> or <code>.info.json</code> <a href="https://www.json.org/json-en.html">JSON</a> files
 that <code>mkiocccentry(1)</code> creates, it is an error and possibly a bug that you
-should report at the <a href="https://github.com/ioccc-src/mkiocccentry/issues">mkiocccentry issues
+should <a href="https://github.com/ioccc-src/mkiocccentry/issues/new?assignees=&amp;labels=bug&amp;projects=&amp;template=bug_report.yml&amp;title=%5BBug%5D+%3Ctitle%3E">report as a bug at the mkiocccentry issues
 page</a>. <strong>PLEASE run the
 <code>bug_report.sh</code> script to help us out here!</strong> See the <a href="../faq.html#mkiocccentry_bugs">the FAQ about reporting
 bugs in the mkiocccentry repo</a>.
 </p>
 <p class="leftbar">
-Assuming that <code>chkentry(1)</code> passes for both <code>.auth.json</code> and
+However, just because there are errors <strong>does not</strong> mean it is a bug in the
 code. It might be an issue with your submission. Thus if you report an error as
 a bug it might not be something that will be fixed as there is nothing to be
 fixed in the first place.
 </p>
 <p class="leftbar">
 Assuming that <code>chkentry(1)</code> validates both <code>.auth.json</code> and
 <code>.info.json</code> then the tarball will be formed and then <code>txzchk(1)</code> will be
-executed. In this case, there should be no problems as <code>mkiocccentry(1)</code> would
+executed. In this case, there should be no problems as <code>mkiocccentry(1)</code> should
-<strong>NOT</strong> form a tarball if there are any issues.
+<strong>NOT</strong> form a tarball if there are any issues. If there is an issue reported,
 however, this is possibly a bug in one or more of the tools and you should <a href="https://github.com/ioccc-src/mkiocccentry/issues/new?assignees=&amp;labels=bug&amp;projects=&amp;template=bug_report.yml&amp;title=%5BBug%5D+%3Ctitle%3E">report
 it as a bug at the mkiocccentry issues
 page</a>.
 See the <a href="../faq.html#mkiocccentry_bugs">the FAQ about reporting
 bugs in the mkiocccentry repo</a>.
 </p>
 <p class="leftbar">
 <code>txzchk(1)</code> performs a wide number of sanity checks on the xz
-compressed tarball and if any issues (<code>feathers</code> :-) ) are found and if you used
+compressed tarball; if any issues are found (‘<code>feathers are stuck in the tarball</code>’ :-) ) <strong>AND if and <em>ONLY IF</em> you used
-<code>mkiocccentry(1)</code>, then it is very possibly a bug in one of the tools and you
+<code>mkiocccentry(1)</code></strong>, then it is very possibly a bug in one of the tools and you
-should report it at the <a href="https://github.com/ioccc-src/mkiocccentry/issues">mkiocccentry issues
+should <a href="https://github.com/ioccc-src/mkiocccentry/issues/new?assignees=&amp;labels=bug&amp;projects=&amp;template=bug_report.yml&amp;title=%5BBug%5D+%3Ctitle%3E">report it as a bug at the mkiocccentry issues
 page</a>. <strong>PLEASE run the
 <code>bug_report.sh</code> script to help us out here!</strong> See <a href="../faq.html#mkiocccentry_bugs">the FAQ about reporting bugs
 in the mkiocccentry repo</a>.
 </p>
 <p class="leftbar">
 As part of its sanity checks, <code>txzchk(1)</code> will run <code>fnamchk(1)</code> on the
-<em>filename</em> to verify that the name is valid. If this test does not pass, then it
+<em>filename</em> to verify that the name is valid.
-is flagged by <code>txzchk(1)</code> but it is not an error if you wish to ignore it.
+</p>
-Ignoring this, however, risks violating <a href="rules.html#rule17">Rule 17</a> which is a
+<p class="leftbar">
-big risk. Of course, using <code>mkiocccentry(1)</code> would prevent this from happening.
+It is extremely unlikely that <code>fnamchk(1)</code> reporting an invalid filename is a
 bug in <code>fnamchk(1)</code> and as such, ignoring such an issue risks violating <a href="rules.html#rule17">Rule
 17</a> which is a big risk. Of course, using <code>mkiocccentry(1)</code>
 would prevent this from happening as it would not create such a file anyway. If
 <code>mkiocccentry(1)</code> was used it would rather suggest a bug in one of the tools and
 you should <a href="https://github.com/ioccc-src/mkiocccentry/issues/new?assignees=&amp;labels=bug&amp;projects=&amp;template=bug_report.yml&amp;title=%5BBug%5D+%3Ctitle%3E">report it as a bug at the mkiocccentry issues
 page</a>.
 See <a href="../faq.html#mkiocccentry_bugs">the FAQ about reporting bugs in the mkiocccentry
 repo</a>.
 </p>
 <p class="leftbar">
 By default, <code>txzchk(1)</code> will show the contents of the tarball which is
@@ -725,41 +769,55 @@ how the <code>mkiocccentry(1)</code> shows you the tarball contents for you to r
 <p class="leftbar">
 To help you with editing a submission, the <code>mkiocccentry(1)</code> tool has
 some options to write <em>OR</em> read from an answers file so you do not have to input
-the information again. To write to <code>answers.txt</code> try:
+the information about the author(s) and the entry itself after saving the
 answers to a file. To write to <code>answers.txt</code> try:
 </p>
-<pre><code>    ./mkiocccentry -a answers.txt ...</code></pre>
+<pre><code>    mkiocccentry -a answers.txt ...</code></pre>
 <p class="leftbar">
 Alternatively, if you wish to overwrite a file, you can use the <code>-A</code>
-flag with the same option argument. Be careful that you do not accidentally
+flag with the same option argument. Be <strong>very careful</strong> that you do not accidentally
-overwrite your <code>prog.c</code>!
+overwrite your <code>prog.c</code> or some other important file!
 </p>
 <p class="leftbar">
 To make use of the answers file, use the <code>-i answers</code> option like:
 </p>
-<pre><code>    ./mkiocccentry -i answers.txt ...</code></pre>
+<pre><code>    mkiocccentry -i answers.txt ...</code></pre>
 <p class="leftbar">
-If you wish to manually run the commands you can do so. For instance, to check
+If you wish to manually run the commands that <code>mkiocccentry(1)</code> runs, to test
-the validity of the tarball
+your submission, you can do so. For instance, to check the validity of the
-<code>submit.12345678-1234-4321-abcd-1234567890ab-2.1719574527.txz</code> you can do:
+tarball <code>submit.12345678-1234-4321-abcd-1234567890ab-2.1720636351.txz</code> you can
 do:
 </p>
-<pre><code>    ./txzchk submit.12345678-1234-4321-abcd-1234567890ab-2.1719574527.txz</code></pre>
+<pre><code>    txzchk submit.12345678-1234-4321-abcd-1234567890ab-2.1720636351.txz</code></pre>
 <p class="leftbar">
 Assuming that the tarball exists and is valid, you should see the
-contents of the tarball and the words:
+contents of the tarball, along with a few other minor details, and the words:
 </p>
 <blockquote>
 <p>No feathers stuck in tarball.</p>
 </blockquote>
 <p class="leftbar">
-If you give the option <code>-q</code> it will not report anything unless there
+If you give the option <code>-q</code> it will not report anything unless there are certain
-are certain error conditions, for instance if <code>fnamchk(1)</code> reports there is a
+error conditions; issues (‘feathers’ :-) ) found in the tarball are not
-problem with the filename; if <code>txzchk(1)</code> exits 0 then there are no problems
+considered errors so that one can get an overview of all the issues in the
-detected.
+tarball but with <code>-q</code> these will not be reported unless <code>-w</code> is used (but as
 <code>-w</code> is meant for the test suite you do not need to concern yourself with that).
 Thus you should check the exit code if you use <code>-q</code>.
 </p>
 <p class="leftbar">
 For instance, the following command will not show anything unless there is a
 problem with the tarball, in which case it will show <code>Feathers stuck in tarball :-(</code>.
 </p>
 <pre><code>    txzchk -q submit.12345678-1234-4321-abcd-1234567890ab-2.1720636351.txz || \
    echo &#39;Feathers stuck in tarball :-(&#39;</code></pre>
 <p class="leftbar">
 Alternatively you could just check the exit code with <code>echo $?</code>; a value of 0
 indicates all is OK.
 </p>
 <p class="leftbar">
 If you wish to run <code>fnamchk(1)</code> directly you can do so like:
 </p>
-<pre><code>    ./fnamchk submit.12345678-1234-4321-abcd-1234567890ab-2.1719574527.txz</code></pre>
+<pre><code>    fnamchk submit.12345678-1234-4321-abcd-1234567890ab-2.1720636351.txz</code></pre>
 <p class="leftbar">
 Assuming everything is OK, it would show:
 </p>
@@ -767,7 +825,7 @@ Assuming everything is OK, it would show:
 <p><code>12345678-1234-4321-abcd-1234567890ab-2</code></p>
 </blockquote>
 <p class="leftbar">
-… which <code>txzchk(1)</code> uses.
+… which, as stated earlier, <code>txzchk(1)</code> uses.
 </p>
 <p class="leftbar">
 If you want to validate the <code>.auth.json</code> or <code>.info.json</code> files you
@@ -777,23 +835,23 @@ If you pass a single argument, it is expected to be a directory that has both
 <code>.info.json</code> file. An argument of <code>.</code> will skip that file. For instance:
 </p>
 <pre><code>    # test entry directory test_work:
-    ./chkentry test_work
+    chkentry test_work
    # run checks on .info.json:
-    ./chkentry .info.json .
+    chkentry .info.json .
    # run checks on .auth.json:
-    ./chkentry . .auth.json
+    chkentry . .auth.json
    # run checks on .info.json and .auth.json:
-    ./chkentry .info.json .auth.json</code></pre>
+    chkentry .info.json .auth.json</code></pre>
 <p class="leftbar">
 If there is a <a href="https://www.json.org/json-en.html">JSON</a> issue detected
 by <code>jparse(8)</code>, <strong>then there is a <a href="https://www.json.org/json-en.html">JSON</a>
 error and <code>chkentry(1)</code> will report it as an <em>error</em></strong>. If the parsing is OK <strong>but
 there <em>is an issue</em> in one or both of the
-<a href="https://www.json.org/json-en.html">JSON</a></strong> files <strong>in the context of the IOCCC</strong>,
+<a href="https://www.json.org/json-en.html">JSON</a> files in <em>the context of the IOCCC</em>,
-<em>it will <strong>report this as an error</strong></em>. Thus, if you were to package this manually
+it will report this as an error</strong>. Thus, if you were to package this manually
 then you would be violating <a href="rules.html#rule17">Rule 17</a>.
 </p>
 <p class="leftbar">
@@ -282,7 +282,7 @@ code against [Rule 2](rules.html#rule2):
 </p>
 ``` <!---sh-->
-    ./iocccsize prog.c
+    iocccsize prog.c
 ```
 The IOCCC size tool algorithm may be summarized as follows:
@@ -352,31 +352,60 @@ The synopsis of the `mkiocccentry(1)` tool is:
 </p>
 ``` <!---sh-->
-    ./mkiocccentry [options] work_dir prog.c \
+    mkiocccentry [options] work_dir prog.c \
         Makefile remarks.md [file ...]
 ```
 <p class="leftbar">
-... where the `work_dir` is a directory that is used to form the
+... where `work_dir` is a directory that will be used to build the submission
-xz compressed tarball that `txzchk(1)` validates, `prog.c` is your submission
+tarball, `prog.c` is your submission source code, `Makefile` is your submission's
-source code, `Makefile` is your `Makefile`, `remarks.md` is your remarks and
+`Makefile`, `remarks.md` are your remarks (that will be the basis of the
-`[file ...]` are any additional files you wish to provide.
+`README.md` file which will be used to form the `index.html` file if your
 submission wins) and the remaining args are the paths to any other files you
 wish to submit.
 </p>
 <p class="leftbar">
-If the `work_dir` already exists it is an error. In the case this happens you
+See the [Rules](rules.html) and in particular [Rule 17](rules.html#rule17) for
-will have to choose a different directory, or if it is safe to remove, you may
+the requirements of these files.
-do so and try again.
+</p>
 <p class="leftbar">
 The `work_dir` **MUST** already exist, as a directory, and it is an error if it
 is not a directory that can be written to. In this directory your submission
 directory will be created, with the name based on your IOCCC registration
 username **in the form of a UUID** and submission number; see the
 [rules](rules.html) for more details on this, and in particular [Rule
 17](rules.html#rule17).
 </p>
 <p class="leftbar">
 If the subdirectory in the work directory already exists, you will have to move
 it or remove it or otherwise specify a different work directory as it needs to
 be empty and the `mkiocccentry(1)` tool does not check this for you
 as it could do nothing about anyway. This subdirectory is where your files will be
 **copied** to. Your submission tarball (which you will upload to the submit
 server) that `txzchk(1)` will validate will be placed in the work directory, and
 its contents will be the subdirectory with your submission's files.
 </p>
 <p class="leftbar">
 The `mkiocccentry(1)` tool will ask you for information about your
 submission as well as author details and it will run the `iocccsize(1)` tool; if
 either [Rule 2a](rules.html#rule2a) or [Rule 2b](rules.html#rule2b) are broken,
-it will give you the option to ignore them, if you are willing to risk this. The
+it will give you the option to ignore them, if you are willing to risk this.
-tool will also do a rudimentary check on the `Makefile` and run other checks as
+</p>
-well. You can override warnings but doing so puts you at risk of violating
+
-[rules](rules.html).
+<p class="leftbar">
 The tool will also do a rudimentary check on the `Makefile` and run other checks as
 well. You can override warnings as well but doing so puts you at risk of
 violating the [rules](rules.html).
 </p>
 <p class="leftbar">
 If you're brave you can use the `-W` option to ignore all warnings but this is a
 big risk; the `-y` option will assume '_yes_' to most questions but this is also a
 big risk.
 </p>
 <p class="leftbar">
@@ -384,35 +413,57 @@ On the other hand, some **issues are an error** and the xz compressed
 tarball **will not be formed**. For instance, if `chkentry(1)` fails to validate
 the `.auth.json` or `.info.json` [JSON](https://www.json.org/json-en.html) files
 that `mkiocccentry(1)` creates, it is an error and possibly a bug that you
-should report at the [mkiocccentry issues
+should [report as a bug at the mkiocccentry issues
-page](https://github.com/ioccc-src/mkiocccentry/issues). **PLEASE run the
+page](https://github.com/ioccc-src/mkiocccentry/issues/new?assignees=&labels=bug&projects=&template=bug_report.yml&title=%5BBug%5D+%3Ctitle%3E). **PLEASE run the
 `bug_report.sh` script to help us out here!** See the [the FAQ about reporting
 bugs in the mkiocccentry repo](../faq.html#mkiocccentry_bugs).
 </p>
 <p class="leftbar">
-Assuming that `chkentry(1)` passes for both `.auth.json` and
+However, just because there are errors **does not** mean it is a bug in the
 code. It might be an issue with your submission. Thus if you report an error as
 a bug it might not be something that will be fixed as there is nothing to be
 fixed in the first place.
 </p>
 <p class="leftbar">
 Assuming that `chkentry(1)` validates both `.auth.json` and
 `.info.json` then the tarball will be formed and then `txzchk(1)` will be
-executed. In this case, there should be no problems as `mkiocccentry(1)` would
+executed. In this case, there should be no problems as `mkiocccentry(1)` should
-**NOT** form a tarball if there are any issues.
+**NOT** form a tarball if there are any issues. If there is an issue reported,
 however, this is possibly a bug in one or more of the tools and you should [report
 it as a bug at the mkiocccentry issues
 page](https://github.com/ioccc-src/mkiocccentry/issues/new?assignees=&labels=bug&projects=&template=bug_report.yml&title=%5BBug%5D+%3Ctitle%3E).
 See the [the FAQ about reporting
 bugs in the mkiocccentry repo](../faq.html#mkiocccentry_bugs).
 </p>
 <p class="leftbar">
 `txzchk(1)` performs a wide number of sanity checks on the xz
-compressed tarball and if any issues (`feathers` :-) ) are found and if you used
+compressed tarball; if any issues are found ('`feathers are stuck in the
-`mkiocccentry(1)`, then it is very possibly a bug in one of the tools and you
+tarball`' :-) ) **AND if and _ONLY IF_ you used
-should report it at the [mkiocccentry issues
+`mkiocccentry(1)`**, then it is very possibly a bug in one of the tools and you
-page](https://github.com/ioccc-src/mkiocccentry/issues). **PLEASE run the
+should [report it as a bug at the mkiocccentry issues
 page](https://github.com/ioccc-src/mkiocccentry/issues/new?assignees=&labels=bug&projects=&template=bug_report.yml&title=%5BBug%5D+%3Ctitle%3E). **PLEASE run the
 `bug_report.sh` script to help us out here!** See [the FAQ about reporting bugs
 in the mkiocccentry repo](../faq.html#mkiocccentry_bugs).
 </p>
 <p class="leftbar">
 As part of its sanity checks, `txzchk(1)` will run `fnamchk(1)` on the
-_filename_ to verify that the name is valid. If this test does not pass, then it
+_filename_ to verify that the name is valid.
-is flagged by `txzchk(1)` but it is not an error if you wish to ignore it.
+</p>
-Ignoring this, however, risks violating [Rule 17](rules.html#rule17) which is a
+
-big risk. Of course, using `mkiocccentry(1)` would prevent this from happening.
+<p class="leftbar">
 It is extremely unlikely that `fnamchk(1)` reporting an invalid filename is a
 bug in `fnamchk(1)` and as such, ignoring such an issue risks violating [Rule
 17](rules.html#rule17) which is a big risk. Of course, using `mkiocccentry(1)`
 would prevent this from happening as it would not create such a file anyway. If
 `mkiocccentry(1)` was used it would rather suggest a bug in one of the tools and
 you should [report it as a bug at the mkiocccentry issues
 page](https://github.com/ioccc-src/mkiocccentry/issues/new?assignees=&labels=bug&projects=&template=bug_report.yml&title=%5BBug%5D+%3Ctitle%3E).
 See [the FAQ about reporting bugs in the mkiocccentry
 repo](../faq.html#mkiocccentry_bugs).
 </p>
 <p class="leftbar">
@@ -423,17 +474,18 @@ how the `mkiocccentry(1)` shows you the tarball contents for you to review.
 <p class="leftbar">
 To help you with editing a submission, the `mkiocccentry(1)` tool has
 some options to write _OR_ read from an answers file so you do not have to input
-the information again. To write to `answers.txt` try:
+the information about the author(s) and the entry itself after saving the
 answers to a file. To write to `answers.txt` try:
 </p>
 ``` <!---sh-->
-    ./mkiocccentry -a answers.txt ...
+    mkiocccentry -a answers.txt ...
 ```
 <p class="leftbar">
 Alternatively, if you wish to overwrite a file, you can use the `-A`
-flag with the same option argument. Be careful that you do not accidentally
+flag with the same option argument. Be **very careful** that you do not accidentally
-overwrite your `prog.c`!
+overwrite your `prog.c` or some other important file!
 </p>
 <p class="leftbar">
@@ -441,31 +493,50 @@ To make use of the answers file, use the `-i answers` option like:
 </p>
 ``` <!---sh-->
-    ./mkiocccentry -i answers.txt ...
+    mkiocccentry -i answers.txt ...
 ```
 <p class="leftbar">
-If you wish to manually run the commands you can do so. For instance, to check
+If you wish to manually run the commands that `mkiocccentry(1)` runs, to test
-the validity of the tarball
+your submission, you can do so. For instance, to check the validity of the
-`submit.12345678-1234-4321-abcd-1234567890ab-2.1719574527.txz ` you can do:
+tarball `submit.12345678-1234-4321-abcd-1234567890ab-2.1720636351.txz` you can
 do:
 </p>
 ``` <!---sh-->
-    ./txzchk submit.12345678-1234-4321-abcd-1234567890ab-2.1719574527.txz
+    txzchk submit.12345678-1234-4321-abcd-1234567890ab-2.1720636351.txz
 ```
 <p class="leftbar">
 Assuming that the tarball exists and is valid, you should see the
-contents of the tarball and the words:
+contents of the tarball, along with a few other minor details, and the words:
 </p>
 > No feathers stuck in tarball.
 <p class="leftbar">
-If you give the option `-q` it will not report anything unless there
+If you give the option `-q` it will not report anything unless there are certain
-are certain error conditions, for instance if `fnamchk(1)` reports there is a
+error conditions; issues ('feathers' :-) ) found in the tarball are not
-problem with the filename; if `txzchk(1)` exits 0 then there are no problems
+considered errors so that one can get an overview of all the issues in the
-detected.
+tarball but with `-q` these will not be reported unless `-w` is used (but as
 `-w` is meant for the test suite you do not need to concern yourself with that).
 Thus you should check the exit code if you use `-q`.
 </p>
 <p class="leftbar">
 For instance, the following command will not show anything unless there is a
 problem with the tarball, in which case it will show `Feathers stuck in tarball
 :-(`.
 </p>
 ``` <!---sh-->
    txzchk -q submit.12345678-1234-4321-abcd-1234567890ab-2.1720636351.txz || \
    echo 'Feathers stuck in tarball :-('
 ```
 <p class="leftbar">
 Alternatively you could just check the exit code with `echo $?`; a value of 0
 indicates all is OK.
 </p>
 <p class="leftbar">
@@ -473,7 +544,7 @@ If you wish to run `fnamchk(1)` directly you can do so like:
 </p>
 ``` <!---sh-->
-    ./fnamchk submit.12345678-1234-4321-abcd-1234567890ab-2.1719574527.txz
+    fnamchk submit.12345678-1234-4321-abcd-1234567890ab-2.1720636351.txz
 ```
 <p class="leftbar">
@@ -483,7 +554,7 @@ Assuming everything is OK, it would show:
 > `12345678-1234-4321-abcd-1234567890ab-2`
 <p class="leftbar">
-... which `txzchk(1)` uses.
+... which, as stated earlier, `txzchk(1)` uses.
 </p>
 <p class="leftbar">
@@ -496,16 +567,16 @@ If you pass a single argument, it is expected to be a directory that has both
 ``` <!---sh-->
    # test entry directory test_work:
-    ./chkentry test_work
+    chkentry test_work
    # run checks on .info.json:
-    ./chkentry .info.json .
+    chkentry .info.json .
    # run checks on .auth.json:
-    ./chkentry . .auth.json
+    chkentry . .auth.json
    # run checks on .info.json and .auth.json:
-    ./chkentry .info.json .auth.json
+    chkentry .info.json .auth.json
 ```
 <p class="leftbar">
@@ -513,8 +584,8 @@ If there is a [JSON](https://www.json.org/json-en.html) issue detected
 by `jparse(8)`, **then there is a [JSON](https://www.json.org/json-en.html)
 error and `chkentry(1)` will report it as an _error_**. If the parsing is OK **but
 there _is an issue_ in one or both of the
-[JSON](https://www.json.org/json-en.html)** files **in the context of the IOCCC**,
+[JSON](https://www.json.org/json-en.html) files in _the context of the IOCCC_,
-_it will **report this as an error**_. Thus, if you were to package this manually
+it will report this as an error**. Thus, if you were to package this manually
 then you would be violating [Rule 17](rules.html#rule17).
 </p>
@@ -705,7 +705,7 @@ been published may be disqualified.</p>
 </div>
 <h3 id="tldr-rule-17---use-mkiocccentry1">TL;DR Rule 17 - Use <code>mkiocccentry(1)</code></h3>
 <p class="leftbar">
-This is a <strong>COMPLEX</strong> rule. <strong>Violating this rule will cause your submission to REJECTED</strong>!
+This is a <strong>COMPLEX</strong> rule. <strong>Violating this rule will cause your submission to REJECTED!</strong>
 To help you avoid such a rejection, you are <strong>HIGHLY ENCOURAGED</strong> to use the <code>mkiocccentry(1)</code> tool,
 based on the latest release of the <a href="https://github.com/ioccc-src/mkiocccentry">mkiocccentry repo</a>,
 to form your submission’s xz compressed tarball.
@@ -740,7 +740,8 @@ conforms to <a href="#rule17">Rule 17</a>.
 </p>
 <p class="leftbar">
 Each above mentioned tools has a <code>-h</code> option that provides command
-line help. For additional details, see the tools’ man pages.
+line help. For additional details, see the tools’ man pages and the
 <a href="guidelines.html">guidelines</a>.
 </p>
 <p class="leftbar">
 You do not explicitly need to invoke <code>jparse(1)</code> but the <code>jparse(8)</code>
@@ -900,7 +901,7 @@ The <code>txzchk(1)</code> tool will verify these (and other things) for you and
 the <code>chkentry(1)</code> tool will do additional checks on the contents of the
 <code>.auth.json</code> and <code>.info.json</code> files including JSON validity. If these checks
 fail it is an error and <code>mkiocccentry(1)</code> will fail. In this case it is very
-<strong>possibly</strong> a bug; please <a href="https://github.com/ioccc-src/mkiocccentry/issues/new?assignees=&amp;labels=bug&amp;projects=&amp;template=bug_report.yml&amp;title=%5BBug%5D+%3Ctitle%3E">report it at the mkiocccentry issues
+<strong>possibly</strong> a bug; please <a href="https://github.com/ioccc-src/mkiocccentry/issues/new?assignees=&amp;labels=bug&amp;projects=&amp;template=bug_report.yml&amp;title=%5BBug%5D+%3Ctitle%3E">report it as a bug at the mkiocccentry issues
 page</a>.
 </p>
 <p class="leftbar">
@@ -946,7 +947,7 @@ use parts of the library as well.
 </p>
 <p class="leftbar">
 If you run into a problem with one or more of these tools, <strong>PLEASE</strong> <a href="https://github.com/ioccc-src/mkiocccentry/issues/new?assignees=&amp;labels=bug&amp;projects=&amp;template=bug_report.yml&amp;title=%5BBug%5D+%3Ctitle%3E">report it
-at the mkiocccentry issues
+as a bug at the mkiocccentry issues
 page</a>,
 <strong>making sure to run <code>bug_report.sh</code></strong>. See the <a href="guidelines.html">guidelines</a>
 for help here and also read <a href="../faq.html#mkiocccentry_bugs">the FAQ about reporting bugs in the mkiocccentry
@@ -451,7 +451,7 @@ been published may be disqualified.
 ### TL;DR Rule 17 - Use `mkiocccentry(1)`
 <p class="leftbar">
-This is a **COMPLEX** rule.  **Violating this rule will cause your submission to REJECTED**!
+This is a **COMPLEX** rule.  **Violating this rule will cause your submission to REJECTED!**
 To help you avoid such a rejection, you are **HIGHLY ENCOURAGED** to use the `mkiocccentry(1)` tool,
 based on the latest release of the [mkiocccentry repo](https://github.com/ioccc-src/mkiocccentry),
 to form your submission's xz compressed tarball.
@@ -476,7 +476,8 @@ conforms to [Rule 17](#rule17).
 <p class="leftbar">
 Each above mentioned tools has a `-h` option that provides command
-line help.  For additional details, see the tools' man pages.
+line help.  For additional details, see the tools' man pages and the
 [guidelines](guidelines.html).
 </p>
 <p class="leftbar">
@@ -630,7 +631,7 @@ The `txzchk(1)` tool will verify these (and other things) for you and
 the `chkentry(1)` tool will do additional checks on the contents of the
 `.auth.json` and `.info.json` files including JSON validity. If these checks
 fail it is an error and `mkiocccentry(1)` will fail. In this case it is very
-**possibly** a bug; please [report it at the mkiocccentry issues
+**possibly** a bug; please [report it as a bug at the mkiocccentry issues
 page](https://github.com/ioccc-src/mkiocccentry/issues/new?assignees=&labels=bug&projects=&template=bug_report.yml&title=%5BBug%5D+%3Ctitle%3E).
 </p>
@@ -685,7 +686,7 @@ use parts of the library as well.
 <p class="leftbar">
 If you run into a problem with one or more of these tools, **PLEASE** [report it
-at the mkiocccentry issues
+as a bug at the mkiocccentry issues
 page](https://github.com/ioccc-src/mkiocccentry/issues/new?assignees=&labels=bug&projects=&template=bug_report.yml&title=%5BBug%5D+%3Ctitle%3E),
 **making sure to run `bug_report.sh`**. See the [guidelines](guidelines.html)
 for help here and also read [the FAQ about reporting bugs in the mkiocccentry