From c6e1c09401e131ea1b8f4a7bf0400c8193c398dc Mon Sep 17 00:00:00 2001
From: Cody Boone Ferguson <53008573+xexyl@users.noreply.github.com>
Date: Sat, 8 Feb 2025 10:34:24 -0800
Subject: [PATCH] Update FAQ and rules for mkiocccentry

Additional things were added to the process (and as for the rules it
notes that remarks.md is only checked for size > 0, not that it has
content).
---
 faq.html        | 79 ++++++++++++++++++++++++++++------------------
 faq.md          | 83 ++++++++++++++++++++++++++++++-------------------
 next/rules.html |  6 ++--
 next/rules.md   |  6 ++--
 4 files changed, 108 insertions(+), 66 deletions(-)

diff --git a/faq.html b/faq.html
index e46c4cfe5..e8f66416b 100644
--- a/faq.html
+++ b/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.5 2025-02-07</strong>.</p>
+<p>This is FAQ version <strong>28.2.6 2025-02-08</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>
@@ -1463,9 +1463,10 @@ to the submission directory.
 <ul>
 <li>If the depth is too deep it is an error (see <code>MAX_PATH_DEPTH</code> in
 <a href="https://github.com/ioccc-src/mkiocccentry/blob/master/soup/limit_ioccc.h">limit_ioccc.h</a>).</li>
-<li>If a file is not a sane relative path it is an error (see the
-<a href="next/rules.html#">Rules</a> and <a href="next/guidelines.html">Guidelines</a> for more
-details).</li>
+<li>If a filename or directory name is not a sane relative path, not allowed
+or will not be added for some reason, it will be added to a relevant list to show to
+the user later, to let them know it is ignored (see the
+<a href="next/rules.html#">Rules</a> and <a href="next/guidelines.html">Guidelines</a> for more details).</li>
 <li>If the path length (all components) are too long it is an error (see
 <code>MAX_PATH_LEN</code> in
 <a href="https://github.com/ioccc-src/mkiocccentry/blob/master/soup/limit_ioccc.h">limit_ioccc.h</a>).</li>
@@ -1478,49 +1479,65 @@ details).</li>
 <code>MAX_EXTRA_FILE_COUNT</code> in
 <a href="https://github.com/ioccc-src/mkiocccentry/blob/master/soup/limit_ioccc.h">limit_ioccc.h</a>).</li>
 </ul></li>
-<li>The user is presented with lists of files (including symlinks) and
-directories that were ignored as well as files and directories to be added, both
-required and non-required files.
+<li>The user is presented with lists of files, symlinks and directories found.
 <ul>
-<li>Symlinks are ignored and may not be included.</li>
-<li>Certain filenames are forbidden and are not allowed. <code>mkiocccentry(1)</code>
-will warn let you know about this. If you do not confirm that this is okay
-it is an error.</li>
-<li>Certain directories like <code>.git</code>, <code>CVS</code> and other RCS directories are not
+<li>Symlinks are ignored and may not be included. You will be warned about
+this.</li>
+<li>Certain filenames (such as <code>README.md</code>, <code>index.html</code> and various others)
+are forbidden and are not allowed. <code>mkiocccentry(1)</code> will warn and let you
+know about this.</li>
+<li>Certain directories like <code>.git</code>, <code>CVS</code> and other RCS related directories are not
 allowed but are ignored (and not descended into). You will be presented with
-a list of these directories and be asked to confirm it as well.</li>
+a list of these directories.</li>
+<li>No file or directory starting with <code>.</code> will be allowed.</li>
+<li>List of directories that will be made.</li>
+<li>List of required and non-required files that will be added.</li>
 <li>The user is asked to verify each list, including the list of files to be
 added, and if the user says it is not OK the program will abort.</li>
 </ul></li>
 <li>The non-ignored files are copied under
-<code>workdir/submit.USERNAME-SLOT.TIMESTAMP</code>, in the correct subdirectories.
+<code>workdir/submit.USERNAME-SLOT.TIMESTAMP</code> (created prior to traversing the
+<code>topdir</code>), making sure to keep the files in the correct directory.
 <ul>
