From bf2e90f2da7923df284656e6d7a8ce8c852795f1 Mon Sep 17 00:00:00 2001
From: Cody Boone Ferguson <53008573+xexyl@users.noreply.github.com>
Date: Thu, 25 Jul 2024 11:58:18 -0700
Subject: [PATCH] Fix FAQs on .auth.json and .info.json

The fields are now in the order that the mkiocccentry tool writes them.

A brief note on how to verify that the .auth.json and .info.json files
are valid JSON (not valid according to the IOCCC rules but valid JSON)
is at the end of each of these FAQs. Given that there are numerous FAQs
on different JSON files it seems like that it might be better to have an
entire FAQ on this (it links to a subsection in an FAQ about another
kind of JSON file). Where this might go is unclear to me so it has not
been done yet.
---
 faq.html | 383 +++++++++++++++++++++++++++++-------------------------
 faq.md   | 385 ++++++++++++++++++++++++++++++-------------------------
 2 files changed, 416 insertions(+), 352 deletions(-)

diff --git a/faq.html b/faq.html
index 47fc28b81..929fb7689 100644
--- a/faq.html
+++ b/faq.html
@@ -389,7 +389,7 @@
 
 <!-- BEFORE: 1st line of markdown file: faq.md -->
 <h1 id="faq-table-of-contents">FAQ Table of Contents</h1>
-<p>This is FAQ version <strong>28.0 2024-07-14</strong>.</p>
+<p>This is FAQ version <strong>28.0.1 2024-07-25</strong>.</p>
 <h2 id="section-0---submitting-entries-to-a-new-ioccc">Section 0 - <a href="#faq0">Submitting entries to a new IOCCC</a></h2>
 <ul>
 <li><a class="normal" href="#faq0_0">0.0 - How may I enter the IOCCC?</a></li>
@@ -534,7 +534,7 @@ to our submission portal.</p>
 <span id="cb2-3"><a href="#cb2-3" aria-hidden="true" tabindex="-1"></a>    <span class="fu">git</span> rebase</span></code></pre></div>
 <h4 id="make-the-mkiocccentry-toolkit">4. Make the mkiocccentry toolkit</h4>
 <div class="sourceCode" id="cb3"><pre class="sourceCode sh"><code class="sourceCode bash"><span id="cb3-1"><a href="#cb3-1" aria-hidden="true" tabindex="-1"></a>    <span class="fu">make</span> clobber all</span></code></pre></div>
-<h4 id="run-the-mkiocccentry-tool-to-form-your-entry-tarball">5. Run the mkiocccentry tool to form your entry tarball</h4>
+<h4 id="run-the-mkiocccentry-tool-to-form-your-submission-tarball">5. Run the mkiocccentry tool to form your submission tarball</h4>
 <div class="sourceCode" id="cb4"><pre class="sourceCode sh"><code class="sourceCode bash"><span id="cb4-1"><a href="#cb4-1" aria-hidden="true" tabindex="-1"></a>    <span class="ex">mkiocccentry</span> work_dir prog.c Makefile remarks.md [file ...]</span></code></pre></div>
 <p>where:</p>
 <ul>
@@ -553,9 +553,11 @@ for more info.</p></li>
 </ul>
 <p>NOTE: Please see our <a href="markdown.html">IOCCC markdown guide</a> for <strong>important information</strong> on using markdown in the IOCCC.</p>
 <p>NOTE: It is <em>NOT</em> necessary to install the tools to use them as you can run
-the tools from the top of the <em>mkiocccentry repo</em> directory just fine.</p>
-<p>If <code>mkiocccentry</code> tool indicates that there is a problem with your entry,
-especially if it identifies a <a href="next/rules.html#2">rule 2</a> related problem,
+the tools from the top of the <em>mkiocccentry repo</em> directory just fine. However,
+installing it will make it easier for you as you can run it from your
+submission’s directory.</p>
+<p>If the <code>mkiocccentry</code> tool indicates that there is a problem with your entry,
+especially if it identifies a <a href="next/rules.html#rule2">Rule 2</a> related problem,
 you are <strong>strongly</strong> encouraged to revise and correct your entry and
 then re-run the <code>mkiocccentry</code> tool.</p>
 <p>If you choose to risk violating rules, be sure an explain your reason
@@ -843,87 +845,8 @@ you attach the log file we will see those too.</p>
 </div>
 <p>This file is constructed by the <code>mkiocccentry(1)</code> <strong>prior to</strong> forming the xz
 compressed tarball of your submission. The <code>.auth.json</code> file contains
-information about the author or authors of the submission, in JSON format. The
-JSON <code>authors</code> <strong>array</strong> holds the following information about the authors of the
-submission:</p>
-<ul>
-<li><p><code>name</code> (double quoted string)</p>
-<ul>
-<li>The <strong>name</strong> of this author.</li>
-</ul></li>
-<li><p><code>location_code</code> (double quoted string)</p>
-<ul>
-<li>The <strong>location code</strong> of this author (an ISO 3166-1 2 character code).
-See
-<a href="https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements" class="uri">https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements</a>
-for a list of valid codes.</li>
-</ul>
-<p><strong>NOTE:</strong> in <code>mkiocccentry</code> use <code>XX</code> if you want your location to be anonymous.</p></li>
-<li><p><code>email</code> (null or double quoted string)</p>
-<ul>
-<li>The <strong>email</strong> of this author in the form of <code>x@y</code>, or <code>null</code> if not provided.</li>
-</ul></li>
-<li><p><code>url</code> (null or double quoted string)</p>
-<ul>
-<li>The primary <strong>URL</strong> of this author, or <code>null</code> if not provided.</li>
-</ul></li>
-<li><p><code>alt_url</code> (null or double quoted string)</p>
-<ul>
-<li>The <strong>alt URL</strong> of this author, or <code>null</code> if not provided.</li>
-</ul></li>
-<li><p><code>mastodon</code> (null or double quoted string)</p>
-<ul>
-<li>The Mastodon handle of this author in the form of <code>@user@domain</code>, or
-<code>null</code> if not provided. See the
-FAQ on “<a href="#try_mastodon">Mastodon</a>”
-for more information.</li>
-</ul></li>
-<li><p><code>github</code> (null or double quoted string)</p>
-<ul>
-<li>The <strong><a href="https://github.com">GitHub</a> account</strong> of this author in the form of <code>@user</code>, or <code>null</code> if not
-provided.</li>
-</ul></li>
-<li><p><code>affiliation</code> (null or double quoted string)</p>
-<ul>
-<li>This author’s <strong>affiliation</strong>, if any, or <code>null</code> if not provided.</li>
-</ul>
-<p><strong>NOTE:</strong> if provided, the length of the <strong>affiliation</strong> <strong>MUST</strong> be within
-the range of 1 <strong>THROUGH</strong> <code>MAX_AFFILIATION_LEN</code> (see
-<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>). If
-this is not the case you stand a great risk of having your submission
-rejected for violating <a href="next/rules.html#rule17">Rule 17</a>!</p>
-<p><strong>NOTE:</strong> an <strong>affiliation</strong> does <strong>NOT</strong> have any affect on whether you will win or not.</p></li>
-<li><p><code>past_winning_author</code> (boolean)</p>
-<ul>
-<li><code>true</code> if this author claims to have won a past IOCCC, <code>false</code> if this
-author has <strong>NOT</strong> won before.</li>
-</ul>
-<p><strong>NOTE:</strong> this has <strong>NO</strong> effect on whether you will win or not.</p></li>
-<li><p><code>default_handle</code> (boolean)</p>
-<ul>
-<li><code>true</code> if this default handle was accepted, <code>false</code> if one is provided
-by this author.</li>
-</ul></li>
-<li><p><code>author_handle</code> (double quoted string)</p>
-<ul>
-<li>This author’s handle (custom or default provided).</li>
-</ul>
-<p><strong>NOTE:</strong> if you have won before, we <strong>ENCOURAGE</strong> you to use the same handle of
-your previous winning entries, to help in organising the
-<a href="authors.html">authors.html</a> page and the author JSON file.
-See the
-FAQ on “<a href="#author_handle_faq">author handle</a>”
-and the
-FAQ on “<a href="#author_json">author_handle.json</a>”
-for more information.</p></li>
-<li><p><code>author_number</code> (number)</p>
-<ul>
-<li>This author number in the <code>authors</code> array.</li>
-</ul></li>
-</ul>
-<h3 id="additional-fields-in-.auth.json">Additional fields in <code>.auth.json</code>:</h3>
-<p>The file also contains the following details:</p>
+information about the author or authors of the submission, in JSON format.</p>
+<p>In order of the file’s contents we describe each required field, below:</p>
 <ul>
 <li><code>no_comment</code> (double quoted string)
 <ul>
