From 50b9f6939861ec8fcf47e921927df01386ef9d5d Mon Sep 17 00:00:00 2001
From: Cody Boone Ferguson <53008573+xexyl@users.noreply.github.com>
Date: Wed, 12 Feb 2025 16:33:15 -0800
Subject: [PATCH] Update FAQ for mkiocccentry process

I have thought of and plugged additional holes in the process (same with
txzchk but that's beyond the scope of the document) so the FAQ was
updated for this.

Also because it is a long list of steps there is now a TL;DR part above
it.

There was an order issue in the list as well.
---
 faq.html |  81 +++++++++++++++++++++++++++++----------
 faq.md   | 114 ++++++++++++++++++++++++++++++++++++++-----------------
 2 files changed, 142 insertions(+), 53 deletions(-)

diff --git a/faq.html b/faq.html
index 5ae9c5f6f..72771a990 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.8 2025-02-10</strong>.</p>
+<p>This is FAQ version <strong>28.2.9 2025-02-12</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>
@@ -444,7 +444,7 @@
 </ul>
 <h2 id="entering-the-ioccc-more-help-and-details">1. <a href="#submitting_help">Entering the IOCCC: more help and details</a></h2>
 <ul>
-<li><strong>Q 1.0</strong>: <a class="normal" href="#answers_file">How can I avoid reentering the information to mkiocccentry?</a></li>
+<li><strong>Q 1.0</strong>: <a class="normal" href="#answers_file">How can I avoid re-entering the information to mkiocccentry?</a></li>
 <li><strong>Q 1.1</strong>: <a class="normal" href="#prog_c">May I use a different source or compiled filename than prog.c or prog?</a></li>
 <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>
@@ -905,7 +905,7 @@ Jump to: <a href="#">top</a>
 </div>
 <p>Jump to: <a href="#">top</a></p>
 <div id="answers_file">
-<h3 id="q-1.0-how-can-i-avoid-reentering-the-information-to-mkiocccentry">Q 1.0: How can I avoid reentering the information to mkiocccentry?</h3>
+<h3 id="q-1.0-how-can-i-avoid-re-entering-the-information-to-mkiocccentry">Q 1.0: How can I avoid re-entering the information to mkiocccentry?</h3>
 </div>
 <p><code>mkiocccentry(1)</code> has some options to help write <em>OR</em> read from an
 answers file so you do not have to input the author(s) or the submission
@@ -1392,7 +1392,27 @@ Jump to: <a href="#">top</a>
 <div id="mkiocccentry_process">
 <h3 id="q-3.0-what-is-the-mkiocccentry1-process-and-what-sort-of-checks-does-it-perform">Q 3.0: What is the <code>mkiocccentry(1)</code> process and what sort of checks does it perform?</h3>
 </div>
-<p>In full, the <code>mkiocccentry(1)</code> tool performs the following steps:</p>
+<p><strong>TL;DR</strong>: the program will make a submission directory (name based on the
+username and slot number you provide) under the workdir and then switch to the
+topdir. It will then create lists of files and directories to present to you, to
+verify everything is in order. If something is not allowed (bad filename for
+example) or an error occurs (missing required file for example) you will be
+notified of this. After you verify everything is okay the files/directories
+found will be copied/made and it will then switch to the submission directory.
+In the submission directory it scans the file hierarchy again and verifies
+things are still okay. When done it will ask you to verify things are still OK.
+If all is good it’ll ask you for more information about the author(s). Next the
+two required JSON files <code>.auth.json</code> and <code>.info.json</code> will be created, running
+<code>chkentry(1)</code> on each. If all is good it’ll give you another chance to say the
+files/directories look good and if you answer yes it’ll create the tarball and
+run <code>txzchk</code> on it.</p>
+<p>In most cases the program will prompt you to verify your input is correct. In
+the case of author information (which will only be looked at if you win) you
+will be asked to verify country code prior to being asked the other questions.
+If you fail to enter other author information correctly you will be prompted
+right away to fix it. Afterwards, when the author information is collected, it
+will ask you to confirm. This procedure happens for each author.</p>
+<p>In more detail the <code>mkiocccentry(1)</code> tool performs the below steps.</p>
 <ol start="0" type="1">
 <li>Ask the user for a submission ID (see the <a href="next/register.html">how to register</a>
 for more details on how to obtain this and <a href="next/rules.html#rule17">Rule 17</a> for
@@ -1425,9 +1445,9 @@ with files, copy those files to their respective directory). Note the following:
 submission directory itself, unrelated to <code>MAX_PATH_DEPTH</code> above) it is an
 error (see <code>MAX_EXTRA_DIR_COUNT</code> in
 <a href="https://github.com/ioccc-src/mkiocccentry/blob/master/soup/limit_ioccc.h">limit_ioccc.h</a>).</li>
