Merge pull request #77 from xexyl/mkiocccentry

Update FAQ, guidelines and rules

faq.html

@@ -684,24 +684,20 @@ <h4 id="q-0.1.4-how-do-i-use-mkiocccentry">Q 0.1.4: How do I use mkiocccentry?</
 see the
 FAQ on “<a href="#about_mkiocccentry">what mkiocccentry is</a>”.</p>
 <p>As the <a href="next/guidelines.html">Guidelines</a> state, the synopsis is:</p>
-<pre><code>    mkiocccentry [options] work_dir prog.c \
-         Makefile remarks.md [file ...]</code></pre>
-<p>… where <code>work_dir</code> is a directory that will be used to build the submission
-tarball, <code>prog.c</code> is your submission source code, <code>Makefile</code> is your submission’s
-<code>Makefile</code>, <code>remarks.md</code> are your remarks (that will be the basis of the
-<code>README.md</code> file which will be used to form the <code>index.html</code> file, if your
-submission wins) and the remaining args are the paths to any other files you
-wish to submit.</p>
-<p>The <code>work_dir</code> <strong>MUST</strong> already exist, as a directory, and it is an error if it
+<pre><code>    mkiocccentry [options] workdir topdir</code></pre>
+<p>… where <code>workdir</code> is a directory that will be used to build the submission
+tarball and <code>topdir</code> is the directory which has your files, including the
+mandatory <code>prog.c</code>, <code>Makefile</code> and <code>remarks.md</code>.</p>
+<p>The <code>workdir</code> <strong>MUST</strong> already exist, as a directory, and it is an error if it
 is not a directory that can be written to. In <strong>this</strong> directory your <strong>submission
 directory</strong> will be created, with the name based on your IOCCC registration
 username, which is <strong>in the form of a UUID</strong>, and submission number; see the
 <a href="next/rules.html">rules</a> for more details on this, and in particular <a href="next/rules.html#rule17">Rule
 17</a>.</p>
-<p>If the <strong><em>subdirectory</em> in the <em>work directory</em></strong> already exists, you will have to
+<p>If the <strong><em>subdirectory</em> in the <em>work directory</em></strong> (based on your submit ID and
+slot number) already exists, you will have to
 move it, remove it or otherwise specify a different work directory (<strong>NOT</strong> the
-subdirectory), as it needs to be empty and the <code>mkiocccentry(1)</code> tool does not
-check this for you as it could not do anything about anyway.</p>
+subdirectory), as it needs to be empty.</p>
 <p>This <em>subdirectory is where your files will be <strong>copied</strong> to</em>. Your <em>submission
 tarball</em> (which you will upload to the submit server) that <code>txzchk(1)</code> will
 validate <em>will be placed in the <strong>work directory</strong></em>, and <strong>its <em>contents</em> will

faq.md

@@ -300,28 +300,24 @@ FAQ on "[what mkiocccentry is](#about_mkiocccentry)".
 As the [Guidelines](next/guidelines.html) state, the synopsis is:
 
 ``` <!---sh-->
-    mkiocccentry [options] work_dir prog.c \
-         Makefile remarks.md [file ...]
+    mkiocccentry [options] workdir topdir
 ```
 
-... where `work_dir` is a directory that will be used to build the submission
-tarball, `prog.c` is your submission source code, `Makefile` is your submission's
-`Makefile`, `remarks.md` are your remarks (that will be the basis of the
-`README.md` file which will be used to form the `index.html` file, if your
-submission wins) and the remaining args are the paths to any other files you
-wish to submit.
+... where `workdir` is a directory that will be used to build the submission
+tarball and `topdir` is the directory which has your files, including the
+mandatory `prog.c`, `Makefile` and `remarks.md`.
 