@@ -1044,12 +967,92 @@ array your submission <strong>will be</strong> invalid.</p></li>
 </ul>
 <p><strong>NOTE:</strong> if <code>true</code> then this may <strong>NOT</strong> be submitted to the contest! Please do
 <strong>NOT</strong> email the <a href="judges.html">Judges</a> your submission!</p></li>
+</ul>
+<p>Next, the JSON <code>authors</code> <strong>array</strong> holds the following information about the
+author(s) of the submission:</p>
+<ul>
+<li><p><code>name</code> (double quoted string)</p>
+<ul>
+<li>The <strong>name</strong> of this author.</li>
+</ul></li>
+<li><p><code>location_code</code> (double quoted string)</p>
+<ul>
+<li>The <strong>location code</strong> of this author (an ISO 3166-1 2 character code).
+See
+<a href="https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements" class="uri">https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements</a>
+for a list of valid codes.</li>
+</ul>
+<p><strong>NOTE:</strong> in <code>mkiocccentry</code> use <code>XX</code> if you want your location to be anonymous.</p></li>
+<li><p><code>email</code> (null or double quoted string)</p>
+<ul>
+<li>The <strong>email</strong> of this author in the form of <code>x@y</code>, or <code>null</code> if not provided.</li>
+</ul></li>
+<li><p><code>url</code> (null or double quoted string)</p>
+<ul>
+<li>The primary <strong>URL</strong> of this author, or <code>null</code> if not provided.</li>
+</ul></li>
+<li><p><code>alt_url</code> (null or double quoted string)</p>
+<ul>
+<li>The <strong>alt URL</strong> of this author, or <code>null</code> if not provided.</li>
+</ul></li>
+<li><p><code>mastodon</code> (null or double quoted string)</p>
+<ul>
+<li>The Mastodon handle of this author in the form of <code>@user@domain</code>, or
+<code>null</code> if not provided. See the
+FAQ on “<a href="#try_mastodon">Mastodon</a>”
+for more information.</li>
+</ul></li>
+<li><p><code>github</code> (null or double quoted string)</p>
+<ul>
+<li>The <strong><a href="https://github.com">GitHub</a> account</strong> of this author in the form of <code>@user</code>, or <code>null</code> if not
+provided.</li>
+</ul></li>
+<li><p><code>affiliation</code> (null or double quoted string)</p>
+<ul>
+<li>This author’s <strong>affiliation</strong>, if any, or <code>null</code> if not provided.</li>
+</ul>
+<p><strong>NOTE:</strong> if provided, the length of the <strong>affiliation</strong> <strong>MUST</strong> be within
+the range of 1 <strong>THROUGH</strong> <code>MAX_AFFILIATION_LEN</code> (see
+<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>). If
+this is not the case you stand a great risk of having your submission
+rejected for violating <a href="next/rules.html#rule17">Rule 17</a>!</p>
+<p><strong>NOTE:</strong> an <strong>affiliation</strong> does <strong>NOT</strong> have any affect on whether you will win or not.</p></li>
+<li><p><code>past_winning_author</code> (boolean)</p>
+<ul>
+<li><code>true</code> if this author claims to have won a past IOCCC, <code>false</code> if this
+author has <strong>NOT</strong> won before.</li>
+</ul>
+<p><strong>NOTE:</strong> this has <strong>NO</strong> effect on whether you will win or not.</p></li>
+<li><p><code>default_handle</code> (boolean)</p>
+<ul>
+<li><code>true</code> if this default handle was accepted, <code>false</code> if one is provided
+by this author.</li>
+</ul></li>
+<li><p><code>author_handle</code> (double quoted string)</p>
+<ul>
+<li>This author’s handle (custom or default provided).</li>
+</ul>
+<p><strong>NOTE:</strong> if you have won before, we <strong>ENCOURAGE</strong> you to use the same handle of
+your previous winning entries, to help in organising the
+<a href="authors.html">authors.html</a> page and the author JSON file.
+See the
+FAQ on “<a href="#author_handle_faq">author handle</a>”
+and the
+FAQ on “<a href="#author_json">author_handle.json</a>”
+for more information.</p></li>
+<li><p><code>author_number</code> (number)</p>
+<ul>
+<li>This author number in the <code>authors</code> array.</li>
+</ul></li>
+</ul>
+<p>After the <code>authors</code> <strong>array</strong> the remaining of a <code>.auth.json</code> file holds:</p>
+<ul>
 <li><p><code>formed_timestamp</code> (number)</p>
 <ul>