-<li>If the max path length is &lt;= 0 it is an error (and a bug).</li>
-<li>If the max depth is &lt;= 0 it is an error (and a bug).</li>
-<li>If the max filename length is &lt;= 0 it is an error (and a bug).</li>
+<li>If the max path length is &lt;= 0 it is an error (and a bug!).</li>
+<li>If the max depth is &lt;= 0 it is an error (and a bug!).</li>
+<li>If the max filename length is &lt;= 0 it is an error (and a bug!).</li>
 <li>If a path is NULL it is an error.</li>
 <li>If a path is an empty string it is an error.</li>
 <li>If the path length (i.e. <code>strlen(path)</code> where path starts after the
@@ -1456,7 +1476,8 @@ encountered it is an error.</li>
 </ul></li>
 <li>Show each list to the user, asking if this is okay. The lists include:
 <ul>
-<li>Ignored directories (those like <code>.git</code>, <code>CVS</code>, <code>RCCS</code> and <code>.svn</code>).</li>
+<li>Ignored directories (those like <code>.git</code>, <code>CVS</code>, <code>RCCS</code>, <code>.svn</code> and various
+others).</li>
 <li>Unsafe directory names that will not be added (i.e. those that are not
 POSIX plus + safe chars only; see above step (4)). This includes directories
 starting with a <code>.</code>.</li>
@@ -1475,22 +1496,24 @@ and files to be made/copied, and if the user says it is not OK the program will
 <code>workdir/submit.USERNAME-SLOT</code> i.e. the submission directory).
 <ul>
 <li>Directories <strong>MUST</strong> be and are made with mode <code>0755</code>.</li>
-<li>If any directory is not this mode <code>txzchk(1)</code> will flag it.</li>
+<li>If any directory is not this mode <code>txzchk(1)</code> will flag it (and so will
+<code>mkioccentry(1)</code>).</li>
 </ul></li>
 <li>The non-ignored files are copied to their respective directories under the
 submission directory.
 <ul>
 <li><code>try.sh</code> and <code>try.alt.sh</code> <strong>MUST</strong> be and are copied as mode <code>0555</code>.</li>
 <li>All other files <strong>MUST</strong> be and are copied as mode <code>0444</code>.</li>
-<li>Anything else will be flagged by <code>txzchk(1)</code>.</li>
+<li>Anything else will be flagged by <code>txzchk(1)</code> (and it’ll be flagged by
+<code>mkiocccentry(1)</code> too).</li>
 </ul></li>
 <li><code>cd submit.USERNAME-SLOT</code> (i.e. switch to submission directory).</li>
 <li><code>make -f Makefile clobber</code>.
 <ul>
 <li>If this fails it is not an error but you are warned about it (it is an error only if the <code>Makefile</code>
-does not exist); even so, see <a href="next/rules.html#rule20">Rule 20</a>.</li>
+does not a regular readable file but; even so, see <a href="next/rules.html#rule20">Rule 20</a>.</li>
 </ul></li>
-<li>Traverse the new tree from <code>.</code> with additional steps from (4).
+<li>Traverse the new tree from <code>.</code> (the submission directory) with additional steps from (4).
 <ul>
 <li>If any file has an ignored directory name in it, it is an error.</li>
 <li>If a symlink is found it is an error.</li>
@@ -1498,10 +1521,28 @@ does not exist); even so, see <a href="next/rules.html#rule20">Rule 20</a>.</li>
 error.</li>
 <li>If a forbidden filename exists it is an error.</li>
 <li>If any file or directory starts with <code>/</code> or is not POSIX plus + safe chars