-The `work_dir` **MUST** already exist, as a directory, and it is an error if it
+The `workdir` **MUST** already exist, as a directory, and it is an error if it
 is not a directory that can be written to. In **this** directory your **submission
 directory** will be created, with the name based on your IOCCC registration
 username, which is **in the form of a UUID**, and submission number; see the
 [rules](next/rules.html) for more details on this, and in particular [Rule
 17](next/rules.html#rule17).
 
-If the **_subdirectory_ in the _work directory_** already exists, you will have to
+If the **_subdirectory_ in the _work directory_** (based on your submit ID and
+slot number) already exists, you will have to
 move it, remove it or otherwise specify a different work directory (**NOT** the
-subdirectory), as it needs to be empty and the `mkiocccentry(1)` tool does not
-check this for you as it could not do anything about anyway.
+subdirectory), as it needs to be empty.
 
 This _subdirectory is where your files will be **copied** to_. Your _submission
 tarball_ (which you will upload to the submit server) that `txzchk(1)` will

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.34 2025-01-24</strong>.
+These <a href="guidelines.html">IOCCC guidelines</a> are version <strong>28.35 2025-01-30</strong>.
 </p>
 <p class="leftbar">
 The <a href="guidelines.md" download="guidelines.md">markdown form of these guidelines</a>
@@ -600,9 +600,11 @@ <h1 id="whats-new-this-ioccc">WHAT’S NEW THIS IOCCC</h1>
 option to <code>mkiocccentry</code> for the tool to pseudo-randomly create answers for you.
 The <code>-d</code> option is an alias for <code>-s 21701</code>. An example use:
 </p>
-<pre><code>    mkiocccentry -d test_work prog.c Makefile remarks.md</code></pre>
+<pre><code>    mkiocccentry -d workdir topdir</code></pre>
 <p class="leftbar">
-where <code>test_work</code> is the directory which the tarball will be formed. Be aware
+where <code>workdir</code> is the directory which the tarball will be formed and the
+<code>topdir</code> is the directory which has the required files (<code>prog.c</code>, <code>Makefile</code> and
+<code>remarks.md</code>) along with extra data files you wish to submit. Be aware
 that if the directory exists already, you will have to remove it or move it
 before this option will work a second time, just like in normal mode.
 </p>
@@ -821,20 +823,32 @@ <h1 id="including-optional-and-extra-files">Including optional and extra files</
 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. Of
-course, if you use the optional filenames without the files being their
-intended, that would be an abuse of rules.
-For more details on the optional files, see the
-FAQ on the “<a href="../faq.html#try_script">try.sh script system</a>”
-and the
-FAQ on “<a href="../faq.html#alt_code">alt code</a>”.
+<code>.auth.json</code>).
+</p>
+<p class="leftbar">
+Additionally, three of the files, if included, <strong>MUST</strong> be
+specific file(name)s and in the top level directory, or they will be counted as
+an extra file, not an optional file.
+</p>
+<p class="leftbar">
+In particular, any file that is not <code>prog.c</code>, <code>Makefile</code>, <code>remarks.md</code>,
+<code>try.sh</code>, <code>prog.alt.c</code> or <code>try.alt.sh</code> will be counted as an extra file, and if
+<code>try.sh</code>, <code>prog.alt.c</code> or <code>try.alt.sh</code> are not in the top level directory they
+will also be counted as an extra file. The <code>.info.json</code> and <code>.auth.json</code> files
+are not counted as extra files but are required.
 </p>
 <p class="leftbar">
 In other words, the actual amount of <strong>EXTRA</strong> files is 31.
 </p>
 <p class="leftbar">
+Of course, if you use the optional filenames without
+the files being our intended use, in order to get past the file limit, that
+would be an abuse of rules. For more details on the optional files, see the
+FAQ on the “<a href="../faq.html#try_script">try.sh script system</a>”
+and the
+FAQ on “<a href="../faq.html#alt_code">alt code</a>”.
+</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. See the <a href="#txzchk">txzchk
@@ -845,6 +859,12 @@ <h1 id="including-optional-and-extra-files">Including optional and extra files</
 said tarball(s), the make <code>clobber</code> rule <strong>MUST</strong> remove them.
 </p>
 <p class="leftbar">
+<strong>IMPORTANT REMINDER</strong>: make <strong>SURE</strong> your tarball does <strong>NOT</strong> reveal who you are!
+The <code>mkiocccentry(1)</code> tool creates a v7 format tarball to prevent this. You can
+do the same like:
+</p>
+<pre><code>    tar --format=v7 -cJf foo.txz directory</code></pre>
+<p class="leftbar">
 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>!
