Merge pull request #2536 from xexyl/rules-guidelines

Fixes in rules, guidelines, additional FAQ

faq.html

@@ -393,6 +393,7 @@
 <li><a href="#faq0_5">0.5 - How may I comment or make a suggestion on IOCCC rules, guidelines and tools?</a></li>
 <li><a href="#faq0_6">0.6 - What is the best way to ask a question about the IOCCC rules, guideline and tools?</a></li>
 <li><a href="#faq0_7">0.7 - What are the IOCCC best practices for using markdown?</a></li>
+<li><a href="#faq0_8">0.8 - How do I report bugs in a <code>mkiocccentry</code> tool?</a></li>
 </ul>
 <h2 id="section-1---history-of-the-ioccc">Section 1 - <a href="#faq1">History of the IOCCC</a></h2>
 <ul>
@@ -790,6 +791,32 @@ start with some markdown content.</p>
 as it lists things you <strong>should not use</strong> in markdown files.</p>
 <p>See the <a href="https://www.markdownguide.org/basic-syntax">markdown syntax</a> guide.
 See also <a href="https://spec.commonmark.org/current/">CommonMark Spec</a>.</p>
+<div id="faq0_8">
+<div id="mkiocccentry_bugs">
+<h3 id="faq-0.8---how-do-i-report-bugs-in-a-mkiocccentry-tool">FAQ 0.8: - How do I report bugs in a <code>mkiocccentry</code> tool?</h3>
+</div>
+</div>
+<p>As the <a href="https://github.com/ioccc-src/mkiocccentry">mkiocccentry toolkit</a> is
+crucial in the contest, both for submitters and the judges, if you find a bug
+(or you think you find a bug) we would be grateful if you were to report it at
+the <a href="https://github.com/ioccc-src/mkiocccentry/issues">mkiocccentry issues
+page</a>.</p>
+<p>When opening an issue for what you think is a bug, <strong>PLEASE</strong> use the <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">‘Bug report’
+option</a>
+and <strong>PLEASE state in the <em>title</em> what tool you think has a bug</strong>.</p>
+<p>When reporting a bug, <strong>PLEASE make sure to run the <code>bug_report.sh</code> script</strong>.
+<strong>This is extremely helpful</strong> and without it it makes it much harder to determine
+the problem (at least in some cases :-) ). Describing the problem in as much
+detail as you can and attaching any relevant screenshots, other files (in
+addition to the bug report log file) and so on will also be very helpful.</p>
+<p>To run the <code>bug_report.sh</code> script, switch to the <code>mkiocccentry</code> directory and
+then run:</p>
+<pre><code>     ./bug_report.sh</code></pre>
+<p>Let it do its thing and when it’s done it will tell you the name of the log
+file. If it does not find a problem but you think there is a problem, please
+still do feel free to report it and do make sure you attach the log nonetheless.
+If it does find problems, it will give you a summary of the problems and when
+you attach the log file we will see those too.</p>
 <div id="faq1">
 <h2 id="section-1-history-of-the-ioccc">Section 1: History of the IOCCC</h2>
 </div>
@@ -1092,7 +1119,8 @@ to the <a href="https://www.ioccc.org">official IOCCC website</a>.</p>
 <h3 id="faq-2.1-what-should-i-put-in-the-remarks.md-file-of-my-entry">FAQ 2.1: What should I put in the remarks.md file of my entry?</h3>
 </div>
 </div>
-<p>While you may put in as much or as little as you wish into your entry’s
+<p>First, <strong>PLEASE</strong> read the <a href="markdown.html">IOCCC markdown guidelines</a>.</p>
+<p>Next, while you may put in as much or as little as you wish into your entry’s
 <code>remarks.md</code> file, we do have few important suggestions:</p>
 <p>We recommend that you explain how to use your entry. Explain the
 command line (if any command line options and arguments are used)
@@ -1125,7 +1153,6 @@ rounds; we look at the author name only if an entry wins. See the guidelines if
 this is not clear!</li>
 <li>leaving the remark section empty.</li>
 </ul>
-https://github.com/ioccc-src/temp-test-ioccc/blob/master/
 <div id="faq2_2">
 <h3 id="faq-2.2-why-dont-you-publish-entries-that-do-not-win">FAQ 2.2: Why don’t you publish entries that do not win?</h3>
 </div>
@@ -1960,9 +1987,9 @@ provided by the author and any other file in the winning entry, found under the
 entry’s subdirectory.</p>
 <p>If you downloaded <code>1984/mullender/1984_mullender.tar.bz2</code>, for instance, you might
 then do:</p>
-<div class="sourceCode" id="cb58"><pre class="sourceCode sh"><code class="sourceCode bash"><span id="cb58-1"><a href="#cb58-1" aria-hidden="true" tabindex="-1"></a>        <span class="bu">cd</span> 1984/mullender</span>
+<div class="sourceCode" id="cb59"><pre class="sourceCode sh"><code class="sourceCode bash"><span id="cb59-1"><a href="#cb59-1" aria-hidden="true" tabindex="-1"></a>        <span class="bu">cd</span> 1984/mullender</span>
-<span id="cb58-2"><a href="#cb58-2" aria-hidden="true" tabindex="-1"></a>        <span class="fu">make</span> everything</span>
+<span id="cb59-2"><a href="#cb59-2" aria-hidden="true" tabindex="-1"></a>        <span class="fu">make</span> everything</span>
-<span id="cb58-3"><a href="#cb58-3" aria-hidden="true" tabindex="-1"></a>        <span class="ex">./mullender.alt</span></span></code></pre></div>
+<span id="cb59-3"><a href="#cb59-3" aria-hidden="true" tabindex="-1"></a>        <span class="ex">./mullender.alt</span></span></code></pre></div>
 <p>to compile all versions and then run the alternate version (if you have
 a PDP-11 or VAX-11 you would be able to run the original version). For more help
 on compiling entries, see also <a href="#faq3_0">3.0 - What Makefile rules are available to