-only (see (4) above) it is an error.</li>
-<li>If the depth is too deep it is an error.</li>
+only (see (4) above) it is an error (though this should not actually happen
+unless you’re doing something funny).</li>
+<li>If the directory depth becomes too deep 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>If an optional file is a directory it is an error.</li>
+<li>If a file or directory is in the submission directory that was not found
+in the topdir it is an error.</li>
+<li>If a file or directory found in the topdir is not in the submission
+directory it is an error.</li>
+<li>If a file or directory in the submission directory is a different type
+from the topdir (e.g. if <code>foo</code> was a directory in topdir but in the submission
+directory it is a file) it is an error.</li>
+<li>If a file (based on the name) or directory has the wrong permission it is
+an error (see (7) above).</li>
+<li>If <code>fts_read(3)</code> reports something as a directory but it’s not a directory
+it is an error (and likewise if it reports something as a file and it’s not
+a file it is an error) - though this should never happen.</li>
+<li>If a directory name (full path from the submission directory) is the name
+of a mandatory file it is an error.</li>
+<li>If a directory name (full path from the submission directory) is the name
+of of an optional file 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>
@@ -1519,15 +1560,11 @@ but has no content is violating <a href="next/rules.html#rule17">Rule 17</a> and
 19</a>.</li>
 <li>If any other error condition from step (4) occurs it is also an error.</li>
 </ul></li>
-<li>Report on any directories that were made and files that were copied in (7)
-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>Ask the user for a submission title.</li>
 <li>Ask the user for a one line abstract of the submission.</li>
 <li>Ask the user for the number of authors and for each author ask a variety of
 questions (see below for more information on what kind of questions).</li>
-<li>Show the output of <code>ls -lakR .</code>, asking the user to confirm that the listing
-is okay.</li>
 <li>Create <code>.info.json</code> and run <code>chkentry(1)</code> on it.
 <ul>
 <li>If <code>chkentry(1)</code> fails to validate the file make sure that you have
@@ -1542,6 +1579,8 @@ obtained and compiled the latest version of all the tools and you either are
 in the repo’s directory, you pass the options to give the path to the tools
 or you have installed the latest tools!</li>
 </ul></li>
+<li>Show the output of <code>ls -lakR .</code>, asking the user to confirm that the listing
+is okay.</li>
 <li>Create the tarball with the name in the form of
 <code>submit.USERNAME-SLOT.TIMESTAMP</code>.</li>
 <li>Run <code>txzchk(1)</code> on the tarball.</li>
@@ -1629,7 +1668,11 @@ FAQ on “<a href="#mkiocccentry_test">how to test everything at once without ha
 questions</a>”.</p>
 <p>See also the <a href="next/guidelines.html">Guidelines</a> and the <a href="next/rules.html">Rules</a>
 (especially <a href="next/rules.html#rule1">Rule 1</a>, <a href="next/rules.html#rule2">Rule 2</a>, <a href="next/rules.html#rule17">Rule
-17</a>, <a href="next/rules.html#rule19">Rule 19</a> and <a href="next/rules.html#rule20">Rule 20</a>).</p>
+17</a>, <a href="next/rules.html#rule19">Rule 19</a> and <a href="next/rules.html#rule20">Rule
+20</a>).</p>
+<p>Finally, if you wish to not have to enter the same answers just to update a
+submission, see the
+FAQ on the “<a href="#answers_file">answers file feature</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 c755c65c7..a6a717c97 100644
--- a/faq.md
+++ b/faq.md
@@ -1,6 +1,6 @@
 # IOCCC FAQ Table of Contents
 
-This is FAQ version **28.2.8 2025-02-10**.
+This is FAQ version **28.2.9 2025-02-12**.
 
 
 ## 0. [Entering the IOCCC: the bare minimum you need to know](#enter_questions)
@@ -18,7 +18,7 @@ This is FAQ version **28.2.8 2025-02-10**.
 
 
 ## 1. [Entering the IOCCC: more help and details](#submitting_help)
-- **Q 1.0**: <a class="normal" href="#answers_file">How can I avoid reentering the information to mkiocccentry?</a>
+- **Q 1.0**: <a class="normal" href="#answers_file">How can I avoid re-entering the information to mkiocccentry?</a>
 - **Q 1.1**: <a class="normal" href="#prog_c">May I use a different source or compiled filename than prog.c or prog?</a>
 - **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>
