mirror/ioccc
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Fix FAQs on .auth.json and .info.json

Browse Source 
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.
This commit is contained in:
Cody Boone Ferguson committed 2024-07-25 11:58:18 -07:00
1 parent 3c33c40ff7
commit bf2e90f2da
2 files changed
+416 -352
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

faq.html
+206 -177
View File
@@ -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>
faq.md
+210 -175
View File
@@ -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