@@ -2003,8 +2030,8 @@ if you switched to each entry’s directory and ran <code>make everything</code>
 <p>If you download the 1984 tarball, i.e. <code>1984/1984.tar.bz2</code>, then you might
 extract it and then switch to the directory and compile everything of each
 entry:</p>
-<div class="sourceCode" id="cb59"><pre class="sourceCode sh"><code class="sourceCode bash"><span id="cb59-1"><a href="#cb59-1" aria-hidden="true" tabindex="-1"></a>        <span class="bu">cd</span> 1984</span>
+<div class="sourceCode" id="cb60"><pre class="sourceCode sh"><code class="sourceCode bash"><span id="cb60-1"><a href="#cb60-1" aria-hidden="true" tabindex="-1"></a>        <span class="bu">cd</span> 1984</span>
-<span id="cb59-2"><a href="#cb59-2" aria-hidden="true" tabindex="-1"></a>        <span class="fu">make</span> everything</span></code></pre></div>
+<span id="cb60-2"><a href="#cb60-2" aria-hidden="true" tabindex="-1"></a>        <span class="fu">make</span> everything</span></code></pre></div>
 <p>For more help on compiling entries, see also <a href="#faq3_0">3.0 - What Makefile rules are
 available to build or clean up IOCCC entries?</a>.</p>
 <p>Of course in this case you can also switch to individual entries and look at the

faq.md