-<li>Seconds since epoch when <code>.auth.json was formed (see</code>gettimeofday(2)`).
-See also the
+<li>Seconds since epoch when <code>.auth.json</code> was formed (see <code>gettimeofday(2)</code>). See also the
 FAQ on “<a href="#info_json">.info.json</a>”
-for more inforation.</li>
+for more information.</li>
 </ul>
 <p><strong>NOTE:</strong> this <strong>MUST</strong> be greater than or equal to <code>MIN_TIMESTAMP</code> (see
 <a href="https://github.com/ioccc-src/mkiocccentry/blob/master/soup/limit_ioccc.h">soup/limit_ioccc.h</a>
@@ -1104,6 +1107,9 @@ filed is in the file. In these cases (and any others that must be established as
 valid by <code>chkentry</code>) your submission would be rejected for violating <a href="next/rules.html#rule17">Rule
 17</a> and in particular because <code>chkentry</code> would not
 validate the <code>.auth.json</code> file.</p>
+<p>If you wish to <strong>verify</strong> that your <code>.auth.json</code> file is valid <strong>JSON</strong> then see the
+<a href="#validating_json">validating JSON documents</a> in the
+FAQ on “<a href="#author_json">author_handle.json</a>”.</p>
 <div id="faq0_10">
 <div id="info_json">
 <h3 id="faq-0.10-what-is-a-.info.json-file">FAQ 0.10: What is a <code>.info.json</code> file?</h3>
@@ -1120,90 +1126,8 @@ See the
 FAQ on “<a href="#auth_json">.auth.json</a>”
 and the
 FAQ on “<a href="#remarks_md">remarks.md</a>”
-for more inforation.</p>
-<ul>
-<li><p><code>info_JSON</code> (double quoted string)</p>
-<ul>
-<li>This <code>MUST</code> be <code>".info.json"</code>, defined as <code>INFO_JSON_FILENAME</code> in
-<a href="https://github.com/ioccc-src/mkiocccentry/blob/master/soup/entry_util.h">soup/entry_util.h</a>
-in the <a href="https://github.com/ioccc-src/mkiocccentry/">mkiocccentry repo</a>, and
-it is the <code>.info.json</code> file that <code>mkiocccentry</code> forms.
-See the
-FAQ on “<a href="#info_json">.info.json</a>”
-for more information.</li>
-</ul>
-<p><strong>NOTE:</strong> if this is <strong>NOT</strong> the case you stand a great chance of having your
-submission rejected for violating <a href="next/rules.html#rule17">Rule 17</a>!</p></li>
-<li><p><code>auth_JSON</code> (double quoted string)</p>
-<ul>
-<li>This <code>MUST</code> be <code>".auth.json"</code>, defined as <code>AUTH_JSON_FILENAME</code> in
-<a href="https://github.com/ioccc-src/mkiocccentry/blob/master/soup/entry_util.h">soup/entry_util.h</a>
-in the <a href="https://github.com/ioccc-src/mkiocccentry/">mkiocccentry repo</a>, and
-it is the <code>.auth.json</code> file that <code>mkiocccentry</code> forms.
-See the
-FAQ on “<a href="#auth_json">.auth.json</a>”
-for more inforation.</li>
-</ul>
-<p><strong>NOTE:</strong> if this is <strong>NOT</strong> the case you stand a great chance of having your
-submission rejected for violating <a href="next/rules.html#rule17">Rule 17</a>!</p></li>
-<li><p><code>c_src</code> (double quoted string)</p>
-<ul>
-<li>This <code>MUST</code> be <code>"prog.c"</code>, defined as <code>PROG_C_FILENAME</code> in
-<a href="https://github.com/ioccc-src/mkiocccentry/blob/master/soup/entry_util.h">soup/entry_util.h</a>
-in the <a href="https://github.com/ioccc-src/mkiocccentry/">mkiocccentry repo</a>, and
-is your submission source code.</li>
-</ul>
-<p><strong>NOTE:</strong> if this is <strong>NOT</strong> the case you stand a great chance of having your
-submission rejected for violating <a href="next/rules.html#rule17">Rule 17</a>!</p>
-<p><strong>NOTE:</strong> if you provide to <code>mkiocccentry</code> a different filename it will be
-copied to <code>prog.c</code>.</p></li>
-<li><p><code>Makefile</code> (double quoted string)</p>
-<ul>
-<li>This <code>MUST</code> be <code>"Makefile"</code>, defined as <code>MAKEFILE_FILENAME</code> in
-<a href="https://github.com/ioccc-src/mkiocccentry/blob/master/soup/entry_util.h">soup/entry_util.h</a>
-in the <a href="https://github.com/ioccc-src/mkiocccentry/">mkiocccentry repo</a>, and
-is your <code>Makefile</code> file.
-See the
-FAQ on “<a href="#makefile">Makefile</a>”
-for more information.</li>
-</ul>
-<p><strong>NOTE:</strong> if this is <strong>NOT</strong> the case you stand a great chance of having your
-submission rejected for violating <a href="next/rules.html#rule17">Rule 17</a>!</p>
-<p><strong>NOTE:</strong> if you provide to <code>mkiocccentry</code> a different filename it will be
-copied to <code>Makefile</code>.</p></li>
-<li><p><code>remarks</code> (double quoted string)</p>
-<ul>
-<li>This <code>MUST</code> be <code>"remarks.md"</code>, defined as <code>REMARKS_FILENAME</code> in
-<a href="https://github.com/ioccc-src/mkiocccentry/blob/master/soup/entry_util.h">soup/entry_util.h</a>
-in the <a href="https://github.com/ioccc-src/mkiocccentry/">mkiocccentry repo</a>, and
-is your <code>remarks.md]</code> file.
-See the
-FAQ on “<a href="#remarks_md">remarks.md</a>”
-for more information.</li>
-</ul>
-<p><strong>NOTE:</strong> if this is <strong>NOT</strong> the case you stand a great chance of having your
-submission rejected for violating <a href="next/rules.html#rule17">Rule 17</a>!</p>
-<p><strong>NOTE:</strong> if you provide to <code>mkiocccentry</code> a different filename it will be
-copied to <code>remarks.md</code>.</p></li>
-</ul>
-<p>The <code>manifest</code> array also optionally has one or more of the field:</p>
-<ul>
-<li><p><code>extra_file</code> (double quoted string)</p>
-<ul>
-<li>Any additional file that you need or want to include with your submission.</li>
-</ul>
-<p><strong>NOTE:</strong> this MUST <strong>NOT</strong> match a mandatory filename (see above list) and
-<code>chkentry</code> will verify this for you; it is <strong>also</strong> an <strong>error</strong> if it the
-filenames are not unique. In these cases you stand a great risk of having
-your submission rejected for violating <a href="next/rules.html#rule17">Rule 17</a>! On
-the other hand, <strong>ONLY</strong> <code>mkiocccentry</code> will verify that the files exist and
-can be read; <code>txzchk(1)</code> will <strong>NOT</strong> do this for you as it only <strong>LISTS</strong>
-the tarball: it does <strong>NOT</strong> extract it. Even so, the <a href="judges.html">Judges</a>
-<strong>WILL</strong> extract the tarball and if a file listed in the manifest does not
-exist your submission will very likely be rejected for not being as
-documented!</p></li>
-</ul>
-<p>The file also contains the following details:</p>
+for more information.</p>
+<p>In order of the file’s contents we describe each required field, below:</p>
 <ul>
 <li><code>no_comment</code> (double quoted string)
 <ul>
@@ -1415,7 +1339,7 @@ overflows in general.</p></li>
 <li><p><code>Makefile_override</code> (boolean)</p>
 <ul>
 <li><code>true</code> if the user overrides any warnings about an incomplete/incorrect
-<code>Makefile file, else</code>false`.</li>
+<code>Makefile</code> file, else <code>false</code>.</li>
 </ul>
 <p><strong>NOTE:</strong> if the <code>Makefile</code> file has no problems and this is <code>true</code> then
 you stand a good chance of having your submission rejected for violating
@@ -1427,6 +1351,9 @@ for more information.</p></li>
 <ul>
 <li><code>true</code> if the first rule in the <code>Makefile</code> file is <code>all</code>, else <code>false</code>.</li>
 </ul>
+<p><strong>NOTE:</strong> if the <code>Makefile</code> file does <strong>NOT</strong> have an <code>all</code> rule or it is not
+first and this boolean is <code>true</code> then you stand a good chance of having your
+submission rejected for violating <a href="next/rules.html#rule17">Rule 17</a>!</p>
 <p>See the
 FAQ on “<a href="#makefile">Makefile</a>”
 for more information.</p></li>
@@ -1434,6 +1361,10 @@ for more information.</p></li>
 <ul>
 <li><code>true</code> if the <code>Makefile</code> file has an <code>all</code> rule, else <code>false</code>.</li>
 </ul>
+<p><strong>NOTE:</strong> if the <code>Makefile</code> file does <strong>NOT</strong> have an <code>all</code> rule and this
+boolean is <code>true</code>, or if it does <strong>NOT</strong> have an <code>all</code> rule but
+<code>first_rule_is_all</code> is <code>true</code> then you stand a good chance of having your
+submission rejected for violating <a href="next/rules.html#rule17">Rule 17</a>!</p>
 <p>See the
 FAQ on “<a href="#makefile">Makefile</a>”
 for more information.</p></li>
@@ -1441,6 +1372,9 @@ for more information.</p></li>
 <ul>
 <li><code>true</code> if the <code>Makefile</code> file has a <code>clean</code> rule, else <code>false</code>.</li>
 </ul>
+<p><strong>NOTE:</strong> if the <code>Makefile</code> file does <strong>NOT</strong> have a <code>clean</code> rule and this
+boolean is <code>true</code> then you stand a good chance of having your submission
+rejected for violating <a href="next/rules.html#rule17">Rule 17</a>!</p>
 <p>See the
 FAQ on “<a href="#makefile">Makefile</a>”
 for more information.</p></li>
@@ -1448,6 +1382,9 @@ for more information.</p></li>
 <ul>
 <li><code>true</code> if the <code>Makefile</code> file has a <code>clobber</code> rule, else <code>false</code>.</li>
 </ul>
+<p><strong>NOTE:</strong> if the <code>Makefile</code> file does <strong>NOT</strong> have an <code>clobber</code> rule and this
+boolean is <code>true</code> then you stand a good chance of having your submission
+rejected for violating <a href="next/rules.html#rule17">Rule 17</a>!</p>
 <p>See the
 FAQ on “<a href="#makefile">Makefile</a>”
 for more information.</p></li>
@@ -1455,6 +1392,9 @@ for more information.</p></li>
 <ul>
 <li><code>true</code> if the <code>Makefile</code> file has a <code>try</code> rule, else <code>false</code>.</li>
 </ul>
+<p><strong>NOTE:</strong> if the <code>Makefile</code> file does <strong>NOT</strong> have an <code>try</code> rule and this
+boolean is <code>true</code> then you stand a good chance of having your submission
+rejected for violating <a href="next/rules.html#rule17">Rule 17</a>!</p>
 <p>See the
 FAQ on “<a href="#makefile">Makefile</a>”
 for more information.</p></li>
@@ -1464,6 +1404,93 @@ for more information.</p></li>
 </ul>
 <p><strong>NOTE:</strong> if this is <code>true</code> then this may <strong>NOT</strong> be submitted to the
 contest! Please do <strong>NOT</strong> email the <a href="judges.html">Judges</a> your submission!</p></li>
+</ul>
+<p>Next comes the <code>manifest</code> <strong>array</strong> which <strong>MUST</strong> have AT LEAST the following.
+The <code>mkiocccentry(1)</code> tool will write it in this order:</p>
+<ul>
+<li><p><code>info_JSON</code> (double quoted string)</p>
+<ul>
+<li>This <code>MUST</code> be <code>".info.json"</code>, defined as <code>INFO_JSON_FILENAME</code> in
+<a href="https://github.com/ioccc-src/mkiocccentry/blob/master/soup/entry_util.h">soup/entry_util.h</a>
+in the <a href="https://github.com/ioccc-src/mkiocccentry/">mkiocccentry repo</a>, and
+it is the <code>.info.json</code> file that <code>mkiocccentry</code> forms.
+See the
+FAQ on “<a href="#info_json">.info.json</a>”
+for more information.</li>
+</ul>
+<p><strong>NOTE:</strong> if this is <strong>NOT</strong> the case you stand a great chance of having your
+submission rejected for violating <a href="next/rules.html#rule17">Rule 17</a>!</p></li>
+<li><p><code>auth_JSON</code> (double quoted string)</p>
+<ul>
+<li>This <code>MUST</code> be <code>".auth.json"</code>, defined as <code>AUTH_JSON_FILENAME</code> in
+<a href="https://github.com/ioccc-src/mkiocccentry/blob/master/soup/entry_util.h">soup/entry_util.h</a>
+in the <a href="https://github.com/ioccc-src/mkiocccentry/">mkiocccentry repo</a>, and
+it is the <code>.auth.json</code> file that <code>mkiocccentry</code> forms.
+See the
+FAQ on “<a href="#auth_json">.auth.json</a>”
+for more information.</li>
+</ul>
+<p><strong>NOTE:</strong> if this is <strong>NOT</strong> the case you stand a great chance of having your
+submission rejected for violating <a href="next/rules.html#rule17">Rule 17</a>!</p></li>
+<li><p><code>c_src</code> (double quoted string)</p>
+<ul>
+<li>This <code>MUST</code> be <code>"prog.c"</code>, defined as <code>PROG_C_FILENAME</code> in
+<a href="https://github.com/ioccc-src/mkiocccentry/blob/master/soup/entry_util.h">soup/entry_util.h</a>
+in the <a href="https://github.com/ioccc-src/mkiocccentry/">mkiocccentry repo</a>, and
+is your submission source code.</li>
+</ul>
+<p><strong>NOTE:</strong> if this is <strong>NOT</strong> the case you stand a great chance of having your
+submission rejected for violating <a href="next/rules.html#rule17">Rule 17</a>!</p>
+<p><strong>NOTE:</strong> if you provide to <code>mkiocccentry</code> a different filename it will be
+copied to <code>prog.c</code>.</p></li>
+<li><p><code>Makefile</code> (double quoted string)</p>
+<ul>
+<li>This <code>MUST</code> be <code>"Makefile"</code>, defined as <code>MAKEFILE_FILENAME</code> in
+<a href="https://github.com/ioccc-src/mkiocccentry/blob/master/soup/entry_util.h">soup/entry_util.h</a>
+in the <a href="https://github.com/ioccc-src/mkiocccentry/">mkiocccentry repo</a>, and
+is your <code>Makefile</code> file.
+See the
+FAQ on “<a href="#makefile">Makefile</a>”
+for more information.</li>
+</ul>
+<p><strong>NOTE:</strong> if this is <strong>NOT</strong> the case you stand a great chance of having your
+submission rejected for violating <a href="next/rules.html#rule17">Rule 17</a>!</p>
+<p><strong>NOTE:</strong> if you provide to <code>mkiocccentry</code> a different filename it will be
+copied to <code>Makefile</code>.</p></li>
+<li><p><code>remarks</code> (double quoted string)</p>
+<ul>
+<li>This <code>MUST</code> be <code>"remarks.md"</code>, defined as <code>REMARKS_FILENAME</code> in
+<a href="https://github.com/ioccc-src/mkiocccentry/blob/master/soup/entry_util.h">soup/entry_util.h</a>
+in the <a href="https://github.com/ioccc-src/mkiocccentry/">mkiocccentry repo</a>, and
+is your <code>remarks.md]</code> file.
+See the
+FAQ on “<a href="#remarks_md">remarks.md</a>”
+for more information.</li>
+</ul>
+<p><strong>NOTE:</strong> if this is <strong>NOT</strong> the case you stand a great chance of having your
+submission rejected for violating <a href="next/rules.html#rule17">Rule 17</a>!</p>
+<p><strong>NOTE:</strong> if you provide to <code>mkiocccentry</code> a different filename it will be
+copied to <code>remarks.md</code>.</p></li>
+</ul>
+<p>The <code>manifest</code> <strong>array</strong> also <strong>OPTIONALLY</strong> has one or more of the field:</p>
+<ul>
+<li><p><code>extra_file</code> (double quoted string)</p>
+<ul>
+<li>Any additional file that you need or want to include with your submission.</li>
+</ul>
+<p><strong>NOTE:</strong> this MUST <strong>NOT</strong> match a mandatory filename (see above list) and
+<code>chkentry</code> will verify this for you; it is <strong>ALSO</strong> an <strong>error</strong> if the
+filenames are not unique. In these cases you stand a great risk of having
+your submission rejected for violating <a href="next/rules.html#rule17">Rule 17</a>! On
+the other hand, <strong>ONLY</strong> <code>mkiocccentry</code> will verify that the files exist and
+can be read; <code>txzchk(1)</code> will <strong>NOT</strong> do this for you as it only <strong>LISTS</strong>
+the tarball: it does <strong>NOT</strong> extract it. Even so, the <a href="judges.html">Judges</a>
+<strong>WILL</strong> extract the tarball and if a file listed in the manifest does not
+exist your submission will very likely be rejected for not being as
+documented!</p></li>
+</ul>
+<p>Finally, after the <code>manifest</code> <strong>array</strong>, the following fields <strong>MUST</strong> exist:</p>
+<ul>
 <li><p><code>formed_timestamp</code> (number)</p>
 <ul>
 <li>Seconds since epoch when JSON (<code>.auth.json</code> or <code>.info.json</code>) file was formed (see <code>gettimeofday(2)</code>).</li>
