From f5bf279807238085e7d250198940408e5b6dd13c Mon Sep 17 00:00:00 2001
From: Cody Boone Ferguson <53008573+xexyl@users.noreply.github.com>
Date: Fri, 7 Feb 2025 11:58:19 -0800
Subject: [PATCH] Update FAQ about new mkiocccentry process

---
 faq.html | 108 ++++++++++++++++++++++++++++++++++++++++++++++++++-----
 faq.md   | 100 ++++++++++++++++++++++++++++++++++++++++++++++-----
 2 files changed, 190 insertions(+), 18 deletions(-)

diff --git a/faq.html b/faq.html
index e5573faa5..e46c4cfe5 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.4 2025-02-03</strong>.</p>
+<p>This is FAQ version <strong>28.2.5 2025-02-07</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>
@@ -714,12 +714,12 @@ 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
-be the <em>subdirectory</em> with your submission’s files</strong>.</p>
-<p>The <code>mkiocccentry(1)</code> tool will ask you for information about your
+be the <em>subdirectory</em> with your submission’s files</strong>.
+The <code>mkiocccentry(1)</code> tool will also ask you for information about your
 submission <em>as well as author details</em> (that will only be looked at if the
-submission wins), run some tests and run a number of other tools, as briefly
-mentioned earlier, and as described in the
-“<a href="#mkiocccentry_details">finer details</a>” section.</p>
+submission wins), run some tests and run a number of other tools, as
+mentioned above, and as described in the “<a href="#mkiocccentry_details">finer
+details</a>” section.</p>
 <p>See also the
 <a href="https://github.com/ioccc-src/mkiocccentry/blob/master/FAQ.md">mkiocccentry repo FAQ</a>
 for more up to date information on downloading, compiling, and related FAQ information.</p>
@@ -1392,7 +1392,9 @@ Jump to: <a href="#">top</a>
 <div id="mkiocccentry_checks">
 <h3 id="q-3.0-what-sort-of-checks-does-the-mkiocccentry-tool-perform">Q 3.0: What sort of checks does the mkiocccentry tool perform?</h3>
 </div>