@@ -10,6 +10,8 @@
 - [0.5  - How may I comment or make a suggestion on IOCCC rules, guidelines and tools?](#faq0_5)
 - [0.6  - What is the best way to ask a question about the IOCCC rules, guideline and tools?](#faq0_6)
 - [0.7  - What are the IOCCC best practices for using markdown?](#faq0_7)
+- [0.8  - How do I report bugs in a `mkiocccentry` tool?](#faq0_8)
+
 
 
 ## Section  1 - [History of the IOCCC](#faq1)
@@ -538,6 +540,42 @@ See also [CommonMark Spec](https://spec.commonmark.org/current/).
 
 
 
+<div id="faq0_8">
+<div id="mkiocccentry_bugs">
+### FAQ 0.8: - How do I report bugs in a `mkiocccentry` tool?
+</div>
+</div>
+
+As the [mkiocccentry toolkit](https://github.com/ioccc-src/mkiocccentry) is
+crucial in the contest, both for submitters and the judges, if you find a bug
+(or you think you find a bug) we would be grateful if you were to report it at
+the [mkiocccentry issues
+page](https://github.com/ioccc-src/mkiocccentry/issues).
+
+When opening an issue for what you think is a bug, **PLEASE** use the ['Bug report'
+option](https://github.com/ioccc-src/mkiocccentry/issues/new?assignees=&labels=bug&projects=&template=bug_report.yml&title=%5BBug%5D+%3Ctitle%3E)
+and **PLEASE state in the _title_ what tool you think has a bug**.
+
+When reporting a bug, **PLEASE make sure to run the `bug_report.sh` script**.
+**This is extremely helpful** and without it it makes it much harder to determine
+the problem (at least in some cases :-) ). Describing the problem in as much
+detail as you can and attaching any relevant screenshots, other files (in
+addition to the bug report log file) and so on will also be very helpful.
+
+To run the `bug_report.sh` script, switch to the `mkiocccentry` directory and
+then run:
+
+``` <!---sh-->
+     ./bug_report.sh
+```
+
+Let it do its thing and when it's done it will tell you the name of the log
+file. If it does not find a problem but you think there is a problem, please
+still do feel free to report it and do make sure you attach the log nonetheless.
+If it does find problems, it will give you a summary of the problems and when
+you attach the log file we will see those too.
+
+
 <div id="faq1">
 ## Section 1: History of the IOCCC
 </div>
@@ -915,7 +953,9 @@ By tradition, we do not say.
 </div>
 </div>
 
-While you may put in as much or as little as you wish into your entry's
+First, **PLEASE** read the [IOCCC markdown guidelines](markdown.html).
+
+Next, while you may put in as much or as little as you wish into your entry's
 `remarks.md` file, we do have few important suggestions:
 
 We recommend that you explain how to use your entry.  Explain the
@@ -956,7 +996,7 @@ this is not clear!
 - leaving the remark section empty.
 
 
-%%REPO_URL%%/<div id="faq2_2">
+<div id="faq2_2">
 ### FAQ 2.2: Why don't you publish entries that do not win?
 </div>
 

next/guidelines.html

@@ -413,7 +413,7 @@ writing by <a href="../contact.html">contacting the judges</a>.</p>
 <div id="guidelines_version">
 <h2 id="ioccc-guidelines-version">IOCCC Guidelines version</h2>
 </div>
-<p><strong><code>|</code></strong> These <a href="guidelines.html">IOCCC guidelines</a> are version <strong>28.3 2024-07-01</strong>.</p>
+<p><strong><code>|</code></strong> These <a href="guidelines.html">IOCCC guidelines</a> are version <strong>28.4 2024-07-02</strong>.</p>
 <p><strong>IMPORTANT</strong>: Be <strong>SURE</strong> to read the <a href="rules.html">IOCCC rules</a>.</p>
 <div id="change_marks">
 <h3 id="change-marks">Change marks</h3>
@@ -459,7 +459,7 @@ you are using the correct versions of these items before using the
 IOCCC submission URL.</p>
 <p><strong><code>|</code></strong> The <a href="rules.html#rule2a">Rule 2a</a> size has <strong>increased from 4096 to 4993</strong> bytes.</p>
 <p><strong><code>|</code></strong> The <a href="rules.html#rule2b">Rule 2b</a> size has <strong>increased from 2053 to 2503</strong> bytes.</p>
-<p><strong><code>|</code></strong> The default way to compile submissions is now <code>-std=gnu17 -O3 -g3 -Wall -Wextra -pedantic</code>. See below for more details about the example Makefile
+<p><strong><code>|</code></strong> The new default way to compile submissions: <code>-std=gnu17 -O3 -g3 -Wall -Wextra -pedantic</code>. See below for more details about the example Makefile
 for more help.</p>
 <p><strong><code>|</code></strong> Submissions are in the form of a single xz compressed tarball.</p>
 <p><strong><code>|</code></strong> To assist in the formation of the xz compressed tarball for submission, use the
@@ -565,11 +565,13 @@ ASCII formfeed, and ASCII carriage return.</p>
 <p>In cases where the above summary and the algorithm implemented by
 the IOCCC size tool source code conflict, the algorithm implemented
 by the IOCCC size tool source code is preferred by the judges.</p>
-<p><strong><code>|</code></strong> There are at least 2 other reasons for selecting 2503 as the 2nd limit<br>
+<p><strong><code>|</code></strong> There are at least 2 other reasons for selecting<br>
-<strong><code>|</code></strong> besides the fact that 2503 is a prime. These reasons<br>
+<strong><code>|</code></strong> 2503 as the 2nd limit besides the fact that 2503<br>
-<strong><code>|</code></strong> may be searched for and discovered if you are <a href="https://t5k.org/curios/page.php/2503.html">“Curios!” about 2503</a>. :-)<br>
+<strong><code>|</code></strong> is a prime. These reasons may be searched for<br>
-<strong><code>|</code></strong> Moreover, 2053 was the number of the kernel disk pack of one of the<br>
+<strong><code>|</code></strong> and discovered if you are <a href="https://t5k.org/curios/page.php/2503.html">“Curios!” about 2503</a>. :-)<br>
-<strong><code>|</code></strong> judge’s BESM-6, and 2503 is a decimal anagram of 2053.</p>
+<strong><code>|</code></strong> Moreover, 2053 was the number of the kernel disk<br>
+<strong><code>|</code></strong> pack of one of the judge’s BESM-6, and 2503 is a<br>
+<strong><code>|</code></strong> decimal anagram of 2053.</p>
 <p>Take note that this secondary limit imposed by the IOCCC size tool
 obviates some of the need to <code>#define</code> C reserved words in an effort
 to get around the size limits of <a href="rules.html#rule2">Rule 2</a>.</p>
@@ -589,7 +591,8 @@ you may wish to validate each part individually. As the <a href="rules.html">rul
 state, each of these tools have a <code>-h</code> option. However, to help simplify
 matters, we give you a brief overview below.</p>
 <p><strong><code>|</code></strong> The synopsis of the <code>mkiocccentry(1)</code> tool is:</p>
-<pre><code>    ./mkiocccentry [options] work_dir prog.c Makefile remarks.md [file ...]</code></pre>
+<pre><code>    ./mkiocccentry [options] work_dir prog.c \
+         Makefile remarks.md [file ...]</code></pre>
 <p><strong><code>|</code></strong> where the <code>work_dir</code> is a directory that is used to form the
 xz compressed tarball that <code>txzchk(1)</code> validates, <code>prog.c</code> is your submission
 source code, <code>Makefile</code> is your <code>Makefile</code>, <code>remarks.md</code> is your remarks and
@@ -603,28 +606,34 @@ tool will also do a rudimentary check on the <code>Makefile</code> and run other
 well. You can override warnings but doing so puts you at risk of violating
 <a href="rules.html">rules</a>.</p>
 <p><strong><code>|</code></strong> 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
+tarball <strong>will not be formed</strong>. For instance, if <code>chkentry(1)</code> fails to validate
-<code>.auth.json</code> or <code>.info.json</code> JSON files that <code>mkiocccentry(1)</code> creates, it is an error and
+the <code>.auth.json</code> or <code>.info.json</code> <a href="https://www.json.org/json-en.html">JSON</a> files
-possibly a bug that you should report at the <a href="https://github.com/ioccc-src/mkiocccentry/issues">mkiocccentry issues
+that <code>mkiocccentry(1)</code> creates, it is an error and possibly a bug that you
-page</a>.</p>
+should report at the <a href="https://github.com/ioccc-src/mkiocccentry/issues">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><strong><code>|</code></strong> Assuming that <code>chkentry(1)</code> passes for 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> should
+executed. In this case, there should be no problems as <code>mkiocccentry(1)</code> would
 <strong>NOT</strong> form a tarball if there are any issues.</p>
 <p><strong><code>|</code></strong> <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 then it is very
+compressed tarball and if any issues (<code>feathers</code> :-) ) are found and if you used
-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
+<code>mkiocccentry(1)</code>, then it is very possibly a bug in one of the tools and you
-issues page</a>.</p>
+should report it at the <a href="https://github.com/ioccc-src/mkiocccentry/issues">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><strong><code>|</code></strong> 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
 is flagged by <code>txzchk(1)</code> but it is not an error if you wish to ignore it.
 Ignoring this, however, risks violating <a href="rules.html#rule17">Rule 17</a> which is a
-big risk.</p>
+big risk. Of course, using <code>mkiocccentry(1)</code> would prevent this from happening.</p>
-<p><strong><code>|</code></strong> <code>txzchk(1)</code> will show the contents of the tarball which is how the
+<p><strong><code>|</code></strong> By default, <code>txzchk(1)</code> will show the contents of the tarball which is
-<code>mkiocccentry(1)</code> shows you the tarball contents for you to review.</p>
+how the <code>mkiocccentry(1)</code> shows you the tarball contents for you to review.</p>
 <p><strong><code>|</code></strong> 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 answers.txt try:</p>
+the information again. To write to <code>answers.txt</code> try:</p>
 <pre><code>    ./mkiocccentry -a answers.txt ...</code></pre>
 <p><strong><code>|</code></strong> 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
@@ -641,7 +650,7 @@ contents of the tarball and the words:</p>
 <p>No feathers stuck in tarball.</p>
 </blockquote>
 <p><strong><code>|</code></strong> If you give the option <code>-q</code> it will not report anything unless there
-are certain error conditions, for instance <code>fnamchk(1)</code> reports there is a
+are certain error conditions, for instance if <code>fnamchk(1)</code> reports there is a
 problem with the filename; if <code>txzchk(1)</code> exits 0 then there are no problems
 detected.</p>
 <p><strong><code>|</code></strong> If you wish to run <code>fnamchk(1)</code> directly you can do so like:</p>
@@ -656,20 +665,30 @@ should use <code>chkentry(1)</code>. <code>chkentry(1)</code> accepts more than
 If you pass a single argument, it is expected to be a directory that has both
 <code>.auth.json</code> and <code>.info.json</code> in it. You can also specify a <code>.auth.json</code> and/or
 <code>.info.json</code> file. An argument of <code>.</code> will skip that file. For instance:</p>
-<pre><code>    ./chkentry test_work   # tests entry directory test_work
+<pre><code>    # test entry directory test_work:
+    ./chkentry test_work
 
-    ./chkentry .info.json .  # run checks on .info.json file
+    # run checks on .info.json:
+    ./chkentry .info.json .
 
-    ./chkentry . .auth.json  # run checks on .auth.json
+    # run checks on .auth.json:
+    ./chkentry . .auth.json
 
-    ./chkentry .info.json .auth.json  # run check on both files</code></pre>
+    # run checks on .info.json and .auth.json:
-<p><strong><code>|</code></strong> If there is a JSON error detected by <code>jparse(8)</code>, then it is an error
+    ./chkentry .info.json .auth.json</code></pre>
-and <code>chkentry(1)</code> will report this. If an issue is found in one or both of the
+<p><strong><code>|</code></strong> If there is a <a href="https://www.json.org/json-en.html">JSON</a> issue detected
-JSON files it will also report this.</p>
+by <code>jparse(8)</code>, <strong>then there is a <a href="https://www.json.org/json-en.html">JSON</a>
-<p><strong><code>|</code></strong> At the risk of stating the obvious: you run a very big risk of having
+error and <code>chkentry(1)</code> will report it as an <em>error</em></strong>. If the parsing is OK <strong>but
-your submission rejected if you package your own tarball and there are any
+there <em>is an issue</em> in one or both of the
-problems. Even if everything checks out OK you should not expect that everything
+<a href="https://www.json.org/json-en.html">JSON</a></strong> files <strong>in the context of the IOCCC</strong>,
-<strong>IS</strong> OK.</p>
+<em>it will <strong>report this as an error</strong></em>. Thus, if you were to package this manually
+then you would be violating <a href="rules.html#rule17">Rule 17</a>.</p>
+<p><strong><code>|</code></strong> At the risk of stating the obvious: you run <strong>a very big risk</strong> of having
+your submission rejected if you package your own tarball and there are <strong>any
+problems</strong>. For instance, if <code>chkentry(1)</code> found a problem in your <code>.info.json</code>
+file, the <code>mkiocccentry(1)</code> tool would not package it. But if you were to package
+it manually, you would be violating <a href="rules.html#rule17">Rule 17</a>. But even if
+everything checks out OK you should not expect that everything <strong>IS</strong> OK.</p>
 <p><strong><code>|</code></strong> As you can see, the use of <code>mkiocccentry(1)</code> is <strong>HIGHLY RECOMMENDED</strong>.</p>
 <p><strong><code>|</code></strong> We recommend that you use the
 <a href="https://github.com/ioccc-src/mkiocccentry/blob/master/Makefile.example">example Makefile</a>
@@ -854,7 +873,7 @@ interfaces to their compilers, once one learns how to invoke a shell.</p>
 Specification</a>
 environment. Therefore do not assume the system has a
 <a href="https://en.wikipedia.org/wiki/Windows.h">windows.h</a> include file:</p>
-<pre><code>    #include &lt;windows.h&gt;        /* we DISLIKE this include */</code></pre>
+<pre><code>    #include &lt;windows.h&gt;  /* we DISLIKE this */</code></pre>
 <p>Unless you are cramped for space, or unless you are entering the
 ‘<strong>Best one liner</strong>’ category, we suggest that you format your program
 in a more creative way than simply forming excessively long lines.</p>
@@ -885,7 +904,9 @@ absolute one. The intent is to ensure that the building if your
 program is reasonably portable.</p>
 <p>We prefer programs that are portable across a wide variety of Unix-like
 operating systems (e.g., Linux, GNU Hurd, BSD, Unix, etc.).</p>
+<blockquote>
 <p>You are in a maze of twisty <em>guidelines</em>, all different.</p>
+</blockquote>
 <p>There are at least zero judges who think that
 <a href="https://en.wikipedia.org/wiki/Fideism">Fideism</a> has little
 or nothing to do with the IOCCC judging process.</p>
@@ -975,12 +996,12 @@ particular window manager.</p>
 <p><strong><code>|</code></strong> You are <strong>well advised</strong> to submit entries that conform to the <a href="https://unix.org/version4/overview.html">Single UNIX Specification Version 4</a>.</p>
 <p><strong><code>|</code></strong> To quote the <a href="../judges.html">IOCCC judges</a>:</p>
 <blockquote>
-<p>You very well might not be completely be prohibited from failing to not<br>
+<p>You very well might not be completely be prohibited from failing to not partly
-partly misunderstand this particular <em>guideline</em>, but of course, we could<br>
+misunderstand this particular <em>guideline</em>, but of course, we could not possibly
-not possibly comment! :-) Nevertheless, you are neither prohibited, nor are<br>
+comment! :-) Nevertheless, you are neither prohibited, nor are you fully
-you fully required to determine that this or the previous sentence is either false<br>
+required to determine that this or the previous sentence is either false and/or
-and/or perhaps misleading. Therefore, it might be wise for you to not fail to<br>
+perhaps misleading. Therefore, it might be wise for you to not fail to consider
-consider to not do so, accordingly. Thank you very much.</p>
+to not do so, accordingly. Thank you very much.</p>
 </blockquote>
 <p>Any complaints about the above <em>guideline</em> could be addressed to the
 Speaker of the House of Commons, or to the speaker of your national
@@ -1231,10 +1252,9 @@ This is one of the reasons why the <a href="rules.html">IOCCC rules</a> and
 </div>
 <p>Entries are judged by Leonid A. Broukhis and Landon Curt Noll.</p>
 <p>Each submission submitted is given a random id number and subdirectory. The
-submission files including, but not limited to <code>prog.c</code>, <code>Makefile</code> (that we
+submission files including, but not limited to <code>prog.c</code>, <code>Makefile</code>,
-form from your submitted <code>Makefile</code> and any additional “<strong>how to build</strong>”
+<code>remarks.md</code> as well as any data files that you submit, are all placed under
-information you provide), as well as any data files that you submit are all
+their own directory and stored and judged from this directory.</p>
-placed under their own directory and stored and judged from this directory.</p>
 <p>Any information about the authors is not read by the judges until
 the judging process is complete, and then only from entries that have
 won an award. Because we do not read this information for entries that

next/guidelines.md

@@ -43,7 +43,7 @@ writing by [contacting the judges](../contact.html).
 ## IOCCC Guidelines version
 </div>
 
-**`|`**   These [IOCCC guidelines](guidelines.html) are version **28.3 2024-07-01**.
+**`|`**   These [IOCCC guidelines](guidelines.html) are version **28.4 2024-07-02**.
 
 **IMPORTANT**: Be **SURE** to read the [IOCCC rules](rules.html).
 
@@ -109,7 +109,7 @@ IOCCC submission URL.
 
 **`|`**   The [Rule 2b](rules.html#rule2b) size has **increased from 2053 to 2503** bytes.
 
-**`|`**   The default way to compile submissions is now `-std=gnu17 -O3 -g3
+**`|`**   The new default way to compile submissions: `-std=gnu17 -O3 -g3
 -Wall -Wextra -pedantic`. See below for more details about the example Makefile
 for more help.
 
@@ -249,11 +249,13 @@ In cases where the above summary and the algorithm implemented by
 the IOCCC size tool source code conflict, the algorithm implemented
 by the IOCCC size tool source code is preferred by the judges.
 
-**`|`**   There are at least 2 other reasons for selecting 2503 as the 2nd limit<br>
+**`|`**   There are at least 2 other reasons for selecting<br>
-**`|`**   besides the fact that 2503 is a prime.  These reasons<br>
+**`|`**   2503 as the 2nd limit besides the fact that 2503<br>
-**`|`**   may be searched for and discovered if you are ["Curios!" about 2503](https://t5k.org/curios/page.php/2503.html). :-)<br>
+**`|`**   is a prime. These reasons may be searched for<br>
-**`|`**   Moreover, 2053 was the number of the kernel disk pack of one of the<br>
+**`|`**   and discovered if you are ["Curios!" about 2503](https://t5k.org/curios/page.php/2503.html). :-)<br>
-**`|`**   judge's BESM-6, and 2503 is a decimal anagram of 2053.
+**`|`**   Moreover, 2053 was the number of the kernel disk<br>
+**`|`**   pack of one of the judge's BESM-6, and 2503 is a<br>
+**`|`**   decimal anagram of 2053.
 
 Take note that this secondary limit imposed by the IOCCC size tool
 obviates some of the need to `#define` C reserved words in an effort
@@ -283,7 +285,8 @@ matters, we give you a brief overview below.
 **`|`**   The synopsis of the `mkiocccentry(1)` tool is:
 
 ``` <!---sh-->
-    ./mkiocccentry [options] work_dir prog.c Makefile remarks.md [file ...]
+    ./mkiocccentry [options] work_dir prog.c \
+         Makefile remarks.md [file ...]
 ```
 
 **`|`** where the `work_dir` is a directory that is used to form the
@@ -302,33 +305,40 @@ well. You can override warnings but doing so puts you at risk of violating
 [rules](rules.html).
 
 **`|`**   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
+tarball **will not be formed**. For instance, if `chkentry(1)` fails to validate
-`.auth.json` or `.info.json` JSON files that `mkiocccentry(1)` creates, it is an error and
+the `.auth.json` or `.info.json` [JSON](https://www.json.org/json-en.html) files
-possibly a bug that you should report at the [mkiocccentry issues
+that `mkiocccentry(1)` creates, it is an error and possibly a bug that you
-page](https://github.com/ioccc-src/mkiocccentry/issues).
+should report at the [mkiocccentry issues
+page](https://github.com/ioccc-src/mkiocccentry/issues). **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).
+
 
 **`|`**   Assuming that `chkentry(1)` passes for 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)` should
+executed. In this case, there should be no problems as `mkiocccentry(1)` would
 **NOT** form a tarball if there are any issues.
 
 **`|`**  `txzchk(1)` performs a wide number of sanity checks on the xz
-compressed tarball and if any issues (`feathers` :-) ) are found then it is very
+compressed tarball and if any issues (`feathers` :-) ) are found and if you used
-possibly a bug in one of the tools and you should report it at the [mkiocccentry
+`mkiocccentry(1)`, then it is very possibly a bug in one of the tools and you
-issues page](https://github.com/ioccc-src/mkiocccentry/issues).
+should report it at the [mkiocccentry issues
+page](https://github.com/ioccc-src/mkiocccentry/issues). **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).
 
 **`|`**  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
 is flagged by `txzchk(1)` but it is not an error if you wish to ignore it.
 Ignoring this, however, risks violating [Rule 17](rules.html#rule17) which is a
-big risk.
+big risk. Of course, using `mkiocccentry(1)` would prevent this from happening.
 
-**`|`**  `txzchk(1)` will show the contents of the tarball which is how the
+**`|`**  By default, `txzchk(1)` will show the contents of the tarball which is
-`mkiocccentry(1)` shows you the tarball contents for you to review.
+how the `mkiocccentry(1)` shows you the tarball contents for you to review.
 
 **`|`**  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 again. To write to `answers.txt` try:
 
 ``` <!---sh-->
     ./mkiocccentry -a answers.txt ...
@@ -358,7 +368,7 @@ contents of the tarball and the words:
 > No feathers stuck in tarball.
 
 **`|`**  If you give the option `-q` it will not report anything unless there
-are certain error conditions, for instance `fnamchk(1)` reports there is a
+are certain error conditions, for instance if `fnamchk(1)` reports there is a
 problem with the filename; if `txzchk(1)` exits 0 then there are no problems
 detected.
 
@@ -381,27 +391,36 @@ If you pass a single argument, it is expected to be a directory that has both
 `.info.json` file. An argument of `.` will skip that file. For instance:
 
 ``` <!---sh-->
-    ./chkentry test_work   # tests entry directory test_work
+    # test entry directory test_work:
+    ./chkentry test_work
 
-    ./chkentry .info.json .  # run checks on .info.json file
+    # run checks on .info.json:
+    ./chkentry .info.json .
 
-    ./chkentry . .auth.json  # run checks on .auth.json
+    # run checks on .auth.json:
+    ./chkentry . .auth.json
 
-    ./chkentry .info.json .auth.json  # run check on both files
+    # run checks on .info.json and .auth.json:
+    ./chkentry .info.json .auth.json
 ```
 
-**`|`**  If there is a JSON error detected by `jparse(8)`, then it is an error
+**`|`**  If there is a [JSON](https://www.json.org/json-en.html) issue detected
-and `chkentry(1)` will report this. If an issue is found in one or both of the
+by `jparse(8)`, **then there is a [JSON](https://www.json.org/json-en.html)
-JSON files it will also report this.
+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**,
+_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).
 
-**`|`** At the risk of stating the obvious: you run a very big risk of having
+**`|`** At the risk of stating the obvious: you run **a very big risk** of having
-your submission rejected if you package your own tarball and there are any
+your submission rejected if you package your own tarball and there are **any
-problems. Even if everything checks out OK you should not expect that everything
+problems**. For instance, if `chkentry(1)` found a problem in your `.info.json`
-**IS** OK.
+file, the `mkiocccentry(1)` tool would not package it. But if you were to package
+it manually, you would be violating [Rule 17](rules.html#rule17). But even if
+everything checks out OK you should not expect that everything **IS** OK.
 
 **`|`** As you can see, the use of `mkiocccentry(1)` is **HIGHLY RECOMMENDED**.
 
-
 **`|`**   We recommend that you use the
 [example Makefile](https://github.com/ioccc-src/mkiocccentry/blob/master/Makefile.example)
 from the [IOCCC mkiocccentry repo](https://github.com/ioccc-src/mkiocccentry).
@@ -671,8 +690,9 @@ Specification](https://en.wikipedia.org/wiki/Single_UNIX_Specification)
 environment. Therefore do not assume the system has a
 [windows.h](https://en.wikipedia.org/wiki/Windows.h) include file:
 
+
 ``` <!---c-->
-    #include <windows.h>        /* we DISLIKE this include */
+    #include <windows.h>  /* we DISLIKE this */
 ```
 
 Unless you are cramped for space, or unless you are entering the
@@ -714,7 +734,7 @@ program is reasonably portable.
 We prefer programs that are portable across a wide variety of Unix-like
 operating systems (e.g., Linux, GNU Hurd, BSD, Unix, etc.).
 
-You are in a maze of twisty _guidelines_, all different.
+> You are in a maze of twisty _guidelines_, all different.
 
 There are at least zero judges who think that
 [Fideism](https://en.wikipedia.org/wiki/Fideism) has little
@@ -846,12 +866,12 @@ particular window manager.
 
 **`|`**   To quote the [IOCCC judges](../judges.html):
 
-> You very well might not be completely be prohibited from failing to not<br>
+> You very well might not be completely be prohibited from failing to not partly
-> partly misunderstand this particular _guideline_, but of course, we could<br>
+misunderstand this particular _guideline_, but of course, we could not possibly
-> not possibly comment!  :-)  Nevertheless, you are neither prohibited, nor are<br>
+comment!  :-)  Nevertheless, you are neither prohibited, nor are you fully
-> you fully required to determine that this or the previous sentence is either false<br>
+required to determine that this or the previous sentence is either false and/or
-> and/or perhaps misleading.  Therefore, it might be wise for you to not fail to<br>
+perhaps misleading.  Therefore, it might be wise for you to not fail to consider
-> consider to not do so, accordingly. Thank you very much.
+to not do so, accordingly. Thank you very much.
 
 Any complaints about the above _guideline_ could be addressed to the
 Speaker of the House of Commons, or to the speaker of your national
@@ -1153,10 +1173,9 @@ This is one of the reasons why the [IOCCC rules](rules.html) and
 Entries are judged by Leonid A. Broukhis and Landon Curt Noll.
 
 Each submission submitted is given a random id number and subdirectory.  The
-submission files including, but not limited to `prog.c`, `Makefile` (that we
+submission files including, but not limited to `prog.c`, `Makefile`,
-form from your submitted `Makefile` and any additional "**how to build**"
+`remarks.md` as well as any data files that you submit, are all placed under
-information you provide), as well as any data files that you submit are all
+their own directory and stored and judged from this directory.
-placed under their own directory and stored and judged from this directory.
 
 Any information about the authors is not read by the judges until
 the judging process is complete, and then only from entries that have

next/rules.html

@@ -413,7 +413,7 @@ writing by <a href="../contact.html">contacting the judges</a>.</p>
 <div id="rules_version">
 <h2 id="ioccc-rules-version">IOCCC Rules version</h2>
 </div>
-<p><strong><code>|</code></strong> These <a href="rules.html">IOCCC rules</a> are version <strong>28.3 2024-07-01</strong>.</p>
+<p><strong><code>|</code></strong> These <a href="rules.html">IOCCC rules</a> are version <strong>28.4 2024-07-02</strong>.</p>
 <p><strong>IMPORTANT</strong>: Be sure to read the <a href="guidelines.html">IOCCC guidelines</a>.</p>
 <div id="change_marks">
 <h3 id="change-marks">Change marks</h3>
@@ -683,13 +683,13 @@ the following files:</p>
 <li><code>.info.json</code></li>
 <li><code>.auth.json</code></li>
 </ul>
-<p><strong><code>|</code></strong> The <code>.info.json</code> must be valid JSON and pass the <code>chkentry(1)</code> test.</p>
+<p><strong><code>|</code></strong> The <code>.info.json</code> must be valid JSON and pass the <code>chkentry(1)</code> tests.</p>
-<p><strong><code>|</code></strong> The <code>.auth.json</code> must be valid JSON and pass the <code>chkentry(1)</code> test.</p>
+<p><strong><code>|</code></strong> The <code>.auth.json</code> must be valid JSON and pass the <code>chkentry(1)</code> tests.</p>
 <p><strong><code>|</code></strong> You submission may have additional files, however the filenames of those additional files <strong>MUST</strong>:</p>
-<ul>
+<p><strong><code>|</code></strong> * Be less than <strong>100</strong> characters in length<br>
-<li>Be less than <strong>100</strong> characters in length</li>
+<strong><code>|</code></strong> * Match the regular expression: <code>^[0-9A-Za-z][0-9A-Za-z._+-]*$</code></p>
-<li>Match the regular expression: <code>^[0-9A-Za-z][0-9A-Za-z._+-]*$</code></li>
+<p><strong><code>|</code></strong> The <code>mkiocccentry(1)</code> tool will not package any files that do not meet
-</ul>
+those requirements.</p>
 <p><strong><code>|</code></strong> The <code>Makefile</code> must be a non-empty file in <a href="https://www.gnu.org/software/make/manual/make.html">GNU
 Makefile</a> form. See the
 <a href="https://github.com/ioccc-src/mkiocccentry/blob/master/Makefile.example">Makefile.example</a>,
@@ -727,20 +727,34 @@ by the <code>mkiocccentry(1)</code> tool):</p>
 only be looked at if the submission wins).</li>
 <li><code>.info.json</code> which contains information about the entry.</li>
 </ul>
-<p><strong><code>|</code></strong> The <code>txzchk(1)</code> tool will verify these for you and the <code>chkentry(1)</code>
+<p><strong><code>|</code></strong> The <code>txzchk(1)</code> tool will verify these (and other things) for you and
-tool will do additional checks on the contents of the <code>.auth.json</code> and
+the <code>chkentry(1)</code> tool will do additional checks on the contents of the
-<code>.info.json</code> files.</p>
+<code>.auth.json</code> and <code>.info.json</code> files.</p>
 <p><strong><code>|</code></strong> The tarball filename <strong>MUST</strong> pass <code>fnamchk(1)</code>; the tool <code>txzchk(1)</code>
-which is run by <code>mkiocccentry(1)</code> <strong>before packaging your tarball</strong> will run
+will run <code>fnamchk(1)</code> as part of its algorithm. If you use <code>mkiocccentry(1)</code>
-<code>fnamchk(1)</code>.</p>
+there should be no problem but if you were to package things manually it is
+possible there could be a problem.</p>
+<p><strong><code>|</code></strong> The <code>fnamchk(1)</code>, which <code>txzchk(1)</code> executes, will verify that the
+filename is correct.</p>
 <p><strong><code>|</code></strong> These checks <strong>MUST PASS</strong>.</p>
 <p><strong><code>|</code></strong> Where <a href="#rule17">Rule 17</a> and the tools from the latest
 release of the <a href="https://github.com/ioccc-src/mkiocccentry">mkiocccentry repo</a>
 conflict, the <a href="../judges.html">IOCCC Judges</a> will use their best judgment which
 is likely to favor <a href="https://github.com/ioccc-src/mkiocccentry">mkiocccentry repo</a> code.</p>
-<p><strong><code>|</code></strong> This means you <strong>MAKE SURE</strong> that you use <code>mkiocccentry(1)</code> to
+<p><strong><code>|</code></strong> This means you should <strong>MAKE SURE</strong> that you use <code>mkiocccentry(1)</code> to
 package your submission; <code>mkiocccentry(1)</code> will run the above mentioned tools
-<strong>before</strong> creating the tarball.</p>
+(that do not act on the tarball) <strong>before</strong> creating the tarball and after the
+tarball is created it will then verify that the tarball is okay by running
+<code>txzchk(1)</code> on it.</p>
+<p><strong><code>|</code></strong> These tools will link in the <code>jparse(8)</code> library and <code>chkentry(1)</code>
+actually uses the parser to validate the
+<a href="https://www.json.org/json-en.html">JSON</a>.</p>
+<p><strong><code>|</code></strong> If you run into a problem with one or more of these tools, <strong>PLEASE</strong>
+report it at the <a href="https://github.com/ioccc-src/mkiocccentry/issues">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
+repo</a>.</p>
 <p><strong><code>|</code></strong> To state the obvious: submissions that violate <a href="#rule17">Rule 17</a> <strong>will be rejected</strong>,
 so be sure to use the latest release of the <a href="https://github.com/ioccc-src/mkiocccentry">mkiocccentry repo</a>,
 to form and test your submission’s xz compressed tarball.</p>

next/rules.md

@@ -43,7 +43,7 @@ writing by [contacting the judges](../contact.html).
 ## IOCCC Rules version
 </div>
 
-**`|`**   These [IOCCC rules](rules.html) are version **28.3 2024-07-01**.
+**`|`**   These [IOCCC rules](rules.html) are version **28.4 2024-07-02**.
 
 **IMPORTANT**: Be sure to read the [IOCCC guidelines](guidelines.html).
 
@@ -443,14 +443,17 @@ the following files:
 * `.info.json`
 * `.auth.json`
 
-**`|`**   The `.info.json` must be valid JSON and pass the `chkentry(1)` test.
+**`|`**   The `.info.json` must be valid JSON and pass the `chkentry(1)` tests.
 
-**`|`**   The `.auth.json` must be valid JSON and pass the `chkentry(1)` test.
+**`|`**   The `.auth.json` must be valid JSON and pass the `chkentry(1)` tests.
 
 **`|`**   You submission may have additional files, however the filenames of those additional files **MUST**:
 
-* Be less than **100** characters in length
+**`|`** * Be less than **100** characters in length<br>
-* Match the regular expression: `^[0-9A-Za-z][0-9A-Za-z._+-]*$`
+**`|`** * Match the regular expression: `^[0-9A-Za-z][0-9A-Za-z._+-]*$`
+
+**`|`**   The `mkiocccentry(1)` tool will not package any files that do not meet
+those requirements.
 
 **`|`**   The `Makefile` must be a non-empty file in [GNU
 Makefile](https://www.gnu.org/software/make/manual/make.html) form. See the
@@ -496,13 +499,17 @@ by the `mkiocccentry(1)` tool):
 only be looked at if the submission wins).
 * `.info.json` which contains information about the entry.
 
-**`|`** The `txzchk(1)` tool will verify these for you and the `chkentry(1)`
+**`|`** The `txzchk(1)` tool will verify these (and other things) for you and
-tool will do additional checks on the contents of the `.auth.json` and
+the `chkentry(1)` tool will do additional checks on the contents of the
-`.info.json` files.
+`.auth.json` and `.info.json` files.
 
 **`|`** The tarball filename **MUST** pass `fnamchk(1)`; the tool `txzchk(1)`
-which is run by `mkiocccentry(1)` **before packaging your tarball** will run
+will run `fnamchk(1)` as part of its algorithm. If you use `mkiocccentry(1)`
-`fnamchk(1)`.
+there should be no problem but if you were to package things manually it is
+possible there could be a problem.
+
+**`|`** The `fnamchk(1)`, which `txzchk(1)` executes, will verify that the
+filename is correct.
 
 **`|`** These checks **MUST PASS**.
 
@@ -511,9 +518,22 @@ release of the [mkiocccentry repo](https://github.com/ioccc-src/mkiocccentry)
 conflict, the [IOCCC Judges](../judges.html) will use their best judgment which
 is likely to favor [mkiocccentry repo](https://github.com/ioccc-src/mkiocccentry) code.
 
-**`|`** This means you **MAKE SURE** that you use `mkiocccentry(1)` to
+**`|`** This means you should **MAKE SURE** that you use `mkiocccentry(1)` to
 package your submission; `mkiocccentry(1)` will run the above mentioned tools
-**before** creating the tarball.
+(that do not act on the tarball) **before** creating the tarball and after the
+tarball is created it will then verify that the tarball is okay by running
+`txzchk(1)` on it.
+
+**`|`** These tools will link in the `jparse(8)` library and `chkentry(1)`
+actually uses the parser to validate the
+[JSON](https://www.json.org/json-en.html).
+
+**`|`** If you run into a problem with one or more of these tools, **PLEASE**
+report it at the [mkiocccentry issues
+page](https://github.com/ioccc-src/mkiocccentry/issues), **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
+repo](../faq.html#mkiocccentry_bugs).
 
 **`|`**  To state the obvious: submissions that violate [Rule 17](#rule17) **will be rejected**,
 so be sure to use the latest release of the [mkiocccentry repo](https://github.com/ioccc-src/mkiocccentry),