-<li>As it copies <code>prog.c</code> it runs <code>iocccsize(1)</code> and other tests on it,
-allowing you to override issues.</li>
-<li>As it copies <code>Makefile</code> it runs tests on it, allowing you to override
-certain issues. <code>Makefile</code> may not be empty.</li>
-<li>As it copies <code>remarks.m</code> it checks that it is not empty (if it is empty it
-is an error). <code>remarks.md</code> may not be empty.</li>
-<li>Only <code>try.sh</code> and <code>try.alt.sh</code> may be executable (mode <code>0555</code>).</li>
 <li>Directories are made prior to the copying of the files.</li>
-<li>Directories will be made with mode <code>0755</code>.</li>
-<li>Other files are mode <code>0444</code>.</li>
-<li><code>txzchk(1)</code> verifies these.</li>
+<li>Directories <strong>MUST</strong> be (and will be made) with mode <code>0755</code>.</li>
+<li><code>try.sh</code> and <code>try.alt.sh</code> <strong>MUST</strong> be (and will be copied as) executable (in
+particular: mode <code>0555</code>).</li>
+<li>Other files MUST be (and will be copied as) mode <code>0444</code>.</li>
+<li><code>txzchk(1)</code> verifies these modes (and much more).</li>
 </ul></li>
 <li><code>cd submit.USERNAME-SLOT.TIMESTAMP</code>.</li>
 <li><code>make -f Makefile clobber</code>.
 <ul>
-<li>If this fails it is not an error but you are warned about it; if the
-Makefile does not exist it is an error.</li>
+<li>If this fails it is not an error but you are warned about it (even so, see
+<a href="next/rules.html#rule20">Rule 20</a>).</li>
 </ul></li>
 <li>Traverse the new tree from <code>.</code>, collecting files in the submission directory.
 <ul>
 <li>If an invalid file or directory is found it is an error.</li>
 <li>If the depth is too deep it is an error.</li>
-<li>If <code>prog.c</code>, <code>Makefile</code> or <code>remarks.md</code> are missing it is an error.</li>
+<li>If <code>prog.c</code>, <code>Makefile</code> or <code>remarks.md</code> are missing (or not readable
+regular files) it is an error.</li>
+<li><code>iocccsize(1)</code> (via the <code>mkiocccentry(1)</code> function <code>check_prog_c()</code>) will
+be run on your <code>prog.c</code>, allowing you to override any warnings; if you do not
+override an issue flagged it is an error but if warnings from <code>check_prog_c()</code>
+are ignored you risk violating the <a href="next/rules.html">Rules</a>, including <a href="next/rules.html#rule2">Rule
+2</a>.</li>
+<li><code>check_Makefile()</code> will be run on <code>Makefile</code>; if it is a non-readable or
+empty file it is an error but otherwise you may override any warnings
+(risking violating the <a href="next/rules.html">Rules</a>, especially <a href="next/rules.html#rule17">Rule
+17</a> and <a href="next/rules.html#rule20">Rule 20</a>).</li>
+<li><code>check_remarks_md()</code> will be run on your <code>remarks.m</code>; if it is not a
+regular readable file or it is empty it is an error. Otherwise it will
+proceed. Note it does not check that there is any text in the file, just
+that the file size is not 0.</li>
 <li>If a file is not a sane relative path it is an error (see the
 <a href="next/rules.html#">Rules</a> and <a href="next/guidelines.html">Guidelines</a> for more
-details).</li>
+details, and for even more details see the comments in the jparse function
+<code>sane_relative_path()</code> in the
+<a href="https://github.com/ioccc-src/mkiocccentry/blob/master/jparse/util.c">jparse/util.c</a>
+file at the <a href="https://github.com/ioccc-src/mkiocccentry%5D">mkiocccentry repo</a> (this
+comes from the <a href="https://github.com/xexyl/jparse/">jparse repo</a>).</li>
 <li>If the path length (all components) are too long it is an error (see
 <code>MAX_PATH_LEN</code> in
 <a href="https://github.com/ioccc-src/mkiocccentry/blob/master/soup/limit_ioccc.h">limit_ioccc.h</a>).</li>