@@ -572,7 +572,7 @@ Jump to: [top](#)
 
 
 <div id="answers_file">
-### Q 1.0: How can I avoid reentering the information to mkiocccentry?
+### Q 1.0: How can I avoid re-entering the information to mkiocccentry?
 </div>
 
 `mkiocccentry(1)` has some options to help write _OR_ read from an
@@ -1212,7 +1212,29 @@ Jump to: [top](#)
 ### Q 3.0: What is the `mkiocccentry(1)` process and what sort of checks does it perform?
 </div>
 
-In full, the `mkiocccentry(1)` tool performs the following steps:
+**TL;DR**: the program will make a submission directory (name based on the
+username and slot number you provide) under the workdir and then switch to the
+topdir. It will then create lists of files and directories to present to you, to
+verify everything is in order. If something is not allowed (bad filename for
+example) or an error occurs (missing required file for example) you will be
+notified of this. After you verify everything is okay the files/directories
+found will be copied/made and it will then switch to the submission directory.
+In the submission directory it scans the file hierarchy again and verifies
+things are still okay. When done it will ask you to verify things are still OK.
+If all is good it'll ask you for more information about the author(s). Next the
+two required JSON files `.auth.json` and `.info.json` will be created, running
+`chkentry(1)` on each. If all is good it'll give you another chance to say the
+files/directories look good and if you answer yes it'll create the tarball and
+run `txzchk` on it.
+
+In most cases the program will prompt you to verify your input is correct. In
+the case of author information (which will only be looked at if you win) you
+will be asked to verify country code prior to being asked the other questions.
+If you fail to enter other author information correctly you will be prompted
+right away to fix it. Afterwards, when the author information is collected, it
+will ask you to confirm. This procedure happens for each author.
+
+In more detail the `mkiocccentry(1)` tool performs the below steps.
 
 0. Ask the user for a submission ID (see the [how to register](next/register.html)
 for more details on how to obtain this and [Rule 17](next/rules.html#rule17) for
@@ -1238,9 +1260,9 @@ with files, copy those files to their respective directory). Note the following:
     submission directory itself, unrelated to `MAX_PATH_DEPTH` above) it is an
     error (see `MAX_EXTRA_DIR_COUNT` in
     [limit_ioccc.h](https://github.com/ioccc-src/mkiocccentry/blob/master/soup/limit_ioccc.h)).
-    * If the max path length is <= 0 it is an error (and a bug).
-    * If the max depth is <= 0 it is an error (and a bug).
-    * If the max filename length is <= 0 it is an error (and a bug).
+    * If the max path length is <= 0 it is an error (and a bug!).
+    * If the max depth is <= 0 it is an error (and a bug!).
+    * If the max filename length is <= 0 it is an error (and a bug!).
     * If a path is NULL it is an error.
     * If a path is an empty string it is an error.
     * If the path length (i.e. `strlen(path)` where path starts after the
@@ -1267,7 +1289,8 @@ with files, copy those files to their respective directory). Note the following:
     encountered it is an error.
     * If there is an unknown error it is an error :-)
 5. Show each list to the user, asking if this is okay. The lists include:
-    * Ignored directories (those like `.git`, `CVS`, `RCCS` and `.svn`).
+    * Ignored directories (those like `.git`, `CVS`, `RCCS`, `.svn` and various
+    others).
     * Unsafe directory names that will not be added (i.e. those that are not
     POSIX plus + safe chars only; see above step (4)). This includes directories
     starting with a `.`.
@@ -1284,27 +1307,47 @@ with files, copy those files to their respective directory). Note the following:
 6. Make any directories if necessary (under
 `workdir/submit.USERNAME-SLOT` i.e. the submission directory).
     * Directories **MUST** be and are made with mode `0755`.
-    * If any directory is not this mode `txzchk(1)` will flag it.
+    * If any directory is not this mode `txzchk(1)` will flag it (and so will
+    `mkioccentry(1)`).
 7. The non-ignored files are copied to their respective directories under the
 submission directory.
     * `try.sh` and `try.alt.sh` **MUST** be and are copied as mode `0555`.
     * All other files **MUST** be and are copied as mode `0444`.
-    * Anything else will be flagged by `txzchk(1)`.
+    * Anything else will be flagged by `txzchk(1)` (and it'll be flagged by
+    `mkiocccentry(1)` too).
 8. `cd submit.USERNAME-SLOT` (i.e. switch to submission directory).
 9. `make -f Makefile clobber`.
     * If this fails it is not an error but you are warned about it (it is an error only if the `Makefile`
-    does not exist); even so, see [Rule 20](next/rules.html#rule20).
-10. Traverse the new tree from `.` with additional steps from (4).
+    does not a regular readable file but; even so, see [Rule 20](next/rules.html#rule20).
+10. Traverse the new tree from `.` (the submission directory) with additional steps from (4).
     * If any file has an ignored directory name in it, it is an error.
     * If a symlink is found it is an error.
     * If any file type other than a directory or regular file exists it is an
     error.
     * If a forbidden filename exists it is an error.
     * If any file or directory starts with `/` or is not POSIX plus + safe chars
-    only (see (4) above) it is an error.
-    * If the depth is too deep it is an error.
+    only (see (4) above) it is an error (though this should not actually happen
+    unless you're doing something funny).
+    * If the directory depth becomes too deep it is an error.
     * If `prog.c`, `Makefile` or `remarks.md` are missing (or not readable
     regular files) it is an error.
+    * If an optional file is a directory it is an error.
+    * If a file or directory is in the submission directory that was not found
+    in the topdir it is an error.
+    * If a file or directory found in the topdir is not in the submission
+    directory it is an error.
+    * If a file or directory in the submission directory is a different type
+    from the topdir (e.g. if `foo` was a directory in topdir but in the submission
+    directory it is a file) it is an error.
+    * If a file (based on the name) or directory has the wrong permission it is
+    an error (see (7) above).
+    * If `fts_read(3)` reports something as a directory but it's not a directory
+    it is an error (and likewise if it reports something as a file and it's not
+    a file it is an error) - though this should never happen.
+    * If a directory name (full path from the submission directory) is the name
+    of a mandatory file it is an error.
+    * If a directory name (full path from the submission directory) is the name
+    of of an optional file 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()`
@@ -1321,28 +1364,26 @@ submission directory.
     but has no content is violating [Rule 17](next/rules.html#rule17) and [Rule
     19](next/rules.html#rule19).
     * If any other error condition from step (4) occurs it is also an error.
-11. Report on any directories that were made and files that were copied in (7)
-but are now gone: asking the user to verify.
-12. Present the list of non-dot files that remain and ask the user to confirm.
-13. Ask the user for a submission title.
-14. Ask the user for a one line abstract of the submission.
-15. Ask the user for the number of authors and for each author ask a variety of
+11. Present the list of non-dot files that remain and ask the user to confirm.
+12. Ask the user for a submission title.
+13. Ask the user for a one line abstract of the submission.
+14. Ask the user for the number of authors and for each author ask a variety of
 questions (see below for more information on what kind of questions).
-16. Show the output of `ls -lakR .`, asking the user to confirm that the listing
+15. Create `.info.json` and run `chkentry(1)` on it.
+    * If `chkentry(1)` fails to validate the file make sure that you have
+    obtained and compiled the latest version of all the tools and you either are
+    in the repo's directory, you pass the options to give the path to the tools
+    or you have installed the latest tools!
+16. Create `.auth.json` and run `chkentry(1)` on it.
+    * If `chkentry(1)` fails to validate the file make sure that you have
+    obtained and compiled the latest version of all the tools and you either are
+    in the repo's directory, you pass the options to give the path to the tools
+    or you have installed the latest tools!
+17. Show the output of `ls -lakR .`, asking the user to confirm that the listing
 is okay.
-17. Create `.info.json` and run `chkentry(1)` on it.
-    * If `chkentry(1)` fails to validate the file make sure that you have
-    obtained and compiled the latest version of all the tools and you either are
-    in the repo's directory, you pass the options to give the path to the tools
-    or you have installed the latest tools!
-18. Create `.auth.json` and run `chkentry(1)` on it.
-    * If `chkentry(1)` fails to validate the file make sure that you have
-    obtained and compiled the latest version of all the tools and you either are
-    in the repo's directory, you pass the options to give the path to the tools
-    or you have installed the latest tools!
-19. Create the tarball with the name in the form of
+18. Create the tarball with the name in the form of
 `submit.USERNAME-SLOT.TIMESTAMP`.
-20. Run `txzchk(1)` on the tarball.
+19. Run `txzchk(1)` on the tarball.
 
 If any of the steps fail or if the user says something is not okay, it aborts.
 Some of the other checks that are made:
@@ -1432,7 +1473,12 @@ questions](#mkiocccentry_test)".
 
 See also the [Guidelines](next/guidelines.html) and the [Rules](next/rules.html)
 (especially [Rule 1](next/rules.html#rule1), [Rule 2](next/rules.html#rule2), [Rule
-17](next/rules.html#rule17), [Rule 19](next/rules.html#rule19) and [Rule 20](next/rules.html#rule20)).
+17](next/rules.html#rule17), [Rule 19](next/rules.html#rule19) and [Rule
+20](next/rules.html#rule20)).
+
+Finally, if you wish to not have to enter the same answers just to update a
+submission, see the
+FAQ on the "[answers file feature](#answers_file)".
 
 Jump to: [top](#)