@@ -1503,9 +1530,8 @@ in the <a href="https://github.com/ioccc-src/mkiocccentry/">mkiocccentry repo</a
 this is not the case your submission <strong>WILL BE</strong> rejected!</p></li>
 </ul>
 <p>This file will be verified with the <code>chkentry(1)</code> tool and if there are any
-problems <strong>it is an error</strong>. If there is an error the tarball will <strong>NOT</strong> be
-formed by <code>mkiocccentry</code>; otherwise the <code>txzchk(1)</code> tool will be executed on the
-tarball.</p>
+problems <strong>it is an error</strong> and the tarball will <strong>NOT</strong> be formed by
+<code>mkiocccentry</code>; otherwise the <code>txzchk(1)</code> tool will be executed on the tarball.</p>
 <p>The <a href="judges.html">Judges</a> <strong>WILL</strong> use <code>chkentry(1)</code> on this file during the
 judging process and if it does not pass your submission <strong>WILL BE</strong> rejected.</p>
 <p>An obvious example where <code>chkentry</code> would fail to validate <code>.info.json</code> is if
@@ -1517,6 +1543,9 @@ filed is in the file. In these cases (and any others that must be established as
 valid by <code>chkentry</code>) your submission would be rejected for violating <a href="next/rules.html#rule17">Rule
 17</a> and in particular because <code>chkentry</code> would not
 validate the <code>.info.json</code> file.</p>