@@ -1532,7 +1549,8 @@ details).</li>
 <code>MAX_EXTRA_FILE_COUNT</code> in
 <a href="https://github.com/ioccc-src/mkiocccentry/blob/master/soup/limit_ioccc.h">limit_ioccc.h</a>).</li>
 </ul></li>
-<li>Report on files that were copied in (3) but are now gone: asking the user to verify.</li>
+<li>Report on files that were copied in (3) and directories made in (3) but are
+now gone: asking the user to verify.</li>
 <li>Present the list of non-dot files that remain and ask the user to confirm.</li>
 <li>Create the <code>.info.json</code> and <code>.auth.json</code> files, running <code>chkenry(1)</code> on each.</li>
 <li>List the submission directory contents, asking the user once again to verify
@@ -1559,7 +1577,8 @@ for more details on the tools that <code>mkiocccentry</code> either executes dir
 indirectly as part of the packaging process, especially if you wish to run one
 or more of these tools manually.</p>
 <p>See also the <a href="next/guidelines.html">Guidelines</a> and the <a href="next/rules.html">Rules</a>
-(and in particular <a href="next/rules.html#rule17">Rule 17</a>).</p>
+(especially <a href="next/rules.html#rule2">Rule 2</a>, <a href="next/rules.html#rule17">Rule
+17</a>, <a href="next/rules.html#rule20">Rule 20</a>).</p>
 <p>Jump to: <a href="#">top</a></p>
 <div id="txzchk">
 <div id="tarball">
diff --git a/faq.md b/faq.md
index 8e7f3edb6..05a1b474c 100644
--- a/faq.md
+++ b/faq.md
@@ -1,6 +1,6 @@
 # IOCCC FAQ Table of Contents
 
-This is FAQ version **28.2.5 2025-02-07**.
+This is FAQ version **28.2.6 2025-02-08**.
 
 
 ## 0. [Entering the IOCCC: the bare minimum you need to know](#enter_questions)