-<p><code>mkiocccentry(1)</code> will check and warn about the following conditions:</p>
+<p>In addition to the checks in the <a href="#mkiocccentry_process">mkiocccentry process</a>
+described below, <code>mkiocccentry(1)</code> will check and warn about the following
+conditions:</p>
 <ul>
 <li>If the files do not exist, are not regular files or cannot be read.</li>
 <li>If <code>prog.c</code> violates <a href="next/rules.html#rule2">Rule 2</a> (see
@@ -1412,8 +1414,9 @@ Jump to: <a href="#">top</a>
 <li>If the <code>Makefile</code> does not have a <code>clean</code> rule.</li>
 <li>If the <code>Makefile</code> does not have a <code>clobber</code> rule.</li>
 <li>If the <code>Makefile</code> does not have a <code>try</code> rule.</li>
-<li>If the <code>remarks.md</code> is empty.</li>
 </ul>
+<p>If your <code>Makefile</code> is empty or <code>remarks.md</code> is empty it is an error and you will
+have to fix it.</p>
 <p>Conditions that one must correct, and which <code>mkiocccentry(1)</code> will prompt until
 they are correct, are:</p>
 <ul>
@@ -1448,8 +1451,95 @@ has more than one <code>@</code> or is longer than <code>MAX_GITHUB_LEN</code> (
 <li>An <em>author handle</em>, if the default is not accepted, does
 not match the regexp <code>^[0-9A-Za-z][0-9A-Za-z._+-]*$</code>.</li>
 <li>An <em>author handle</em> is repeated.</li>
-<li>The output of <code>ls</code> on the submission directory is incorrect.</li>
 </ul>
+<div id="mkiocccentry_process">
+<h4 id="mkiocccentry-process"><code>mkiocccentry</code> process</h4>
+</div>
+<p>The <code>mkiocccentry(1)</code> tool performs the following steps:</p>
+<ol start="0" type="1">
+<li>Change to the <code>topdir</code>.</li>
+<li>Traverses the directory, gathering lists of ignored files and files to copy
+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 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>
+<li>If a filename is too long it is an error (see <code>MAX_FILENAME_LEN</code> in
+<a href="https://github.com/ioccc-src/mkiocccentry/blob/master/soup/limit_ioccc.h">limit_ioccc.h</a>).</li>
+<li>If a directory is not readable it is an error.</li>
+<li>If <code>prog.c</code>, <code>Makefile</code> or <code>remarks.md</code> are not found it is an error.</li>
+<li>If too many files that are 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> are found, it is an error (see
+<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.
+<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
+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>
+<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.
+<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>
+</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>
+</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 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 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>
+<li>If a filename is too long it is an error (see <code>MAX_FILENAME_LEN</code> in
+<a href="https://github.com/ioccc-src/mkiocccentry/blob/master/soup/limit_ioccc.h">limit_ioccc.h</a>).</li>
+<li>If a directory is not readable it is an error.</li>
+<li>If too many files that are 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> are found, it is an error (see
+<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>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
+everything is okay.</li>
+<li>Form the tarball and run <code>txzchk(1)</code> on it.</li>
+</ol>
+<p>If any of the steps fail or if the user says something is not okay, it aborts.</p>
 <p>Although the <code>mkiocccentry(1)</code> tool will verify everything for you, you may wish
 to validate different parts individually with the different tools. As the
 <a href="next/rules.html">rules</a> state, each of these tools has a <code>-h</code> option.</p>
diff --git a/faq.md b/faq.md
index ef3433712..8e7f3edb6 100644
--- a/faq.md
+++ b/faq.md
@@ -1,6 +1,6 @@
 # IOCCC FAQ Table of Contents
 
-This is FAQ version **28.2.4 2025-02-03**.
+This is FAQ version **28.2.5 2025-02-07**.
 
 
 ## 0. [Entering the IOCCC: the bare minimum you need to know](#enter_questions)
@@ -339,12 +339,11 @@ 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
 validate _will be placed in the **work directory**_, and **its _contents_ will
 be the _subdirectory_ with your submission's files**.
-
-The `mkiocccentry(1)` tool will ask you for information about your
+The `mkiocccentry(1)` tool will also ask you for information about your
 submission _as well as author details_ (that will only be looked at if the
-submission wins), run some tests and run a number of other tools, as briefly
-mentioned earlier, and as described in the
-"[finer details](#mkiocccentry_details)" section.
+submission wins), run some tests and run a number of other tools, as
+mentioned above, and as described in the "[finer
+details](#mkiocccentry_details)" section.
 
 See also the
 [mkiocccentry repo FAQ](https://github.com/ioccc-src/mkiocccentry/blob/master/FAQ.md)
@@ -1213,7 +1212,9 @@ Jump to: [top](#)
 ### Q 3.0: What sort of checks does the mkiocccentry tool perform?
 </div>
 
-`mkiocccentry(1)` will check and warn about the following conditions:
+In addition to the checks in the [mkiocccentry process](#mkiocccentry_process)
+described below, `mkiocccentry(1)` will check and warn about the following
+conditions:
 
 - If the files do not exist, are not regular files or cannot be read.
 - If `prog.c` violates [Rule 2](next/rules.html#rule2) (see
@@ -1233,7 +1234,9 @@ Jump to: [top](#)
 - If the `Makefile` does not have a `clean` rule.
 - If the `Makefile` does not have a `clobber` rule.
 - If the `Makefile` does not have a `try` rule.
-- If the `remarks.md` is empty.
+
+If your `Makefile` is empty or `remarks.md` is empty it is an error and you will
+have to fix it.
 
 Conditions that one must correct, and which `mkiocccentry(1)` will prompt until
 they are correct, are:
@@ -1269,7 +1272,86 @@ has more than one `@` or is longer than `MAX_GITHUB_LEN` (see
 - An _author handle_, if the default is not accepted, does
 not match the regexp `^[0-9A-Za-z][0-9A-Za-z._+-]*$`.
 - An _author handle_ is repeated.
-- The output of `ls` on the submission directory is incorrect.
+
+<div id="mkiocccentry_process">
+#### `mkiocccentry` process
+</div>
+
+The `mkiocccentry(1)` tool performs the following steps:
+
+0. Change to the `topdir`.
+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).
+    * 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)).
+    * If a filename is too long it is an error (see `MAX_FILENAME_LEN` in
+    [limit_ioccc.h](https://github.com/ioccc-src/mkiocccentry/blob/master/soup/limit_ioccc.h)).
+    * If a directory is not readable it is an error.
+    * If `prog.c`, `Makefile` or `remarks.md` are not found it is an error.
+    * If too many files that are not `prog.c`, `Makefile`, `remarks.md`,
+    `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
+    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.
+    * 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`).
+    * 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.
+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 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 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).
+    * 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)).
+    * If a filename is too long it is an error (see `MAX_FILENAME_LEN` in
+    [limit_ioccc.h](https://github.com/ioccc-src/mkiocccentry/blob/master/soup/limit_ioccc.h)).
+    * If a directory is not readable it is an error.
+    * If too many files that are not `prog.c`, `Makefile`, `remarks.md`,
+    `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.
+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
+everything is okay.
+11. Form the tarball and run `txzchk(1)` on it.
+
+If any of the steps fail or if the user says something is not okay, it aborts.
 
 Although the `mkiocccentry(1)` tool will verify everything for you, you may wish
 to validate different parts individually with the different tools. As the