Merge pull request #55 from xexyl/tarballs

Add details on submitting extra files

faq.html

@@ -425,7 +425,7 @@
 
 <!-- BEFORE: 1st line of markdown file: faq.md -->
 <h1 id="ioccc-faq-table-of-contents">IOCCC FAQ Table of Contents</h1>
-<p>This is FAQ version <strong>28.2.0 2025-01-16</strong>.</p>
+<p>This is FAQ version <strong>28.2.1 2025-01-18</strong>.</p>
 <h2 id="entering-the-ioccc-the-bare-minimum-you-need-to-know">0. <a href="#enter_questions">Entering the IOCCC: the bare minimum you need to know</a></h2>
 <ul>
 <li><strong>Q 0.0</strong>: <a class="normal" href="#enter">How can I enter the IOCCC?</a></li>
@@ -448,7 +448,8 @@
 <li><strong>Q 1.2</strong>: <a class="normal" href="#markdown">What is markdown and how does the IOCCC use it?</a></li>
 <li><strong>Q 1.3</strong>: <a class="normal" href="#mkiocccentry_bugs">How do I report bugs in an <code>mkiocccentry</code> tool?</a></li>
 <li><strong>Q 1.4</strong>: <a class="normal" href="#subdirectories">How may I use subdirectories in my submission if Rule 17 disallows them?</a></li>
-<li><strong>Q 1.5</strong>: <a class="normal" href="#mkiocccentry_test">How can I test my submission passes tests without having to answer questions?</a></li>
+<li><strong>Q 1.5</strong>: <a class="normal" href="#mkiocccentry_test">How can I check if my submission passes tests without having to answer questions?</a></li>
+<li><strong>Q 1.6</strong>: <a class="normal" href="#extra-files">How may I include additional files beyond the max allowed?</a></li>
 </ul>
 <h2 id="ioccc-judging-process">2. <a href="#judging">IOCCC Judging process</a></h2>
 <ul>
@@ -967,7 +968,7 @@ tarball does not exceed the limit, defined as <code>MAX_FILE_COUNT</code> in
 <a href="https://github.com/ioccc-src/mkiocccentry/blob/master/soup/limit_ioccc.h">limit_ioccc.h</a>,
 you can include tarballs with subdirectories or other files.</p>
 <div id="mkiocccentry_test">
-<h4 id="q-1.5-how-can-i-test-my-submission-passes-tests-without-having-to-answer-questions">Q 1.5: How can I test my submission passes tests without having to answer questions?</h4>
+<h4 id="q-1.5-how-can-i-check-if-my-submission-passes-tests-without-having-to-answer-questions">Q 1.5: How can I check if my submission passes tests without having to answer questions?</h4>
 </div>
 <p>In case you do not have a UUID or you simply want to test if <code>mkiocccentry(1)</code>
 does not detect any issues with your submission, without having to answer all
@@ -991,6 +992,25 @@ FAQ on”<a href="#txzchk">txzchk</a>”
 and the
 FAQ on “<a href="#fnamchk">fnamchk</a>”
 for more details.</p>
+<div id="extra-files">
+<h1 id="how-may-i-include-additional-files-beyond-the-max-allowed">How may I include additional files beyond the max allowed?</h1>
+</div>
+<p>The rules state:</p>
+<blockquote>
+<p>The maximum number of files your submission tarball may contain, not counting
+the optional files (<code>prog.alt.c</code>, <code>try.sh</code>, <code>try.alt.sh</code>) and the mandatory
+files (<code>prog.c</code>, <code>Makefile</code>, <code>remarks.md</code>) is 31.</p>
+</blockquote>
+<p>If you need to include more files than this, you may include a tarball as an
+<strong>EXTRA</strong> file.</p>
+<p>This file does <strong>NOT</strong> need to pass the <code>txzchk(1)</code> tests; only your submission
+tarball needs to pass these tests.</p>
+<p>Please pay careful attention to <a href="next/rules.html#rule17">Rule 17</a> and in
+particular the part about the <a href="next/rules.html#max-files">maximum number of files per
+submission</a>, which not only discusses the maximum
+number of files (including extra files) but also specific rules you must follow
+if you do include a tarball. Not following these points puts you at great risk
+of violating <a href="next/rules.html#rule17">Rule 17</a>!</p>
 <hr style="width:50%;text-align:left;margin-left:0">
 <hr style="width:50%;text-align:left;margin-left:0">
 <div id="judging">

faq.md

@@ -1,6 +1,6 @@
 # IOCCC FAQ Table of Contents
 
-This is FAQ version **28.2.0 2025-01-16**.
+This is FAQ version **28.2.1 2025-01-18**.
 
 
 ## 0. [Entering the IOCCC: the bare minimum you need to know](#enter_questions)
@@ -22,7 +22,8 @@ This is FAQ version **28.2.0 2025-01-16**.
 - **Q 1.2**: <a class="normal" href="#markdown">What is markdown and how does the IOCCC use it?</a>
 - **Q 1.3**: <a class="normal" href="#mkiocccentry_bugs">How do I report bugs in an `mkiocccentry` tool?</a>
 - **Q 1.4**: <a class="normal" href="#subdirectories">How may I use subdirectories in my submission if Rule 17 disallows them?</a>