@@ -1283,10 +1283,11 @@ The `mkiocccentry(1)` tool performs the following steps:
 1. Traverses the directory, gathering lists of ignored files and files to copy
 to the submission directory.
     * If the depth is too deep it is an error (see `MAX_PATH_DEPTH` in
-[limit_ioccc.h](https://github.com/ioccc-src/mkiocccentry/blob/master/soup/limit_ioccc.h)).
-    * If a file is not a sane relative path it is an error (see the
-    [Rules](next/rules.html#) and [Guidelines](next/guidelines.html) for more
-    details).
+    [limit_ioccc.h](https://github.com/ioccc-src/mkiocccentry/blob/master/soup/limit_ioccc.h)).
+    * If a filename or directory name is not a sane relative path, not allowed
+    or will not be added for some reason, it will be added to a relevant list to show to
+    the user later, to let them know it is ignored (see the
+    [Rules](next/rules.html#) and [Guidelines](next/guidelines.html) for more details).
     * If the path length (all components) are too long it is an error (see
     `MAX_PATH_LEN` in
     [limit_ioccc.h](https://github.com/ioccc-src/mkiocccentry/blob/master/soup/limit_ioccc.h)).
@@ -1298,42 +1299,58 @@ to the submission directory.
     `try.sh`, `prog.alt.c` or `try.alt.sh` are found, it is an error (see
     `MAX_EXTRA_FILE_COUNT` in
     [limit_ioccc.h](https://github.com/ioccc-src/mkiocccentry/blob/master/soup/limit_ioccc.h)).
-2. The user is presented with lists of files (including symlinks) and
-directories that were ignored as well as files and directories to be added, both
-required and non-required files.
-    * Symlinks are ignored and may not be included.
-    * Certain filenames are forbidden and are not allowed. `mkiocccentry(1)`
-    will warn let you know about this. If you do not confirm that this is okay
-    it is an error.
-    * Certain directories like `.git`, `CVS` and other RCS directories are not
+2. The user is presented with lists of files, symlinks and directories found.
+    * Symlinks are ignored and may not be included. You will be warned about
+    this.
+    * Certain filenames (such as `README.md`, `index.html` and various others)
+    are forbidden and are not allowed. `mkiocccentry(1)` will warn and let you
+    know about this.
+    * Certain directories like `.git`, `CVS` and other RCS related directories are not
     allowed but are ignored (and not descended into). You will be presented with
-    a list of these directories and be asked to confirm it as well.
+    a list of these directories.
+    * No file or directory starting with `.` will be allowed.
+    * List of directories that will be made.
+    * List of required and non-required files that will be added.
     * The user is asked to verify each list, including the list of files to be
     added, and if the user says it is not OK the program will abort.
 3. The non-ignored files are copied under
-`workdir/submit.USERNAME-SLOT.TIMESTAMP`, in the correct subdirectories.
-    * As it copies `prog.c` it runs `iocccsize(1)` and other tests on it,
-    allowing you to override issues.
-    * As it copies `Makefile` it runs tests on it, allowing you to override
-    certain issues. `Makefile` may not be empty.
-    * As it copies `remarks.m` it checks that it is not empty (if it is empty it
-    is an error). `remarks.md` may not be empty.
-    * Only `try.sh` and `try.alt.sh` may be executable (mode `0555`).
+`workdir/submit.USERNAME-SLOT.TIMESTAMP` (created prior to traversing the
+`topdir`), making sure to keep the files in the correct directory.
     * Directories are made prior to the copying of the files.
-    * Directories will be made with mode `0755`.
-    * Other files are mode `0444`.
-    * `txzchk(1)` verifies these.
+    * Directories **MUST** be (and will be made) with mode `0755`.
+    * `try.sh` and `try.alt.sh` **MUST** be (and will be copied as) executable (in
+    particular: mode `0555`).
+    * Other files MUST be (and will be copied as) mode `0444`.
+    * `txzchk(1)` verifies these modes (and much more).
 4. `cd submit.USERNAME-SLOT.TIMESTAMP`.
 5. `make -f Makefile clobber`.
-    * If this fails it is not an error but you are warned about it; if the
-    Makefile does not exist it is an error.
-6. Traverse the new tree from `.`, collecting files in the submission directory.
+    * If this fails it is not an error but you are warned about it (even so, see
+     [Rule 20](next/rules.html#rule20)).
+6.  Traverse the new tree from `.`, collecting files in the submission directory.
     * If an invalid file or directory is found it is an error.
     * If the depth is too deep it is an error.
-    * If `prog.c`, `Makefile` or `remarks.md` are missing it is an error.
+    * If `prog.c`, `Makefile` or `remarks.md` are missing (or not readable
+    regular files) it is an error.
+    * `iocccsize(1)` (via the `mkiocccentry(1)` function `check_prog_c()`) will
+    be run on your `prog.c`, allowing you to override any warnings; if you do not
+    override an issue flagged it is an error but if warnings from `check_prog_c()`
+    are ignored you risk violating the [Rules](next/rules.html), including [Rule
+    2](next/rules.html#rule2).
+    * `check_Makefile()` will be run on `Makefile`; if it is a non-readable or
+    empty file it is an error but otherwise you may override any warnings
+    (risking violating the [Rules](next/rules.html), especially [Rule
+    17](next/rules.html#rule17) and [Rule 20](next/rules.html#rule20)).
+    * `check_remarks_md()` will be run on your `remarks.m`; if it is not a
+    regular readable file or it is empty it is an error. Otherwise it will
+    proceed. Note it does not check that there is any text in the file, just
+    that the file size is not 0.
     * If a file is not a sane relative path it is an error (see the
     [Rules](next/rules.html#) and [Guidelines](next/guidelines.html) for more
-    details).
+    details, and for even more details see the comments in the jparse function
+    `sane_relative_path()` in the
+    [jparse/util.c](https://github.com/ioccc-src/mkiocccentry/blob/master/jparse/util.c)
+    file at the [mkiocccentry repo](https://github.com/ioccc-src/mkiocccentry]) (this
+    comes from the [jparse repo](https://github.com/xexyl/jparse/)).
     * If the path length (all components) are too long it is an error (see
     `MAX_PATH_LEN` in
     [limit_ioccc.h](https://github.com/ioccc-src/mkiocccentry/blob/master/soup/limit_ioccc.h)).
@@ -1344,7 +1361,8 @@ required and non-required files.
     `try.sh`, `prog.alt.c` or `try.alt.sh` are found, it is an error (see
     `MAX_EXTRA_FILE_COUNT` in
     [limit_ioccc.h](https://github.com/ioccc-src/mkiocccentry/blob/master/soup/limit_ioccc.h)).
-7. Report on files that were copied in (3) but are now gone: asking the user to verify.
+7. Report on files that were copied in (3) and directories made in (3) but are
+now gone: asking the user to verify.
 8. Present the list of non-dot files that remain and ask the user to confirm.
 9. Create the `.info.json` and `.auth.json` files, running `chkenry(1)` on each.
 10. List the submission directory contents, asking the user once again to verify
@@ -1374,7 +1392,8 @@ indirectly as part of the packaging process, especially if you wish to run one
 or more of these tools manually.
 
 See also the [Guidelines](next/guidelines.html) and the [Rules](next/rules.html)
-(and in particular [Rule 17](next/rules.html#rule17)).
+(especially [Rule 2](next/rules.html#rule2), [Rule
+17](next/rules.html#rule17), [Rule 20](next/rules.html#rule20)).
 
 Jump to: [top](#)
 
diff --git a/next/rules.html b/next/rules.html
index 15cd07622..9e525a639 100644
--- a/next/rules.html
+++ b/next/rules.html
@@ -461,7 +461,7 @@ writing by <a href="../contact.html">contacting the judges</a>.</p>
 </div>
 </div>
 <p class="leftbar">
-These <a href="rules.html">IOCCC rules</a> are version <strong>28.21 2025-02-03</strong>.
+These <a href="rules.html">IOCCC rules</a> are version <strong>28.22 2025-02-08</strong>.
 </p>
 <p class="leftbar">
 The <a href="rules.md" download="rules.md">markdown form of these rules</a>
@@ -1043,7 +1043,9 @@ FAQ on “<a href="../faq.html#make_compatibility">Makefile compatibility</a>”
 for help.
 </p>
 <p class="leftbar">
-The <code>remarks.md</code> <strong>MUST</strong> be a <strong>non</strong>-empty file in markdown form. See also
+The <code>remarks.md</code> <strong>MUST</strong> be a <strong>non</strong>-empty file in markdown form
+(<code>mkiocccentry(1)</code> only checks the file size but if you do not have any text in
+it you still risk violating this rule). See also
 <a href="#rule18">Rule 18</a> and our
 FAQ on “<a href="../faq.html#remarks_md">remarks.md</a>”
 and our
diff --git a/next/rules.md b/next/rules.md
index fe0e6cf5a..13d7dacb6 100644
--- a/next/rules.md
+++ b/next/rules.md
@@ -53,7 +53,7 @@ Jump to: [top](#)
 
 
 <p class="leftbar">
-These [IOCCC rules](rules.html) are version **28.21 2025-02-03**.
+These [IOCCC rules](rules.html) are version **28.22 2025-02-08**.
 </p>
 
 <p class="leftbar">
@@ -819,7 +819,9 @@ for help.
 </p>
 
 <p class="leftbar">
-The `remarks.md` **MUST** be a **non**-empty file in markdown form.  See also
+The `remarks.md` **MUST** be a **non**-empty file in markdown form
+(`mkiocccentry(1)` only checks the file size but if you do not have any text in
+it you still risk violating this rule).  See also
 [Rule 18](#rule18) and our
 FAQ on "[remarks.md](../faq.html#remarks_md)"
 and our