@@ -911,8 +931,7 @@ <h2 id="mkiocccentry1-synopsis"><code>mkiocccentry(1)</code> synopsis</h2>
 <p class="leftbar">
 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] workdir topdir</code></pre>
 <p class="leftbar">
 To help you with editing a submission, the <code>mkiocccentry(1)</code> tool has
 some options to write <em>OR</em> read from an answers file so you do not have to input

next/guidelines.md

@@ -222,11 +222,13 @@ The `-d` option is an alias for `-s 21701`. An example use:
 </p>
 
 ``` <!---sh-->
-    mkiocccentry -d test_work prog.c Makefile remarks.md
+    mkiocccentry -d workdir topdir
 ```
 
 <p class="leftbar">
-where `test_work` is the directory which the tarball will be formed. Be aware
+where `workdir` is the directory which the tarball will be formed and the
+`topdir` is the directory which has the required files (`prog.c`, `Makefile` and
+`remarks.md`) along with extra data files you wish to submit. Be aware
 that if the directory exists already, you will have to remove it or move it
 before this option will work a second time, just like in normal mode.
 </p>
@@ -491,21 +493,36 @@ Jump to: [top](#)
 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. Of
-course, if you use the optional filenames without the files being their
-intended, that would be an abuse of rules.
-For more details on the optional files, see the
-FAQ on the "[try.sh script system](../faq.html#try_script)"
-and the
-FAQ on "[alt code](../faq.html#alt_code)".
+`.auth.json`).
+</p>
+
+<p class="leftbar">
+Additionally, three of the files, if included, **MUST** be
+specific file(name)s and in the top level directory, or they will be counted as
+an extra file, not an optional file.
+</p>
+
+<p class="leftbar">
+In particular, any file that is not `prog.c`, `Makefile`, `remarks.md`,
+`try.sh`, `prog.alt.c` or `try.alt.sh` will be counted as an extra file, and if
+`try.sh`, `prog.alt.c` or `try.alt.sh` are not in the top level directory they
+will also be counted as an extra file. The `.info.json` and `.auth.json` files
+are not counted as extra files but are required.
 </p>
 
 <p class="leftbar">
 In other words, the actual amount of **EXTRA** files is 31.
 </p>
 
+<p class="leftbar">
+Of course, if you use the optional filenames without
+the files being our intended use, in order to get past the file limit, that
+would be an abuse of rules.  For more details on the optional files, see the
+FAQ on the "[try.sh script system](../faq.html#try_script)"
+and the
+FAQ on "[alt code](../faq.html#alt_code)".
+</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
@@ -518,6 +535,16 @@ If you **DO** include a tarball, and the build process or the program extracts
 said tarball(s), the make `clobber` rule **MUST** remove them.
 </p>
 
+<p class="leftbar">
+**IMPORTANT REMINDER**: make **SURE** your tarball does **NOT** reveal who you are!
+The `mkiocccentry(1)` tool creates a v7 format tarball to prevent this. You can
+do the same like:
+</p>
+
+``` <!---sh-->
+    tar --format=v7 -cJf foo.txz directory
+```
+
 <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
@@ -604,8 +631,7 @@ The synopsis of the `mkiocccentry(1)` tool is:
 </p>
 
 ``` <!---sh-->
-    mkiocccentry [options] work_dir prog.c \
-         Makefile remarks.md [file ...]
+    mkiocccentry [options] workdir topdir
 ```
 
 <p class="leftbar">

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.18 2025-01-24</strong>.
+These <a href="rules.html">IOCCC rules</a> are version <strong>28.19 2025-01-30</strong>.
 </p>
 <p class="leftbar">
 The <a href="rules.md" download="rules.md">markdown form of these rules</a>
@@ -1034,22 +1034,6 @@ <h3 id="rule-17---the-complex-details">Rule 17 - The COMPLEX details</h3>
 page</a>.
 </p>
 <p class="leftbar">