-- **Q 1.5**: <a class="normal" href="#mkiocccentry_test">How can I test my submission passes tests without having to answer questions?</a>
+- **Q 1.5**: <a class="normal" href="#mkiocccentry_test">How can I check if my submission passes tests without having to answer questions?</a>
+- **Q 1.6**: <a class="normal" href="#extra-files">How may I include additional files beyond the max allowed?</a>
 
 
 ## 2. [IOCCC Judging process](#judging)
@@ -662,7 +663,7 @@ tarball does not exceed the limit, defined as `MAX_FILE_COUNT` in
 you can include tarballs with subdirectories or other files.
 
 <div id="mkiocccentry_test">
-#### Q 1.5: How can I test my submission passes tests without having to answer questions?
+#### Q 1.5: How can I check if my submission passes tests without having to answer questions?
 </div>
 
 In case you do not have a UUID or you simply want to test if `mkiocccentry(1)`
@@ -696,6 +697,29 @@ FAQ on "[fnamchk](#fnamchk)"
 for more details.
 
 
+<div id="extra-files">
+# How may I include additional files beyond the max allowed?
+</div>
+
+The rules state:
+
+> The maximum number of files your submission tarball may contain, not counting
+the optional files (`prog.alt.c`, `try.sh`, `try.alt.sh`) and the mandatory
+files (`prog.c`, `Makefile`, `remarks.md`) is 31.
+
+If you need to include more files than this, you may include a tarball as an
+**EXTRA** file.
+
+This file does **NOT** need to pass the `txzchk(1)` tests; only your submission
+tarball needs to pass these tests.
+
+Please pay careful attention to [Rule 17](next/rules.html#rule17) and in
+particular the part about the [maximum number of files per
+submission](next/rules.html#max-files), which not only discusses the maximum
+number of files (including extra files) but also specific rules you must follow
+if you do include a tarball. Not following these points puts you at great risk
+of violating [Rule 17](next/rules.html#rule17)!
+
 <hr style="width:50%;text-align:left;margin-left:0">
 <hr style="width:50%;text-align:left;margin-left:0">
 

next/guidelines.html

@@ -461,7 +461,7 @@ writing by <a href="../contact.html">contacting the judges</a>.</p>
 </div>
 </div>
 <p class="leftbar">
-These <a href="guidelines.html">IOCCC guidelines</a> are version <strong>28.30 2025-01-16</strong>.
+These <a href="guidelines.html">IOCCC guidelines</a> are version <strong>28.31 2025-01-18</strong>.
 </p>
 <p class="leftbar">
 The <a href="guidelines.md" download="guidelines.md">markdown form of these guidelines</a>
@@ -561,7 +561,7 @@ to process your registration and email you your initial login and password,
 you should <strong>MAKE SURE</strong> you give yourself enough time before the contest closes.
 In other words, <strong>DO NOT WAIT UNTIL THE FINAL DAYS</strong> of the contest to register!
 The <a href="../judges.html">IOCCC judges</a> are <strong>NOT</strong> responsible for delayed or lost email,
-nor for those who wait until the last minute to try to register!
+or for those who wait until the last minute to try to register!
 </p>
 <p class="leftbar">
 For those who have <a href="register.html">registered</a> and received by email, their
@@ -648,7 +648,7 @@ FAQ on “<a href="../quick-start.html#enter">how to enter the IOCCC</a>”
 as that FAQ has import details on
 <a href="register.html">how to register</a>
 as well as
-<a href="submit.html">how to upload your submission</a> for the IOCCC.
+<a href="submit.html">how to upload your submission</a> to the IOCCC.
 </p>
 <p>Jump to: <a href="#">top</a></p>
 <div id="hints">
@@ -786,6 +786,36 @@ value similar to the <a href="../faq.html#size_rule2001-2012">2001-2012</a> and
 <a href="../faq.html#size_rule2013-2020">2013-2020</a> IOCCC eras.
 </p>
 <p>Jump to: <a href="#">top</a></p>
+<div id="extra-files">
+<h1 id="including-extra-files">Including extra files</h1>
+</div>
+<p class="leftbar">
+The maximum total number of files that may be submitted has changed to 39 files.
+However, of those files, 5 are mandatory (<code>prog.c</code>, <code>Makefile</code>, <code>remarks.md</code> and
+the two JSON files generated by <code>mkiocccentry(1)</code>, <code>.info.json</code> and
+<code>.auth.json</code>). Additionally, three of the files in the limit <strong>MUST</strong> be
+specific file(name)s: the <strong>OPTIONAL</strong> submission files, which are <code>prog.alt.c</code>,
+<code>try.sh</code> and <code>try.alt.sh</code>, or else they <strong>WILL</strong> count as an extra file.
+</p>
+<p class="leftbar">
+In other words, the actual amount of <strong>EXTRA</strong> files is 31.
+</p>
+<p class="leftbar">
+If you do need to include more files, you may do so by including as an extra
+file, a tarball. This does <strong>NOT</strong> have to pass <code>txzchk(1)</code> tests; only the
+submission tarball must pass the <code>txzchk(1)</code> tests.
+<p class="leftbar">
+<p class="leftbar">
+<p>See <a href="rules.html#rule17">Rule 17</a> and in particular the part about the <a href="rules.html#max-files">maximum
+number of files</a>. If you do not follow these points, you
+are at a great risk of violating <a href="rules.html#rule17">Rule 17</a>!</p>
+<p class="leftbar">
+<p>For more details, see the
+FAQ on the “<a href="../faq.html#try">try.sh script system</a>”,
+the
+FAQ on “<a href="../faq.html#auth_json">.auth.json</a>”,
+the
+FAQ on “<a href="../faq.html#info_json">.info.json</a>”,</p>
 <h1 id="mkiocccentry"><code>mkiocccentry</code></h1>
 <p class="leftbar">
 <a href="rules.html#rule17">Rule 17</a> (the <code>mkiocccentry(1)</code> rule) states that
@@ -1413,6 +1443,12 @@ We <strong>DISLIKE</strong> the use of <code>varargs.h</code>. Use <code>stdarg.
 <p class="leftbar">
 We <strong>DISLIKE</strong> the use of <code>gets(3)</code>. Use <code>fgets(3)</code> instead.
 </p>
+<p class="leftbar">
+We tend to <strong>DISLIKE</strong> the blatant use of tarballs in an attempt to simply get
+around the extra file number limit. We realize there may be cases where a
+tarball containing a number of extra files may be needed. Such a need for a
+tarball <strong>MUST</strong> be explained in the <code>remarks.md</code> file.
+</p>
 <p>On 28 January 2007, the Judges rescinded the requirement that the
 <code>#</code> in a C preprocessor directive must be the 1st non-whitespace octet.</p>
 <p>The <code>exit(3)</code> function returns <code>void</code>. Some broken systems have <code>exit(3)</code>

next/guidelines.md

@@ -49,7 +49,7 @@ Jump to: [top](#)
 </div>
 
 <p class="leftbar">
-These [IOCCC guidelines](guidelines.html) are version **28.30 2025-01-16**.
+These [IOCCC guidelines](guidelines.html) are version **28.31 2025-01-18**.
 </p>
 
 <p class="leftbar">
@@ -174,7 +174,7 @@ to process your registration and email you your initial login and password,
 you should **MAKE SURE** you give yourself enough time before the contest closes.
 In other words, **DO NOT WAIT UNTIL THE FINAL DAYS** of the contest to register!
 The [IOCCC judges](../judges.html) are **NOT** responsible for delayed or lost email,
-nor for those who wait until the last minute to try to register!
+or for those who wait until the last minute to try to register!
 </p>
 
 <p class="leftbar">
@@ -281,7 +281,7 @@ FAQ on "[how to enter the IOCCC](../quick-start.html#enter)"
 as that FAQ has import details on
 [how to register](register.html)
 as well as
-[how to upload your submission](submit.html) for the IOCCC.
+[how to upload your submission](submit.html) to the IOCCC.
 </p>
 
 
@@ -452,6 +452,43 @@ value similar to the [2001-2012](../faq.html#size_rule2001-2012) and
 
 Jump to: [top](#)
 
+<div id="extra-files">
+# Including extra files
+</div>
+
+<p class="leftbar">
+The maximum total number of files that may be submitted has changed to 39 files.
+However, of those files, 5 are mandatory (`prog.c`, `Makefile`, `remarks.md` and
+the two JSON files generated by `mkiocccentry(1)`, `.info.json` and
+`.auth.json`). Additionally, three of the files in the limit **MUST** be
+specific file(name)s: the **OPTIONAL** submission files, which are `prog.alt.c`,
+`try.sh` and `try.alt.sh`, or else they **WILL** count as an extra file.
+</p>
+
+<p class="leftbar">
+In other words, the actual amount of **EXTRA** files is 31.
+</p>
+
+<p class="leftbar">
+If you do need to include more files, you may do so by including as an extra
+file, a tarball. This does **NOT** have to pass `txzchk(1)` tests; only the
+submission tarball must pass the `txzchk(1)` tests.
+<p class="leftbar">
+
+<p class="leftbar">
+See [Rule 17](rules.html#rule17) and in particular the part about the [maximum
+number of files](rules.html#max-files). If you do not follow these points, you
+are at a great risk of violating [Rule 17](rules.html#rule17)!
+
+<p class="leftbar">
+For more details, see the
+FAQ on the "[try.sh script system](../faq.html#try)",
+the
+FAQ on "[.auth.json](../faq.html#auth_json)",
+the
+FAQ on "[.info.json](../faq.html#info_json)",
+
+
 <div id="mkiocccentry">
 # `mkiocccentry`
 </div>
@@ -1251,6 +1288,13 @@ We **DISLIKE** the use of `varargs.h`.  Use `stdarg.h` instead.
 We **DISLIKE** the use of `gets(3)`.  Use `fgets(3)` instead.
 </p>
 
+<p class="leftbar">
+We tend to **DISLIKE** the blatant use of tarballs in an attempt to simply get
+around the extra file number limit. We realize there may be cases where a
+tarball containing a number of extra files may be needed. Such a need for a
+tarball **MUST** be explained in the `remarks.md` file.
+</p>
+
 On 28 January 2007, the Judges rescinded the requirement that the
 `#` in a C preprocessor directive must be the 1st non-whitespace octet.
 

next/rules.html

@@ -462,7 +462,7 @@ writing by <a href="../contact.html">contacting the judges</a>.</p>
 </div>
 <p>Jump to: <a href="#">top</a></p>
 <p class="leftbar">
-These <a href="rules.html">IOCCC rules</a> are version <strong>28.17 2024-12-30</strong>.
+These <a href="rules.html">IOCCC rules</a> are version <strong>28.17 2025-01-18</strong>.
 </p>
 <p class="leftbar">
 The <a href="rules.md" download="rules.md">markdown form of these rules</a>
@@ -540,17 +540,17 @@ to process your registration and email you your initial login and password,
 you should <strong>MAKE SURE</strong> you give yourself enough time before the contest closes.
 In other words, <strong>DO NOT WAIT UNTIL THE FINAL DAYS</strong> of the contest to register!
 The <a href="../judges.html">IOCCC judges</a> are <strong>NOT</strong> responsible for delayed or lost email,
-nor for those who wait until the last minute to try to register!
+or for those who wait until the last minute to try to register!
 </p>
 <p class="leftbar">
 See the
 FAQ on “<a href="../faq.html#mkiocccentry">obtaining and compiling the mkiocccentry tools</a>”
 and the
 FAQ on “<a href="../quick-start.html#enter">how to enter the IOCCC</a>”
-as that FAQ has import details on
+as that FAQ has important details on
 <a href="register.html">how to register</a>
 as well as
-<a href="submit.html">how to upload your submission</a> for the IOCCC.
+<a href="submit.html">how to upload your submission</a> to the IOCCC.
 </p>
 <p>Jump to: <a href="#">top</a></p>
 <div id="rules">
@@ -608,6 +608,13 @@ You may check your code prior to submission by giving the filename
 as a command like argument to the <code>iocccsize(1)</code> tool. For example:
 </p>
 <pre><code>    ./iocccsize prog.c</code></pre>
+<p class="leftbar">
+Alternatively, you may use the <code>mkiocccentry(1)</code> option <code>-d</code> to verify that
+things check out without having to answer all the questions. See the
+FAQ on “<a href="../faq.html#mkiocccentry_test">how to test your submission without having to answer
+questions</a>”
+for more details.
+</p>
 <p>Jump to: <a href="#">top</a></p>
 <div id="rule2b">
 <h2 id="rule-2b">Rule 2b</h2>
@@ -680,10 +687,10 @@ to process your registration and email you your initial login and password,
 you should <strong>MAKE SURE</strong> you give yourself enough time before the contest closes.
 In other words, <strong>DO NOT WAIT UNTIL THE FINAL DAYS</strong> of the contest to register!
 The <a href="../judges.html">IOCCC judges</a> are <strong>NOT</strong> responsible for delayed or lost email,
-nor for those who wait until the last minute to try to register!
+or for those who wait until the last minute to try to register!
 </p>
 <p class="leftbar">
-For those who have <a href="register.html">registered</a> and received by email, their
+If you have <a href="register.html">registered</a> and received by email their
 <a href="https://submit.ioccc.org">submit server</a> <strong>Username</strong> and <strong>Initial password</strong>
 from an <a href="../judges.html">IOCCC judge</a>, you may upload your submission to
 the <a href="https://submit.ioccc.org">submit server</a> only while the
@@ -706,7 +713,7 @@ for more information about the <code>mkiocccentry(1)</code> tool.
 <p class="leftbar">
 While the contest is <strong><a href="../status.html#open">open</a></strong>, you may modify your previously
 uploaded submission by rebuilding your submission with the <code>mkiocccentry(1)</code> tool
-and then re-uploading it to the same slot no the <a href="https://submit.ioccc.org">submit server</a>.
+and then re-uploading it to the same slot number on the <a href="https://submit.ioccc.org">submit server</a>.
 </p>
 <p class="leftbar">
 Once the contest enters the <strong><a href="../status.html#judging">judging</a></strong> state, you will
@@ -722,10 +729,10 @@ See the
 FAQ on “<a href="../faq.html#mkiocccentry">obtaining and compiling the mkiocccentry tools</a>”
 and the
 FAQ on “<a href="../quick-start.html#enter">how to enter the IOCCC</a>”
-as that FAQ has import details on
+as that FAQ has important details on
 <a href="register.html">how to register</a>
 as well as
-<a href="submit.html">how to upload your submission</a> for the IOCCC.
+<a href="submit.html">how to upload your submission</a> to the IOCCC.
 </p>
 <p>Jump to: <a href="#">top</a></p>
 <div id="rule4">
@@ -736,12 +743,13 @@ If your submission is selected as a winning entry, then your submission may be m
 to fit into the structure of the <a href="https://www.ioccc.org/index.html">Official IOCCC winner website</a>.
 </p>
 <p class="leftbar">
-For example, your submission’s <code>Makefile</code> might be modified.
+For example, your submission’s <code>Makefile</code> will be modified and your <code>remarks.md</code>
+will become a <code>README.md</code> which will be used to generate an <code>index.html</code> file.
 </p>
 <p class="leftbar">
 Your source code will be the file <code>prog.c</code>. The compiled binary
 will be called <code>prog</code>. If you submission requires different filenames,
-then modify your submission’s <code>Makefile</code> to <strong>COPY</strong> (<strong>NOT</strong> move)
+then modify your submission’s <code>Makefile</code> to <strong>COPY</strong> (<strong>NOT</strong> move!)
 the files accordingly.
 </p>
 <p class="leftbar">
@@ -887,8 +895,7 @@ any control-M at the end of remark file lines.</p>
 In order to register for the IOCCC, you <strong>MUST</strong> have a valid email address.
 </p>
 <p>The <a href="../judges.html">judges</a> <strong>are not responsible for delays in email</strong>, please plan
-enough time for one automated exchange of email as part of your
-submission.</p>
+enough time for the exchange of emails so you can upload your submission.</p>
 <p class="leftbar">
 See the
 FAQ on “<a href="../quick-start.html#register">how to register</a>”
@@ -942,25 +949,33 @@ The above mentioned tools will help you verify that your submission
 conforms to <a href="#rule17">Rule 17</a>.
 </p>
 <p class="leftbar">
-Each above mentioned tool has a <code>-h</code> option that provides command
-line help. For additional details, see the tools’ man pages and the
-<a href="guidelines.html">guidelines</a>.
+Each above mentioned tool has a <code>-h</code> option that provides command line help. For
+additional details of each tool, see its man page, and in some cases, the <a href="guidelines.html">IOCCC
+guidelines</a>.
 </p>
 <p class="leftbar">
-You do not explicitly need to invoke <code>jparse(1)</code> but the <code>jparse(3)</code>
-library will be used when compiling the tools.
+There is no need to use <code>jparse(1)</code> but the <code>jparse(3)</code> library
+library will be linked when compiling the tools as they use various functions
+provided by it, and <code>chkentry</code> uses the JSON parser API as well.
 </p>
 <p class="leftbar">
-Of course you <strong>can</strong> invoke <code>jparse(1)</code> if you wish to validate a JSON file but
+Of course you <strong>may</strong> invoke <code>jparse(1)</code> if you wish to validate a JSON file but
 the only JSON files you might want to validate for the IOCCC are validated
 by <code>chkentry(1)</code>, and that is what you should use to make sure you conform to
 this rule.
 </p>
-<p><strong>IMPORTANT</strong>: Make <strong>SURE</strong> you have the most recent version of the
-<code>mkiocccentry</code> toolkit! Not doing so will put you at a great risk of violating
-this rule! See the
-FAQ on “<a href="../faq.html#mkiocccentry">obtaining the mkiocccentry toolkit</a>”
-for more details.</p>
+<p class="leftbar">
+The maximum number of <strong>extra files</strong> is 31. See the <a href="#max-files">maximum number of extra
+files section</a> below for finer details and the
+FAQ on “<a href="../faq.html#extra-files">including additional files</a>”
+if you need to include more files than this maximum.
+</p>
+<p class="leftbar">
+Extra files are defined as files that are not the required files (<code>prog.c</code>,
+<code>Makefile</code>, <code>remarks.md</code> and the two generated by <code>mkiocccentry(1)</code> <code>.info.json</code>
+and <code>.auth.json</code>) and the optional files (<code>try.sh</code>, <code>prog.alt.c</code> and
+<code>try.alt.sh</code>).
+</p>
 <p>Jump to: <a href="#">top</a></p>
 <h3 id="rule-17---the-complex-details">Rule 17 - The COMPLEX details</h3>
 <p class="leftbar">
@@ -976,10 +991,11 @@ details), and where <em><code>slot_num</code></em> is a single decimal digit int
 (i.e., &gt;= <code>0</code> and &lt; <code>9</code>).
 </p>
 <p class="leftbar">
-In particular, <em><code>username</code></em> is in the form of:
-<code>xxxxxxxx-xxxx-4xxx-axxx-xxxxxxxxxxxx</code> where <code>x</code> is a hexadecimal digit in the
-range <code>[0-9a-f]</code>. And yes, there is a 4 (UUID version 4) and an <code>a</code> (UUID variant
-1) in there.
+In particular, <code>username</code> is in the form of:
+<code>xxxxxxxx-xxxx-4xxx-Nxxx-xxxxxxxxxxxx</code> where <code>'x'</code> is a hex digit in the range
+of <code>[0-9a-f]</code>, 4 is the UUID version, and <code>N</code> is one of <code>8</code>, <code>9</code>, <code>a</code>, or <code>b</code>.
+And yes, there is a 4 (UUID version 4) and variants <code>0x8</code>, <code>0x9</code>, <code>0xa</code> and
+<code>0xb</code> in there.
 </p>
 <p class="leftbar">
 Your xz compressed tarball <strong>MUST</strong> contain, <strong>at a minimum</strong>, the following files:
@@ -1002,12 +1018,20 @@ Your xz compressed tarball <strong>MUST</strong> contain, <strong>at a minimum</
 </p></li>
 </ul>
 <p class="leftbar">
-The <code>.info.json</code> must be valid JSON and pass the <code>chkentry(1)</code> tests.
-It is generated by the <code>mkiocccentry(1)</code> tool.
+The <code>.info.json</code> is generated by the <code>mkiocccentry(1)</code> tool. If not, and it is
+not valid JSON or it does not pass the <code>chkentry(1)</code> tool, your submission
+<strong>WILL BE</strong> rejected! If you do use <code>mkiocccentry(1)</code> and it fails to pass
+<code>chkentry(1)</code> then you might wish to <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">
-The <code>.auth.json</code> must be valid JSON and pass the <code>chkentry(1)</code> tests.
-It is generated by the <code>mkiocccentry(1)</code> tool.
+The <code>.auth.json</code> is generated by the <code>mkiocccentry(1)</code> tool. If not, and it is
+not valid JSON or it does not pass the <code>chkentry(1)</code> tool, your submission
+<strong>WILL BE</strong> rejected! If you do use <code>mkiocccentry(1)</code> and it fails to pass
+<code>chkentry(1)</code> then you might wish to <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">
 You submission may have additional files, however the filenames of those additional files <strong>MUST</strong>:
@@ -1061,6 +1085,13 @@ Your submission’s xz compressed tarball <strong>MUST</strong> pass the <code>t
 the <a href="guidelines.html">guidelines</a> for more details on this tool.
 </p>
 <p class="leftbar">
+<strong>IMPORTANT</strong>: Make <strong>SURE</strong> you have the most recent version of the
+<code>mkiocccentry</code> toolkit! Not doing so will put you at a great risk of violating
+this rule! See the
+FAQ on “<a href="../faq.html#mkiocccentry">obtaining the mkiocccentry toolkit</a>”
+for more details.
+</p>
+<p class="leftbar">
 You are <strong>HIGHLY ENCOURAGED</strong> to use the <code>mkiocccentry(1)</code> tool to form your
 submission’s xz compressed tarball. See the <a href="guidelines.html">guidelines</a> for
 more details on this tool and the <a href="https://github.com/ioccc-src/mkiocccentry">mkiocccentry
@@ -1132,10 +1163,38 @@ The <code>fnamchk(1)</code>, which <code>txzchk(1)</code> executes, will verify
 filename is correct.
 </p>
 <p class="leftbar">
-These checks <strong>MUST PASS</strong>.
+These checks <strong>MUST PASS</strong>. If they do not you stand a significant chance of
+having your submission rejected for violating <a href="#rule17">Rule 17</a>!
+</p>
+<div id="max-files">
+<h4 id="maximum-number-of-files-per-submission">Maximum number of files per submission</h4>
+</div>
+<p class="leftbar">
+The maximum number of files your submission tarball may contain, not counting
+the optional files (<code>prog.alt.c</code>, <code>try.sh</code>, <code>try.alt.sh</code>) and the mandatory
+files (<code>prog.c</code>, <code>Makefile</code>, <code>remarks.md</code>) is 31. This is defined in the macro
+<code>MAX_EXTRA_FILE_COUNT</code> in
+<a href="https://github.com/ioccc-src/mkiocccentry/blob/master/soup/limit_ioccc.h">soup/limit_ioccc.h</a>
+in the <a href="https://github.com/ioccc-src/mkiocccentry">mkiocccentry repo</a>. See the
+FAQ on “<a href="../faq.html#extra-files">how to include additional files</a>”
+if you need to include more files.
 </p>
 <p class="leftbar">
-Where <a href="#rule17">Rule 17</a> and the tools from the latest
+If you do include a tarball that takes your extra files count over the maximum,
+you <strong>MUST</strong> explain this in your <code>remarks.md</code> file!
+</p>
+<p class="leftbar">
+If you need to extract a tarball by some Makefile, or perhaps the program
+itself, then <code>make clobber</code> <strong>MUST</strong> remove everything that the extraction
+created!
+</p>
+<p class="leftbar">
+Tarballs <strong>MUST</strong> only create files and directories <em>under them</em>. They may
+<strong>NOT</strong> contain absolute paths (paths that start with <code>/</code>)!
+</p>
+<hr style="width:50%;text-align:left;margin-left:0">
+<p class="leftbar">
+<strong>IMPORTANT</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.
@@ -1157,7 +1216,7 @@ for more help on ensuring you do have the most up to date release.
 </p>
 <p class="leftbar">
 We recommend that you run <code>make</code> and then install the tools (and man pages) via
-<code>make install</code> (as root or using <code>sudo(1)</code> to help you run these tools from your
+<code>make install</code> (as root or using <code>sudo(1)</code>) to help you run these tools from your
 submission’s directory. The <code>make install</code> will install in <code>/usr/local</code>.
 However, <strong>you do not have</strong> to install them, but in that case you’ll have to run it
 from the toolkit’s directory or use the correct options to specify the path to
@@ -1354,7 +1413,7 @@ See the
 FAQ on “<a href="../faq.html#mkiocccentry">obtaining and compiling the mkiocccentry tools</a>”
 and the
 FAQ on “<a href="../quick-start.html#enter">how to enter the IOCCC</a>”
-as that FAQ has import details on
+as that FAQ has important details on
 <a href="register.html">how to register</a>
 as well as
 <a href="submit.html">how to upload your submission</a> for the IOCCC.

next/rules.md

@@ -55,7 +55,7 @@ Jump to: [top](#)
 
 
 <p class="leftbar">
-These [IOCCC rules](rules.html) are version **28.17 2024-12-30**.
+These [IOCCC rules](rules.html) are version **28.17 2025-01-18**.
 </p>
 
 <p class="leftbar">
@@ -162,7 +162,7 @@ to process your registration and email you your initial login and password,
 you should **MAKE SURE** you give yourself enough time before the contest closes.
 In other words, **DO NOT WAIT UNTIL THE FINAL DAYS** of the contest to register!
 The [IOCCC judges](../judges.html) are **NOT** responsible for delayed or lost email,
-nor for those who wait until the last minute to try to register!
+or for those who wait until the last minute to try to register!
 </p>
 
 <p class="leftbar">
@@ -170,10 +170,10 @@ See the
 FAQ on "[obtaining and compiling the mkiocccentry tools](../faq.html#mkiocccentry)"
 and the
 FAQ on "[how to enter the IOCCC](../quick-start.html#enter)"
-as that FAQ has import details on
+as that FAQ has important details on
 [how to register](register.html)
 as well as
-[how to upload your submission](submit.html) for the IOCCC.
+[how to upload your submission](submit.html) to the IOCCC.
 </p>
 
 
@@ -265,6 +265,14 @@ as a command like argument to the `iocccsize(1)` tool. For example:
     ./iocccsize prog.c
 ```
 
+<p class="leftbar">
+Alternatively, you may use the `mkiocccentry(1)` option `-d` to verify that
+things check out without having to answer all the questions. See the
+FAQ on "[how to test your submission without having to answer
+questions](../faq.html#mkiocccentry_test)"
+for more details.
+</p>
+
 
 Jump to: [top](#)
 
@@ -359,11 +367,11 @@ to process your registration and email you your initial login and password,
 you should **MAKE SURE** you give yourself enough time before the contest closes.
 In other words, **DO NOT WAIT UNTIL THE FINAL DAYS** of the contest to register!
 The [IOCCC judges](../judges.html) are **NOT** responsible for delayed or lost email,
-nor for those who wait until the last minute to try to register!
+or for those who wait until the last minute to try to register!
 </p>
 
 <p class="leftbar">
-For those who have [registered](register.html) and received by email, their
+If you have [registered](register.html) and received by email their
 [submit server](https://submit.ioccc.org) **Username** and **Initial password**
 from an [IOCCC judge](../judges.html), you may upload your submission to
 the [submit server](https://submit.ioccc.org) only while the
@@ -390,7 +398,7 @@ for more information about the `mkiocccentry(1)` tool.
 <p class="leftbar">
 While the contest is **[open](../status.html#open)**, you may modify your previously
 uploaded submission by rebuilding your submission with the `mkiocccentry(1)` tool
-and then re-uploading it to the same slot no the [submit server](https://submit.ioccc.org).
+and then re-uploading it to the same slot number on the [submit server](https://submit.ioccc.org).
 </p>
 
 <p class="leftbar">
@@ -409,10 +417,10 @@ See the
 FAQ on "[obtaining and compiling the mkiocccentry tools](../faq.html#mkiocccentry)"
 and the
 FAQ on "[how to enter the IOCCC](../quick-start.html#enter)"
-as that FAQ has import details on
+as that FAQ has important details on
 [how to register](register.html)
 as well as
-[how to upload your submission](submit.html) for the IOCCC.
+[how to upload your submission](submit.html) to the IOCCC.
 </p>
 
 
@@ -429,13 +437,14 @@ to fit into the structure of the [Official IOCCC winner website](https://www.ioc
 </p>
 
 <p class="leftbar">
-For example, your submission's `Makefile` might be modified.
+For example, your submission's `Makefile` will be modified and your `remarks.md`
+will become a `README.md` which will be used to generate an `index.html` file.
 </p>
 
 <p class="leftbar">
 Your source code will be the file `prog.c`.  The compiled binary
 will be called `prog`.  If you submission requires different filenames,
-then modify your submission's `Makefile` to **COPY** (**NOT** move)
+then modify your submission's `Makefile` to **COPY** (**NOT** move!)
 the files accordingly.
 </p>
 
@@ -653,8 +662,7 @@ In order to register for the IOCCC, you **MUST** have a valid email address.
 </p>
 
 The [judges](../judges.html) **are not responsible for delays in email**, please plan
-enough time for one automated exchange of email as part of your
-submission.
+enough time for the exchange of emails so you can upload your submission.
 
 <p class="leftbar">
 See the
@@ -711,29 +719,37 @@ conforms to [Rule 17](#rule17).
 </p>
 
 <p class="leftbar">
-Each above mentioned tool has a `-h` option that provides command
-line help.  For additional details, see the tools' man pages and the
-[guidelines](guidelines.html).
+Each above mentioned tool has a `-h` option that provides command line help. For
+additional details of each tool, see its man page, and in some cases, the [IOCCC
+guidelines](guidelines.html).
 </p>
 
 <p class="leftbar">
-You do not explicitly need to invoke `jparse(1)` but the `jparse(3)`
-library will be used when compiling the tools.
+There is no need to use `jparse(1)` but the `jparse(3)` library
+library will be linked when compiling the tools as they use various functions
+provided by it, and `chkentry` uses the JSON parser API as well.
 </p>
 
 <p class="leftbar">
-Of course you **can** invoke `jparse(1)` if you wish to validate a JSON file but
+Of course you **may** invoke `jparse(1)` if you wish to validate a JSON file but
 the only JSON files you might want to validate for the IOCCC are validated
 by `chkentry(1)`, and that is what you should use to make sure you conform to
 this rule.
 </p>
 
-**IMPORTANT**: Make **SURE** you have the most recent version of the
-`mkiocccentry` toolkit! Not doing so will put you at a great risk of violating
-this rule! See the
-FAQ on "[obtaining the mkiocccentry toolkit](../faq.html#mkiocccentry)"
-for more details.
+<p class="leftbar">
+The maximum number of **extra files** is 31. See the [maximum number of extra
+files section](#max-files) below for finer details and the
+FAQ on "[including additional files](../faq.html#extra-files)"
+if you need to include more files than this maximum.
+</p>
 
+<p class="leftbar">
+Extra files are defined as files that are not the required files (`prog.c`,
+`Makefile`, `remarks.md` and the two generated by `mkiocccentry(1)` `.info.json`
+and `.auth.json`) and the optional files (`try.sh`, `prog.alt.c` and
+`try.alt.sh`).
+</p>
 
 Jump to: [top](#)
 
@@ -758,10 +774,11 @@ details), and where _`slot_num`_ is a single decimal digit integer
 </p>
 
 <p class="leftbar">
-In particular, _`username`_ is in the form of:
-`xxxxxxxx-xxxx-4xxx-axxx-xxxxxxxxxxxx` where `x` is a hexadecimal digit in the
-range `[0-9a-f]`.  And yes, there is a 4 (UUID version 4) and an `a` (UUID variant
-1) in there.
+In particular, `username` is in the form of:
+`xxxxxxxx-xxxx-4xxx-Nxxx-xxxxxxxxxxxx` where `'x'` is a hex digit in the range
+of `[0-9a-f]`, 4 is the UUID version, and `N` is one of `8`, `9`, `a`, or `b`.
+And yes, there is a 4 (UUID version 4) and variants `0x8`, `0x9`, `0xa` and
+`0xb` in there.
 </p>
 
 <p class="leftbar">
@@ -775,13 +792,21 @@ Your xz compressed tarball **MUST** contain, **at a minimum**, the following fil
 * <p class="leftbar">`.auth.json`</p>
 
 <p class="leftbar">
-The `.info.json` must be valid JSON and pass the `chkentry(1)` tests.
-It is generated by the `mkiocccentry(1)` tool.
+The `.info.json` is generated by the `mkiocccentry(1)` tool. If not, and it is
+not valid JSON or it does not pass the `chkentry(1)` tool, your submission
+**WILL BE** rejected! If you do use `mkiocccentry(1)` and it fails to pass
+`chkentry(1)` then you might wish to [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>
 
 <p class="leftbar">
-The `.auth.json` must be valid JSON and pass the `chkentry(1)` tests.
-It is generated by the `mkiocccentry(1)` tool.
+The `.auth.json` is generated by the `mkiocccentry(1)` tool. If not, and it is
+not valid JSON or it does not pass the `chkentry(1)` tool, your submission
+**WILL BE** rejected! If you do use `mkiocccentry(1)` and it fails to pass
+`chkentry(1)` then you might wish to [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>
 
 <p class="leftbar">
@@ -838,6 +863,18 @@ Your submission's xz compressed tarball **MUST** pass the `txzchk(1)` test. See
 the [guidelines](guidelines.html) for more details on this tool.
 </p>
 
+
+
+<p class="leftbar">
+**IMPORTANT**: Make **SURE** you have the most recent version of the
+`mkiocccentry` toolkit! Not doing so will put you at a great risk of violating
+this rule! See the
+FAQ on "[obtaining the mkiocccentry toolkit](../faq.html#mkiocccentry)"
+for more details.
+</p>
+
+
+
 <p class="leftbar">
 You are **HIGHLY ENCOURAGED** to use the `mkiocccentry(1)` tool to form your
 submission's xz compressed tarball. See the [guidelines](guidelines.html) for
@@ -901,11 +938,46 @@ filename is correct.
 </p>
 
 <p class="leftbar">
-These checks **MUST PASS**.
+These checks **MUST PASS**. If they do not you stand a significant chance of
+having your submission rejected for violating [Rule 17](#rule17)!
+</p>
+
+<div id="max-files">
+#### Maximum number of files per submission
+</div>
+
+<p class="leftbar">
+The maximum number of files your submission tarball may contain, not counting
+the optional files (`prog.alt.c`, `try.sh`, `try.alt.sh`) and the mandatory
+files (`prog.c`, `Makefile`, `remarks.md`) is 31. This is defined in the macro
+`MAX_EXTRA_FILE_COUNT` in
+[soup/limit_ioccc.h](https://github.com/ioccc-src/mkiocccentry/blob/master/soup/limit_ioccc.h)
+in the [mkiocccentry repo](https://github.com/ioccc-src/mkiocccentry). See the
+FAQ on "[how to include additional files](../faq.html#extra-files)"
+if you need to include more files.
 </p>
 
 <p class="leftbar">
-Where [Rule 17](#rule17) and the tools from the latest
+If you do include a tarball that takes your extra files count over the maximum,
+you **MUST** explain this in your `remarks.md` file!
+</p>
+
+<p class="leftbar">
+If you need to extract a tarball by some Makefile, or perhaps the program
+itself, then `make clobber` **MUST** remove everything that the extraction
+created!
+</p>
+
+<p class="leftbar">
+Tarballs **MUST** only create files and directories _under them_. They may
+**NOT** contain absolute paths (paths that start with `/`)!
+</p>
+
+<hr style="width:50%;text-align:left;margin-left:0">
+
+
+<p class="leftbar">
+**IMPORTANT**: where [Rule 17](#rule17) and the tools from the latest
 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.
@@ -930,7 +1002,7 @@ for more help on ensuring you do have the most up to date release.
 
 <p class="leftbar">
 We recommend that you run `make` and then install the tools (and man pages) via
-`make install` (as root or using `sudo(1)` to help you run these tools from your
+`make install` (as root or using `sudo(1)`) to help you run these tools from your
 submission's directory. The `make install` will install in `/usr/local`.
 However, **you do not have** to install them, but in that case you'll have to run it
 from the toolkit's directory or use the correct options to specify the path to
@@ -1210,7 +1282,7 @@ See the
 FAQ on "[obtaining and compiling the mkiocccentry tools](../faq.html#mkiocccentry)"
 and the
 FAQ on "[how to enter the IOCCC](../quick-start.html#enter)"
-as that FAQ has import details on
+as that FAQ has important details on
 [how to register](register.html)
 as well as
 [how to upload your submission](submit.html) for the IOCCC.