From b65e85678fa8e375796c2b2f527074bd06d81f00 Mon Sep 17 00:00:00 2001
From: Cody Boone Ferguson <53008573+xexyl@users.noreply.github.com>
Date: Sat, 18 Jan 2025 09:05:58 -0800
Subject: [PATCH 1/2] Add details on submitting extra files
The FAQ, guidelines and rules have been updated to reflect recent
discussions and modifications to the maximum number of files.
A new FAQ entry has been added. The guidelines talk about including
extra tarballs and rule 17 has been updated as well. Some of this was
copied directly from discussion with Landon.
Some minor other fixes were made in the guidelines and rules (mostly
wording).
---
faq.html | 26 +++++++-
faq.md | 30 ++++++++-
next/guidelines.html | 42 ++++++++++++-
next/guidelines.md | 50 ++++++++++++++-
next/rules.html | 131 ++++++++++++++++++++++++++++-----------
next/rules.md | 144 ++++++++++++++++++++++++++++++++-----------
6 files changed, 339 insertions(+), 84 deletions(-)
diff --git a/faq.html b/faq.html
index 60f4dac4a0..96a646d0fb 100644
--- a/faq.html
+++ b/faq.html
@@ -425,7 +425,7 @@ <h2>Frequently Asked Questions</h2>
<!-- 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 @@ <h2 id="entering-the-ioccc-more-help-and-details">1. <a href="#submitting_help">
<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 @@ <h4 id="q-1.4-how-may-i-use-subdirectories-in-my-submission-if-rule-17-disallows
<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 @@ <h4 id="q-1.5-how-can-i-test-my-submission-passes-tests-without-having-to-answer
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">
diff --git a/faq.md b/faq.md
index 86aab27803..2587841ece 100644
--- a/faq.md
+++ b/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">
diff --git a/next/guidelines.html b/next/guidelines.html
index 95b3b67597..5f54adeaad 100644
--- a/next/guidelines.html
+++ b/next/guidelines.html
@@ -461,7 +461,7 @@ <h1 id="ioccc-guidelines-version">IOCCC Guidelines version</h1>
</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 @@ <h1 id="whats-new-this-ioccc">WHAT’S NEW THIS IOCCC</h1>
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 @@ <h1 id="whats-new-this-ioccc">WHAT’S NEW THIS IOCCC</h1>
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 @@ <h1 id="hints-and-suggestions">HINTS AND SUGGESTIONS:</h1>
<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 @@ <h1 id="our-likes-and-dislikes">OUR LIKES AND DISLIKES:</h1>
<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>
diff --git a/next/guidelines.md b/next/guidelines.md
index e0bee98c71..4ef3126230 100644
--- a/next/guidelines.md
+++ b/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.
diff --git a/next/rules.html b/next/rules.html
index 05b8604734..46e0535aff 100644
--- a/next/rules.html
+++ b/next/rules.html
@@ -462,7 +462,7 @@ <h2 id="ioccc-rules-version">IOCCC Rules version</h2>
</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 @@ <h1 id="important-ioccc-dates">Important IOCCC dates</h1>
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 @@ <h2 id="rule-2a">Rule 2a</h2>
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 @@ <h2 id="rule-3">Rule 3</h2>
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 @@ <h2 id="rule-3">Rule 3</h2>
<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 @@ <h2 id="rule-3">Rule 3</h2>
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 @@ <h2 id="rule-4">Rule 4</h2>
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 @@ <h2 id="rule-15">Rule 15</h2>
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 @@ <h3 id="tldr-rule-17---use-mkiocccentry1">TL;DR Rule 17 - Use <code>mkiocccentry
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 @@ <h3 id="rule-17---the-complex-details">Rule 17 - The COMPLEX details</h3>
(i.e., >= <code>0</code> and < <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 @@ <h3 id="rule-17---the-complex-details">Rule 17 - The COMPLEX details</h3>
</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=&labels=bug&projects=&template=bug_report.yml&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=&labels=bug&projects=&template=bug_report.yml&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 @@ <h3 id="rule-17---the-complex-details">Rule 17 - The COMPLEX details</h3>
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 @@ <h3 id="rule-17---the-complex-details">Rule 17 - The COMPLEX details</h3>
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">
+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">
-Where <a href="#rule17">Rule 17</a> and the tools from the latest
+<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 @@ <h3 id="rule-17---the-complex-details">Rule 17 - The COMPLEX details</h3>
</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 @@ <h1 id="for-more-information">FOR MORE INFORMATION:</h1>
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.
diff --git a/next/rules.md b/next/rules.md
index 14f07e9167..372cba3a60 100644
--- a/next/rules.md
+++ b/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">
+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">
-Where [Rule 17](#rule17) and the tools from the latest
+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.
From f241a72cb74827d33c974b86b4d9905590409852 Mon Sep 17 00:00:00 2001
From: Cody Boone Ferguson <53008573+xexyl@users.noreply.github.com>
Date: Sat, 18 Jan 2025 09:39:51 -0800
Subject: [PATCH 2/2] Fix broken links in guidelines
---
next/guidelines.html | 4 ++--
next/guidelines.md | 4 ++--
2 files changed, 4 insertions(+), 4 deletions(-)
diff --git a/next/guidelines.html b/next/guidelines.html
index 5f54adeaad..b8361024da 100644
--- a/next/guidelines.html
+++ b/next/guidelines.html
@@ -813,9 +813,9 @@ <h1 id="including-extra-files">Including extra files</h1>
<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>”,
+FAQ on “<a href="../faq.html#auth_json">.auth.json</a>”,
the
-FAQ on “<a href="faq.html#info_json">.info.json</a>”,</p>
+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
diff --git a/next/guidelines.md b/next/guidelines.md
index 4ef3126230..c2ab9b8f1f 100644
--- a/next/guidelines.md
+++ b/next/guidelines.md
@@ -484,9 +484,9 @@ are at a great risk of violating [Rule 17](rules.html#rule17)!
For more details, see the
FAQ on the "[try.sh script system](../faq.html#try)",
the
-FAQ on "[.auth.json](faq.html#auth_json)",
+FAQ on "[.auth.json](../faq.html#auth_json)",
the
-FAQ on "[.info.json](faq.html#info_json)",
+FAQ on "[.info.json](../faq.html#info_json)",
<div id="mkiocccentry">