-You submission may have additional files, however the filenames of those additional files <strong>MUST</strong>:
-</p>
-<ul>
-<li><p class="leftbar">
-Be less than <strong>100</strong> characters in length.
-</p></li>
-<li><p class="leftbar">
-Match the regular expression:
-<code>^[0-9A-Za-z][0-9A-Za-z._+-]*$</code>
-</p></li>
-</ul>
-<p class="leftbar">
-The <code>mkiocccentry(1)</code> tool will not package any files that do not meet
-those requirements.
-</p>
-<p class="leftbar">
 The <code>Makefile</code> <strong>MUST</strong> be a <strong>non</strong>-empty file in <strong><a href="https://www.gnu.org/software/make/manual/make.html">GNU
 Makefile</a></strong> form. See the
 <a href="guidelines.html#makefile">Makefile section in the guidelines</a>,
@@ -1098,17 +1082,17 @@ <h3 id="rule-17---the-complex-details">Rule 17 - The COMPLEX details</h3>
 repo</a>.
 </p>
 <p class="leftbar">
-Your entry may <strong>NOT</strong> have subdirectories. However, you can provide files that
-are in different directories as <code>mkiocccentry(1)</code> will copy them to the work
-directory (see the <a href="guidelines.html">guidelines</a> for more details).
+Your entry may have subdirectories, depending on the depth and total length of
+the filenames. Certain directories like <code>.git</code>, <code>RCCS</code>, <code>CVS</code> and <code>.svn</code> are
+skipped. For more information, see the <a href="guidelines.html">guidelines</a>.
 </p>
 <p class="leftbar">
 Filenames in your entry (that is, not including the files generated by the
 <code>mkiocccentry(1)</code> tool or the tools it or any other tool invokes) <strong>MUST</strong>:
 </p>
 <ul>
 <li><p class="leftbar">
-Be less than <strong>100</strong> characters in length
+Be &lt;= <strong>38</strong> characters in length
 </p></li>
 <li><p class="leftbar">
 <strong>NOT</strong> have a <strong><code>/</code></strong> (excluding the entry directory that
@@ -1125,13 +1109,19 @@ <h3 id="rule-17---the-complex-details">Rule 17 - The COMPLEX details</h3>
 </p></li>
 <li><p class="leftbar">
 Match the regular expression
-<code>^[0-9A-Za-z][0-9A-Za-z._+-]*$</code> (again, excluding files generated by
+<code>^[0-9A-Za-z]+[0-9A-Za-z_+.-]*$</code> (again, excluding files generated by
 <code>mkiocccentry(1)</code>).
 </p></li>
+<li><p class="leftbar">
+<strong>NOT</strong> be a directory depth &gt; 4.
+</p></li>
+<li><p class="leftbar">
+<strong>NOT</strong> have a total path length &gt; 99 characters.
+</p></li>
 </ul>
 <p class="leftbar">
-Additionally, the tarball <strong>MUST</strong> have the following files (generated
-by the <code>mkiocccentry(1)</code> tool):
+Additionally, the submission tarball created by <code>mkiocccentry(1)</code> <strong>MUST</strong> have
+the following files (generated by the <code>mkiocccentry(1)</code> tool):
 </p>
 <ul>
 <li><p class="leftbar">
@@ -1181,7 +1171,10 @@ <h4 id="maximum-number-of-files-per-submission">Maximum number of files per subm
 </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!
+you <strong>MUST</strong> explain this in your <code>remarks.md</code> file! <strong>PLEASE</strong> do not include a
+tarball with extra files for a test-suite; instead mention in your remarks that
+you have extra files for a test-suite that can be included should your
+submission win.
 </p>
 <p class="leftbar">
 If you need to extract a tarball by some Makefile, or perhaps the program
@@ -1190,8 +1183,14 @@ <h4 id="maximum-number-of-files-per-submission">Maximum number of files per subm
 </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>)!
+<strong>NOT</strong> contain absolute paths (paths that start with <code>/</code>)! <code>txzchk</code> only checks
+the submission tarball so you must verify these details yourself.
+</p>
+<p class="leftbar">
+Make <strong>SURE</strong> your tarball does not reveal who you are! The <code>mkiocccentry(1)</code>
+tool uses the v7 format. For instance you might try:
 </p>
+<pre><code>    tar --format=v7 -cJf foo.txz directory</code></pre>
 <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