+<p>If you wish to <strong>verify</strong> that your <code>.info.json</code> file is valid <strong>JSON</strong> then see the
+<a href="#validating_json">validating JSON documents</a> in the
+FAQ on “<a href="#author_json">author_handle.json</a>”.</p>
 <div id="faq1">
 <h2 id="section-1-history-of-the-ioccc">Section 1: History of the IOCCC</h2>
 </div>
diff --git a/faq.md b/faq.md
index 0ced54a46..655bba927 100644
--- a/faq.md
+++ b/faq.md
@@ -1,6 +1,6 @@
 # FAQ Table of Contents
 
-This is FAQ version **28.0 2024-07-14**.
+This is FAQ version **28.0.1 2024-07-25**.
 
 
 ## Section  0 - [Submitting entries to a new IOCCC](#faq0)
@@ -14,7 +14,7 @@ This is FAQ version **28.0 2024-07-14**.
 - <a class="normal" href="#faq0_7">0.7  - What are the IOCCC best practices for using markdown?</a>
 - <a class="normal" href="#faq0_8">0.8  - How do I report bugs in a `mkiocccentry` tool?</a>
 - <a class="normal" href="#faq0_9">0.9  - What is a `.auth.json` file?</a>
-- <a class="normal" href="#faq0_10">0.10  - What is a `.info.json` file?</a>
+- <a class="normal" href="#faq0_10">0.10 - What is a `.info.json` file?</a>
 
 
 ## Section  1 - [History of the IOCCC](#faq1)
@@ -181,7 +181,7 @@ If you already have an mkiocccentry tool directory:
     make clobber all
 ```
 
-#### 5. Run the mkiocccentry tool to form your entry tarball
+#### 5. Run the mkiocccentry tool to form your submission tarball
 
 ```sh
     mkiocccentry work_dir prog.c Makefile remarks.md [file ...]
@@ -214,10 +214,12 @@ where:
 NOTE: Please see our [IOCCC markdown guide](markdown.html) for **important information** on using markdown in the IOCCC.
 
 NOTE: It is *NOT* necessary to install the tools to use them as you can run
-the tools from the top of the _mkiocccentry repo_ directory just fine.
+the tools from the top of the _mkiocccentry repo_ directory just fine. However,
+installing it will make it easier for you as you can run it from your
+submission's directory.
 
-If `mkiocccentry` tool indicates that there is a problem with your entry,
-especially if it identifies a [rule 2](next/rules.html#2) related problem,
+If the `mkiocccentry` tool indicates that there is a problem with your entry,
+especially if it identifies a [Rule 2](next/rules.html#rule2) related problem,
 you are **strongly** encouraged to revise and correct your entry and
 then re-run the `mkiocccentry` tool.
 
@@ -596,81 +598,9 @@ you attach the log file we will see those too.
 
 This file is constructed by the `mkiocccentry(1)` **prior to** forming the xz
 compressed tarball of your submission. The `.auth.json` file contains
-information about the author or authors of the submission, in JSON format. The
-JSON `authors` **array** holds the following information about the authors of the
-submission:
+information about the author or authors of the submission, in JSON format.
 
-- `name` (double quoted string)
-     * The **name** of this author.
-
-- `location_code` (double quoted string)
-     * The **location code** of this author (an ISO 3166-1 2 character code).
-     See
-     <https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements>
-     for a list of valid codes.
-
-     **NOTE:** in `mkiocccentry` use `XX` if you want your location to be anonymous.
-
-- `email` (null or double quoted string)
-     * The **email** of this author in the form of `x@y`, or `null` if not provided.
-
-- `url` (null or double quoted string)
-     * The primary **URL** of this author, or `null` if not provided.
-
-- `alt_url` (null or double quoted string)
-     * The **alt URL** of this author, or `null` if not provided.
-
-- `mastodon` (null or double quoted string)
-     * The Mastodon handle of this author in the form of `@user@domain`, or
-     `null` if not provided.  See the
-     FAQ on "[Mastodon](#try_mastodon)"
-     for more information.
-
-- `github` (null or double quoted string)
-     * The **[GitHub](https://github.com) account** of this author in the form of `@user`, or `null` if not
-     provided.
-
-- `affiliation` (null or double quoted string)
-     * This author's **affiliation**, if any, or `null` if not provided.
-
-    **NOTE:** if provided, the length of the **affiliation** **MUST** be within
-    the range of 1 **THROUGH** `MAX_AFFILIATION_LEN` (see
-    [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/)). If
-    this is not the case you stand a great risk of having your submission
-    rejected for violating [Rule 17](next/rules.html#rule17)!
-
-     **NOTE:** an **affiliation** does **NOT** have any affect on whether you will win or not.
-
-- `past_winning_author` (boolean)
-     * `true` if this author claims to have won a past IOCCC, `false` if this
-     author has **NOT** won before.
-
-     **NOTE:** this has **NO** effect on whether you will win or not.
-
-- `default_handle` (boolean)
-     * `true` if this default handle was accepted, `false` if one is provided
-     by this author.
-
-- `author_handle` (double quoted string)
-     * This author's handle (custom or default provided).
-
-     **NOTE:** if you have won before, we **ENCOURAGE** you to use the same handle of
-     your previous winning entries, to help in organising the
-     [authors.html](authors.html) page and the author JSON file.
-     See the
-     FAQ on "[author handle](#author_handle_faq)"
-     and the
-     FAQ on "[author_handle.json](#author_json)"
-     for more information.
-
-- `author_number` (number)
-     * This author number in the `authors` array.
-
-
-### Additional fields in `.auth.json`:
-
-The file also contains the following details:
+In order of the file's contents we describe each required field, below:
 
 - `no_comment` (double quoted string)
     * We can provide `no comment` about `no_comment` other than to state that unless
@@ -792,11 +722,83 @@ The file also contains the following details:
     **NOTE:** if `true` then this may **NOT** be submitted to the contest! Please do
     **NOT** email the [Judges](judges.html) your submission!
 
+Next, the JSON `authors` **array** holds the following information about the
+author(s) of the submission:
+
+- `name` (double quoted string)
+     * The **name** of this author.
+
+- `location_code` (double quoted string)
+     * The **location code** of this author (an ISO 3166-1 2 character code).
+     See
+     <https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements>
+     for a list of valid codes.
+
+     **NOTE:** in `mkiocccentry` use `XX` if you want your location to be anonymous.
+
+- `email` (null or double quoted string)
+     * The **email** of this author in the form of `x@y`, or `null` if not provided.
+
+- `url` (null or double quoted string)
+     * The primary **URL** of this author, or `null` if not provided.
+
+- `alt_url` (null or double quoted string)
+     * The **alt URL** of this author, or `null` if not provided.
+
+- `mastodon` (null or double quoted string)
+     * The Mastodon handle of this author in the form of `@user@domain`, or
+     `null` if not provided.  See the
+     FAQ on "[Mastodon](#try_mastodon)"
+     for more information.
+
+- `github` (null or double quoted string)
+     * The **[GitHub](https://github.com) account** of this author in the form of `@user`, or `null` if not
+     provided.
+
+- `affiliation` (null or double quoted string)
+     * This author's **affiliation**, if any, or `null` if not provided.
+
+    **NOTE:** if provided, the length of the **affiliation** **MUST** be within
+    the range of 1 **THROUGH** `MAX_AFFILIATION_LEN` (see
+    [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/)). If
+    this is not the case you stand a great risk of having your submission
+    rejected for violating [Rule 17](next/rules.html#rule17)!
+
+     **NOTE:** an **affiliation** does **NOT** have any affect on whether you will win or not.
+
+- `past_winning_author` (boolean)
+     * `true` if this author claims to have won a past IOCCC, `false` if this
+     author has **NOT** won before.
+
+     **NOTE:** this has **NO** effect on whether you will win or not.
+
+- `default_handle` (boolean)
+     * `true` if this default handle was accepted, `false` if one is provided
+     by this author.
+
+- `author_handle` (double quoted string)
+     * This author's handle (custom or default provided).
+
+     **NOTE:** if you have won before, we **ENCOURAGE** you to use the same handle of
+     your previous winning entries, to help in organising the
+     [authors.html](authors.html) page and the author JSON file.
+     See the
+     FAQ on "[author handle](#author_handle_faq)"
+     and the
+     FAQ on "[author_handle.json](#author_json)"
+     for more information.
+
+- `author_number` (number)
+     * This author number in the `authors` array.
+
+After the `authors` **array** the remaining of a `.auth.json` file holds:
+
+
 - `formed_timestamp` (number)
-    * Seconds since epoch when `.auth.json was formed (see `gettimeofday(2)`).
-    See also the
+    * Seconds since epoch when `.auth.json` was formed (see `gettimeofday(2)`).  See also the
     FAQ on "[.info.json](#info_json)"
-    for more inforation.
+    for more information.
 
     **NOTE:** this **MUST** be greater than or equal to `MIN_TIMESTAMP` (see
     [soup/limit_ioccc.h](https://github.com/ioccc-src/mkiocccentry/blob/master/soup/limit_ioccc.h)
@@ -832,6 +834,7 @@ The file also contains the following details:
     in the [mkiocccentry repo](https://github.com/ioccc-src/mkiocccentry/). If
     this is not the case your submission **WILL BE** rejected!
 
+
 This file will be verified with the `chkentry(1)` tool and if there are any
 problems **it is an error**. If there is an error the tarball will **NOT** be
 formed by `mkiocccentry`; otherwise the `txzchk(1)` tool will be executed on the
@@ -855,6 +858,10 @@ valid by `chkentry`) your submission would be rejected for violating [Rule
 17](next/rules.html#rule17) and in particular because `chkentry` would not
 validate the `.auth.json` file.
 
+If you wish to **verify** that your `.auth.json` file is valid **JSON** then see the
+[validating JSON documents](#validating_json) in the
+FAQ on "[author_handle.json](#author_json)".
+
 
 <div id="faq0_10">
 <div id="info_json">
@@ -873,95 +880,9 @@ See the
 FAQ on "[.auth.json](#auth_json)"
 and the
 FAQ on "[remarks.md](#remarks_md)"
-for more inforation.
+for more information.
 
-- `info_JSON` (double quoted string)
-    * This `MUST` be `".info.json"`, defined as `INFO_JSON_FILENAME` in
-    [soup/entry_util.h](https://github.com/ioccc-src/mkiocccentry/blob/master/soup/entry_util.h)
-    in the [mkiocccentry repo](https://github.com/ioccc-src/mkiocccentry/), and
-    it is the `.info.json` file that `mkiocccentry` forms.
-    See the
-    FAQ on "[.info.json](#info_json)"
-    for more information.
-
-    **NOTE:** if this is **NOT** the case you stand a great chance of having your
-    submission rejected for violating [Rule 17](next/rules.html#rule17)!
-
-- `auth_JSON` (double quoted string)
-    * This `MUST` be `".auth.json"`, defined as `AUTH_JSON_FILENAME` in
-    [soup/entry_util.h](https://github.com/ioccc-src/mkiocccentry/blob/master/soup/entry_util.h)
-    in the [mkiocccentry repo](https://github.com/ioccc-src/mkiocccentry/), and
-    it is the `.auth.json` file that `mkiocccentry` forms.
-    See the
-    FAQ on "[.auth.json](#auth_json)"
-    for more inforation.
-
-    **NOTE:** if this is **NOT** the case you stand a great chance of having your
-    submission rejected for violating [Rule 17](next/rules.html#rule17)!
-
-- `c_src` (double quoted string)
-    * This `MUST` be `"prog.c"`, defined as `PROG_C_FILENAME` in
-    [soup/entry_util.h](https://github.com/ioccc-src/mkiocccentry/blob/master/soup/entry_util.h)
-    in the [mkiocccentry repo](https://github.com/ioccc-src/mkiocccentry/), and
-    is your submission source code.
-
-    **NOTE:** if this is **NOT** the case you stand a great chance of having your
-    submission rejected for violating [Rule 17](next/rules.html#rule17)!
-
-    **NOTE:** if you provide to `mkiocccentry` a different filename it will be
-    copied to `prog.c`.
-
-
-- `Makefile` (double quoted string)
-    * This `MUST` be `"Makefile"`, defined as `MAKEFILE_FILENAME` in
-    [soup/entry_util.h](https://github.com/ioccc-src/mkiocccentry/blob/master/soup/entry_util.h)
-    in the [mkiocccentry repo](https://github.com/ioccc-src/mkiocccentry/), and
-    is your `Makefile` file.
-    See the
-    FAQ on "[Makefile](#makefile)"
-    for more information.
-
-    **NOTE:** if this is **NOT** the case you stand a great chance of having your
-    submission rejected for violating [Rule 17](next/rules.html#rule17)!
-
-    **NOTE:** if you provide to `mkiocccentry` a different filename it will be
-    copied to `Makefile`.
-
-- `remarks` (double quoted string)
-    * This `MUST` be `"remarks.md"`, defined as `REMARKS_FILENAME` in
-    [soup/entry_util.h](https://github.com/ioccc-src/mkiocccentry/blob/master/soup/entry_util.h)
-    in the [mkiocccentry repo](https://github.com/ioccc-src/mkiocccentry/), and
-    is your `remarks.md]` file.
-    See the
-    FAQ on "[remarks.md](#remarks_md)"
-    for more information.
-
-    **NOTE:** if this is **NOT** the case you stand a great chance of having your
-    submission rejected for violating [Rule 17](next/rules.html#rule17)!
-
-    **NOTE:** if you provide to `mkiocccentry` a different filename it will be
-    copied to `remarks.md`.
-
-
-The `manifest` array also optionally has one or more of the field:
-
-- `extra_file` (double quoted string)
-
-    * Any additional file that you need or want to include with your submission.
-
-    **NOTE:** this MUST **NOT** match a mandatory filename (see above list) and
-    `chkentry` will verify this for you; it is **also** an **error** if it the
-    filenames are not unique. In these cases you stand a great risk of having
-    your submission rejected for violating [Rule 17](next/rules.html#rule17)! On
-    the other hand, **ONLY** `mkiocccentry` will verify that the files exist and
-    can be read; `txzchk(1)` will **NOT** do this for you as it only **LISTS**
-    the tarball: it does **NOT** extract it. Even so, the [Judges](judges.html)
-    **WILL** extract the tarball and if a file listed in the manifest does not
-    exist your submission will very likely be rejected for not being as
-    documented!
-
-
-The file also contains the following details:
+In order of the file's contents we describe each required field, below:
 
 - `no_comment` (double quoted string)
     * We can provide `no comment` about `no_comment` other than to state that unless
@@ -1165,7 +1086,7 @@ The file also contains the following details:
 
 - `Makefile_override` (boolean)
     * `true` if the user overrides any warnings about an incomplete/incorrect
-    `Makefile file, else `false`.
+    `Makefile` file, else `false`.
 
     **NOTE:** if the `Makefile` file has no problems and this is `true` then
     you stand a good chance of having your submission rejected for violating
@@ -1178,6 +1099,10 @@ The file also contains the following details:
 - `first_rule_is_all` (boolean)
     * `true` if the first rule in the `Makefile` file is `all`, else `false`.
 
+    **NOTE:** if the `Makefile` file does **NOT** have an `all` rule or it is not
+    first and this boolean is `true` then you stand a good chance of having your
+    submission rejected for violating [Rule 17](next/rules.html#rule17)!
+
     See the
     FAQ on "[Makefile](#makefile)"
     for more information.
@@ -1185,6 +1110,11 @@ The file also contains the following details:
 - `found_all_rule` (boolean)
     * `true` if the `Makefile` file has an `all` rule, else `false`.
 
+    **NOTE:** if the `Makefile` file does **NOT** have an `all` rule and this
+    boolean is `true`, or if it does **NOT** have an `all` rule but
+    `first_rule_is_all` is `true` then you stand a good chance of having your
+    submission rejected for violating [Rule 17](next/rules.html#rule17)!
+
     See the
     FAQ on "[Makefile](#makefile)"
     for more information.
@@ -1192,6 +1122,10 @@ The file also contains the following details:
 - `found_clean_rule` (boolean)
     * `true` if the `Makefile` file has a `clean` rule, else `false`.
 
+    **NOTE:** if the `Makefile` file does **NOT** have a `clean` rule and this
+    boolean is `true` then you stand a good chance of having your submission
+    rejected for violating [Rule 17](next/rules.html#rule17)!
+
     See the
     FAQ on "[Makefile](#makefile)"
     for more information.
@@ -1199,6 +1133,10 @@ The file also contains the following details:
 - `found_clobber_rule` (boolean)
     * `true` if the `Makefile` file has a `clobber` rule, else `false`.
 
+    **NOTE:** if the `Makefile` file does **NOT** have an `clobber` rule and this
+    boolean is `true` then you stand a good chance of having your submission
+    rejected for violating [Rule 17](next/rules.html#rule17)!
+
     See the
     FAQ on "[Makefile](#makefile)"
     for more information.
@@ -1206,6 +1144,10 @@ The file also contains the following details:
 - `found_try_rule` (boolean)
     * `true` if the `Makefile` file has a `try` rule, else `false`.
 
+    **NOTE:** if the `Makefile` file does **NOT** have an `try` rule and this
+    boolean is `true` then you stand a good chance of having your submission
+    rejected for violating [Rule 17](next/rules.html#rule17)!
+
     See the
     FAQ on "[Makefile](#makefile)"
     for more information.
@@ -1216,6 +1158,96 @@ The file also contains the following details:
     **NOTE:** if this is `true` then this may **NOT** be submitted to the
     contest! Please do **NOT** email the [Judges](judges.html) your submission!
 
+Next comes the `manifest` **array** which **MUST** have AT LEAST the following.
+The `mkiocccentry(1)` tool will write it in this order:
+
+
+- `info_JSON` (double quoted string)
+    * This `MUST` be `".info.json"`, defined as `INFO_JSON_FILENAME` in
+    [soup/entry_util.h](https://github.com/ioccc-src/mkiocccentry/blob/master/soup/entry_util.h)
+    in the [mkiocccentry repo](https://github.com/ioccc-src/mkiocccentry/), and
+    it is the `.info.json` file that `mkiocccentry` forms.
+    See the
+    FAQ on "[.info.json](#info_json)"
+    for more information.
+
+    **NOTE:** if this is **NOT** the case you stand a great chance of having your
+    submission rejected for violating [Rule 17](next/rules.html#rule17)!
+
+- `auth_JSON` (double quoted string)
+    * This `MUST` be `".auth.json"`, defined as `AUTH_JSON_FILENAME` in
+    [soup/entry_util.h](https://github.com/ioccc-src/mkiocccentry/blob/master/soup/entry_util.h)
+    in the [mkiocccentry repo](https://github.com/ioccc-src/mkiocccentry/), and
+    it is the `.auth.json` file that `mkiocccentry` forms.
+    See the
+    FAQ on "[.auth.json](#auth_json)"
+    for more information.
+
+    **NOTE:** if this is **NOT** the case you stand a great chance of having your
+    submission rejected for violating [Rule 17](next/rules.html#rule17)!
+
+- `c_src` (double quoted string)
+    * This `MUST` be `"prog.c"`, defined as `PROG_C_FILENAME` in
+    [soup/entry_util.h](https://github.com/ioccc-src/mkiocccentry/blob/master/soup/entry_util.h)
+    in the [mkiocccentry repo](https://github.com/ioccc-src/mkiocccentry/), and
+    is your submission source code.
+
+    **NOTE:** if this is **NOT** the case you stand a great chance of having your
+    submission rejected for violating [Rule 17](next/rules.html#rule17)!
+
+    **NOTE:** if you provide to `mkiocccentry` a different filename it will be
+    copied to `prog.c`.
+
+
+- `Makefile` (double quoted string)
+    * This `MUST` be `"Makefile"`, defined as `MAKEFILE_FILENAME` in
+    [soup/entry_util.h](https://github.com/ioccc-src/mkiocccentry/blob/master/soup/entry_util.h)
+    in the [mkiocccentry repo](https://github.com/ioccc-src/mkiocccentry/), and
+    is your `Makefile` file.
+    See the
+    FAQ on "[Makefile](#makefile)"
+    for more information.
+
+    **NOTE:** if this is **NOT** the case you stand a great chance of having your
+    submission rejected for violating [Rule 17](next/rules.html#rule17)!
+
+    **NOTE:** if you provide to `mkiocccentry` a different filename it will be
+    copied to `Makefile`.
+
+- `remarks` (double quoted string)
+    * This `MUST` be `"remarks.md"`, defined as `REMARKS_FILENAME` in
+    [soup/entry_util.h](https://github.com/ioccc-src/mkiocccentry/blob/master/soup/entry_util.h)
+    in the [mkiocccentry repo](https://github.com/ioccc-src/mkiocccentry/), and
+    is your `remarks.md]` file.
+    See the
+    FAQ on "[remarks.md](#remarks_md)"
+    for more information.
+
+    **NOTE:** if this is **NOT** the case you stand a great chance of having your
+    submission rejected for violating [Rule 17](next/rules.html#rule17)!
+
+    **NOTE:** if you provide to `mkiocccentry` a different filename it will be
+    copied to `remarks.md`.
+
+The `manifest` **array** also **OPTIONALLY** has one or more of the field:
+
+- `extra_file` (double quoted string)
+
+    * Any additional file that you need or want to include with your submission.
+
+    **NOTE:** this MUST **NOT** match a mandatory filename (see above list) and
+    `chkentry` will verify this for you; it is **ALSO** an **error** if the
+    filenames are not unique. In these cases you stand a great risk of having
+    your submission rejected for violating [Rule 17](next/rules.html#rule17)! On
+    the other hand, **ONLY** `mkiocccentry` will verify that the files exist and
+    can be read; `txzchk(1)` will **NOT** do this for you as it only **LISTS**
+    the tarball: it does **NOT** extract it. Even so, the [Judges](judges.html)
+    **WILL** extract the tarball and if a file listed in the manifest does not
+    exist your submission will very likely be rejected for not being as
+    documented!
+
+Finally, after the `manifest` **array**, the following fields **MUST** exist:
+
 - `formed_timestamp` (number)
     * Seconds since epoch when JSON (`.auth.json` or `.info.json`) file was formed (see `gettimeofday(2)`).
 
@@ -1253,10 +1285,10 @@ The file also contains the following details:
     in the [mkiocccentry repo](https://github.com/ioccc-src/mkiocccentry/). If
     this is not the case your submission **WILL BE** rejected!
 
+
 This file will be verified with the `chkentry(1)` tool and if there are any
-problems **it is an error**. If there is an error the tarball will **NOT** be
-formed by `mkiocccentry`; otherwise the `txzchk(1)` tool will be executed on the
-tarball.
+problems **it is an error** and the tarball will **NOT** be formed by
+`mkiocccentry`; otherwise the `txzchk(1)` tool will be executed on the tarball.
 
 The [Judges](judges.html) **WILL** use `chkentry(1)` on this file during the
 judging process and if it does not pass your submission **WILL BE** rejected.
@@ -1271,6 +1303,9 @@ valid by `chkentry`) your submission would be rejected for violating [Rule
 17](next/rules.html#rule17) and in particular because `chkentry` would not
 validate the `.info.json` file.
 
+If you wish to **verify** that your `.info.json` file is valid **JSON** then see the
+[validating JSON documents](#validating_json) in the
+FAQ on "[author_handle.json](#author_json)".
 
 <div id="faq1">
 ## Section 1: History of the IOCCC