Add FAQs about the mkiocccentry tools
Several new FAQ entries have been added to discuss some of the details of chkentry, txzchk, fnamchk, jparse and maybe others that are related to the rules and guidelines (and in particular rule 17 and how to package submission tarballs). As there are new FAQ entries on these (which is much of what was in the guidelines) the guidelines have been shortened for these additions. Looking over the rendered html files it seems okay but I believe that these entries are works in progress and not complete. For reference the new FAQ version is 28.0.3 2024-07-27 and the new guidelines version is 28.11 2024-07-27.
This commit is contained in:
Cody Boone Ferguson committed
1 parent
5b4d848cb3
commit
b70c510124
4 files changed
+783
-590
No files matched your search
@@ -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.2 2024-07-26</strong>.</p>
|
||||
<p>This is FAQ version <strong>28.0.3 2024-07-27</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>
|
||||
@@ -403,6 +403,11 @@
|
||||
<li><a class="normal" href="#faq0_8">0.8 - How do I report bugs in a <code>mkiocccentry</code> tool?</a></li>
|
||||
<li><a class="normal" href="#faq0_9">0.9 - What is a <code>.auth.json</code> file?</a></li>
|
||||
<li><a class="normal" href="#faq0_10">0.10 - What is a <code>.info.json</code> file?</a></li>
|
||||
<li><a class="normal" href="#faq0_11">0.11 - How can I validate any JSON document?</a></li>
|
||||
<li><a class="normal" href="#faq0_12">0.12 - How can I validate my <code>.auth.json</code> and/or <code>.info.json</code> files?</a></li>
|
||||
<li><a class="normal" href="#faq0_13">0.13 - How can I validate my submission tarball?</a></li>
|
||||
<li><a class="normal" href="#faq0_14">0.14 - What is the <code>fnamchk</code> tool?</a></li>
|
||||
<li><a class="normal" href="#faq0_15">0.15 - What is the <code>mkiocccentry</code> tool and how do I use it?</a></li>
|
||||
</ul>
|
||||
<h2 id="section-1---history-of-the-ioccc">Section 1 - <a href="#faq1">History of the IOCCC</a></h2>
|
||||
<ul>
|
||||
@@ -984,31 +989,31 @@ See
|
||||
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>
|
||||
<li><p><code>email</code> (<code>null</code> 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>
|
||||
<li><p><code>url</code> (<code>null</code> 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>
|
||||
<li><p><code>alt_url</code> (<code>null</code> 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>
|
||||
<li><p><code>mastodon</code> (<code>null</code> 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>
|
||||
<li><p><code>github</code> (<code>null</code> 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>
|
||||
<li><p><code>affiliation</code> (<code>null</code> or double quoted string)</p>
|
||||
<ul>
|
||||
<li>This author’s <strong>affiliation</strong>, if any, or <code>null</code> if not provided.</li>
|
||||
</ul>
|
||||
@@ -1109,8 +1114,7 @@ valid by <code>chkentry</code>) your submission would be rejected for violating
|
||||
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>
|
||||
FAQ on “<a href="#validating_json">validating JSON documents</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>
|
||||
@@ -1545,8 +1549,262 @@ valid by <code>chkentry</code>) your submission would be rejected for violating
|
||||
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>
|
||||
FAQ on “<a href="#validating_json">validating JSON documents</a>”.</p>
|
||||
<div id="faq0_11">
|
||||
<div id="validating_json">
|
||||
<div id="jparse">
|
||||
<h3 id="faq-0.11-how-can-i-validate-any-json-document">FAQ 0.11: How can I validate any JSON document?</h3>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
<p>If you want or need to verify that a JSON document (as a string or file) is
|
||||
valid, you can use the
|
||||
<a href="https://github.com/ioccc-src/mkiocccentry/blob/master/jparse/README.md">jparse</a>
|
||||
tool. This tool, <code>jparse(1)</code>, is, for the time being, in the <a href="https://github.com/ioccc-src/mkiocccentry">mkiocccentry
|
||||
repo</a>, but <!--XXX - update the above
|
||||
URL to point to the jparse repo when it is populated --> will later be in a
|
||||
separate repo. In any case you need to download the repo or <code>git clone</code> it and
|
||||
then compile it (cd to the directory and then run <code>make all</code>). If you wish to
|
||||
make it easier you can then do <code>make install</code> either as root or via <code>sudo</code> so
|
||||
you can run the tool from any path.</p>
|
||||
<p>The syntax of <code>jparse(1)</code> is very simple:</p>
|
||||
<pre class="<!--sh-->"><code> jparse foo.json</code></pre>
|
||||
<p>If the tool shows <code>valid JSON</code> then the document is valid JSON; otherwise it’ll
|
||||
show an error message. If you don’t want to see any output unless it is invalid
|
||||
you can specify the <code>-q</code> option to <code>jparse</code>. In that case an exit code of 0
|
||||
indicates the JSON is valid.</p>
|
||||
<p>If you want to see more information about the parsing you can increase the
|
||||
verbosity with the <code>-v</code> option. For instance:</p>
|
||||
<pre class="<!--sh-->"><code> jparse -v 3 foo.json</code></pre>
|
||||
<p>If the tool is not installed then you will obviously have to specify the path of
|
||||
the tool.</p>
|
||||
<div id="faq0_12">
|
||||
<div id="validating_auth_info_json">
|
||||
<div id="chkentry">
|
||||
<h3 id="faq-0.12-how-can-i-validate-my-.auth.json-andor-.info.json-files">FAQ 0.12: How can I validate my <code>.auth.json</code> and/or <code>.info.json</code> files?</h3>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
<p>If you want to validate the <code>.auth.json</code> or <code>.info.json</code> files you
|
||||
should use <code>chkentry(1)</code> from the <a href="https://github.com/ioccc-src/mkiocccentry">mkiocccentry
|
||||
repo</a>.</p>
|
||||
<p><code>chkentry</code> uses the <a href="https://github.com/ioccc-src/mkiocccentry/blob/master/jparse/README.md">jparse</a>
|
||||
API; you can use the <code>jparse</code> tool itself to validate JSON documents, discussed
|
||||
above in the
|
||||
FAQ on “<a href="#validating_json">validating JSON documents</a>”
|
||||
but the <code>chkentry</code> tool has <strong>additional</strong> checks on these two IOCCC specific files.
|
||||
See the
|
||||
FAQ on “<a href="#auth_json">.auth.json</a>”
|
||||
and
|
||||
FAQ on “<a href="#info_json">.info.json</a>”
|
||||
for more details on these files.</p>
|
||||
<p>The <code>chkentry(1)</code> tool accepts more than one command line form.
|
||||
If you pass a single argument, it is expected to be a directory that has both
|
||||
<code>.auth.json</code> and <code>.info.json</code> in it. You can also specify a <code>.auth.json</code> and/or
|
||||
<code>.info.json</code> file. An argument of “<code>.</code>” will skip that file. For instance:</p>
|
||||
<pre><code> # test entry directory test_work:
|
||||
chkentry test_work
|
||||
|
||||
# run checks on .info.json:
|
||||
chkentry .info.json .
|
||||
|
||||
# run checks on .auth.json:
|
||||
chkentry . .auth.json
|
||||
|
||||
# run checks on .info.json and .auth.json:
|
||||
chkentry .info.json .auth.json</code></pre>
|
||||
<p>If there is a <a href="https://www.json.org/json-en.html">JSON</a> issue detected by
|
||||
<code>jparse(3)</code>, then there is a <a href="https://www.json.org/json-en.html">JSON</a> error and
|
||||
<code>chkentry(1)</code> will report it as an <strong>error</strong>. If the parsing is OK (i.e. valid
|
||||
JSON) but there is an issue in one or both of the
|
||||
<a href="https://www.json.org/json-en.html">JSON</a> files in <strong>the context of the IOCCC</strong>,
|
||||
it will report this as an <strong>error</strong>. Thus, if you were to package your
|
||||
submission manually then you would be violating <a href="next/rules.html#rule17">Rule
|
||||
17</a>.</p>
|
||||
<div id="faq0_13">
|
||||
<div id="txzchk">
|
||||
<div id="tarball">
|
||||
<h3 id="faq-0.13---how-can-i-validate-my-submission-tarball">FAQ 0.13 - How can I validate my submission tarball?</a></h3>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
<p>The tool that validates submission tarballs can be obtained from the <a href="https://github.com/ioccc-src/mkiocccentry">IOCCC
|
||||
mkiocccentry repo</a>. The
|
||||
<code>mkiocccentry</code> tool itself will run the validator <strong>after</strong> forming the tarball.
|
||||
However, you may wish to manually validate the tarball. The tool that does this
|
||||
is <code>txzchk</code>.</p>
|
||||
<p>If you wish to validate the tarball without running the <code>mkiocccentry(1)</code> tool,
|
||||
for instance the tarball
|
||||
<code>submit.12345678-1234-4321-abcd-1234567890ab-2.1720636351.txz</code> you can, after
|
||||
installing the tools, do:</p>
|
||||
<pre><code> txzchk submit.12345678-1234-4321-abcd-1234567890ab-2.1720636351.txz</code></pre>
|
||||
<p>Assuming that the tarball exists and is valid, you should see no output.</p>
|
||||
<p>If you wish to see the contents, for instance like <code>mkiocccentry(1)</code> does, you
|
||||
could do:</p>
|
||||
<pre><code> txzchk -v 1 submit.12345678-1234-4321-abcd-1234567890ab-2.1720636351.txz</code></pre>
|
||||
<p>As the <a href="next/guidelines.html#txzchk">guidelines state</a>, it is beyond the scope
|
||||
of this document to discuss the many tests that <code>txzchk(1)</code> runs; if you must
|
||||
know we refer you to the <a href="https://github.com/ioccc-src/mkiocccentry/blob/master/txzchk.c">source
|
||||
code</a>.</p>
|
||||
<div id="faq0_14">
|
||||
<div id="fnamchk">
|
||||
<div id="tarball_filename">
|
||||
<h3 id="faq-0.14---what-is-the-fnamchk-tool">FAQ 0.14 - What is the <code>fnamchk</code> tool?</h3>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
<p>This tool, which is in the <a href="https://github.com/ioccc-src/mkiocccentry">mkiocccentry
|
||||
repo</a>, validates the directory name
|
||||
of your submission.</p>
|
||||
<p>Rather than <code>mkiocccentry</code> running this tool manually, <code>txzchk</code>’s algorithm uses
|
||||
the output of this tool. If you wish to validate your tarball filename manually,
|
||||
you can do so. For instance:</p>
|
||||
<pre><code> fnamchk submit.12345678-1234-4321-abcd-1234567890ab-2.1720636351.txz</code></pre>
|
||||
<p>Assuming everything is OK, it would show:</p>
|
||||
<blockquote>
|
||||
<p><code>12345678-1234-4321-abcd-1234567890ab-2</code></p>
|
||||
</blockquote>
|
||||
<p>See also the
|
||||
FAQ on “<a href="#txzchk">validating your submission tarball</a>”
|
||||
for more information.</p>
|
||||
<div id="faq0_15">
|
||||
<div id="mkiocccentry">
|
||||
<h3 id="faq-0.15---what-is-the-mkiocccentry-tool-and-how-do-i-use-it">FAQ 0.15 - What is the <code>mkiocccentry</code> tool and how do I use it?</h3>
|
||||
</div>
|
||||
</div>
|
||||
<p>This tool also comes from the <a href="https://github.com/ioccc-src/mkiocccentry">mkiocccentry
|
||||
repo</a> and it is <strong>required</strong> that you
|
||||
use it to package your submission. Not doing so puts you at a great risk of
|
||||
violating the <a href="next/rules.html">Rules</a> and in particular <a href="next/rules.html#rule17">Rule
|
||||
17</a>. The <code>mkiocccentry</code> tool first gathers your source
|
||||
code, your Makefile, your remarks, other information about your submission,
|
||||
information about the author (or authors) and then runs a lot of tests before (if
|
||||
all is OK) forming your tarball. After this is done it will additionally run the
|
||||
<code>txzchk(1)</code> tool (which runs the <code>fnamchk(1)</code> tool) on the submission tarball.</p>
|
||||
<p>See the
|
||||
FAQ on “<a href="#submit">submitting to the IOCCC</a>”
|
||||
for details on how to register for the IOCCC.</p>
|
||||
<p>Once you have registered, you will need to package your entry with the
|
||||
<code>mkiocccentry</code> tool. The below details discuss this very important tool. As it
|
||||
is complicated we will explain how to use this tool.</p>
|
||||
<p>As the <a href="next/guidelines.html">Guidelines</a> state, the synopsis is:</p>
|
||||
<pre><code> mkiocccentry [options] work_dir prog.c \
|
||||
Makefile remarks.md [file ...]</code></pre>
|
||||
<p>… where <code>work_dir</code> is a directory that will be used to build the submission
|
||||
tarball, <code>prog.c</code> is your submission source code, <code>Makefile</code> is your submission’s
|
||||
<code>Makefile</code>, <code>remarks.md</code> are your remarks (that will be the basis of the
|
||||
<code>README.md</code> file which will be used to form the <code>index.html</code> file, if your
|
||||
submission wins) and the remaining args are the paths to any other files you
|
||||
wish to submit.</p>
|
||||
<p>The <code>work_dir</code> <strong>MUST</strong> already exist, as a directory, and it is an error if it
|
||||
is not a directory that can be written to. In <strong>this</strong> directory your <strong>submission
|
||||
directory</strong> will be created, with the name based on your IOCCC registration
|
||||
username, which is <strong>in the form of a UUID</strong> and submission number; see the
|
||||
<a href="next/rules.html">rules</a> for more details on this, and in particular <a href="next/rules.html#rule17">Rule
|
||||
17</a>.</p>
|
||||
<p>If the <strong><em>subdirectory</em> in the <em>work directory</em></strong> already exists, you will have to
|
||||
move it, remove it or otherwise specify a different work directory (<strong>NOT</strong> the
|
||||
subdirectory), as it needs to be empty and the <code>mkiocccentry(1)</code> tool does not
|
||||
check this for you as it could not do anything about anyway.</p>
|
||||
<p>This <em>subdirectory is where your files will be <strong>copied</strong> to</em>. Your <em>submission
|
||||
tarball</em> (which you will upload to the submit server) that <code>txzchk(1)</code> will
|
||||
validate <em>will be placed in the <strong>work directory</strong></em>, and <strong>its <em>contents</em> will
|
||||
be the <em>subdirectory</em> with your submission’s files</strong>.</p>
|
||||
<p>The <code>mkiocccentry(1)</code> tool will ask you for information about your
|
||||
submission <em>as well as author details</em> (that will only be looked at if the
|
||||
submission wins), run some tests and run a number of other tools, as already
|
||||
mentioned and as described below.</p>
|
||||
<p>To help you with editing a submission, the <code>mkiocccentry(1)</code> tool has
|
||||
some options to write <em>OR</em> read from an answers file so you do not have to input
|
||||
the information about the author(s) and the submission itself, after saving the
|
||||
answers to a file. To write to <code>answers.txt</code> try:</p>
|
||||
<pre><code> mkiocccentry -a answers.txt ...</code></pre>
|
||||
<p>Alternatively, if you wish to overwrite a file, you can use the <code>-A</code>
|
||||
flag with the same option argument. Be <strong>very careful</strong> that you do not accidentally
|
||||
overwrite your <code>prog.c</code> or some other important file!</p>
|
||||
<p>To make use of the answers file, use the <code>-i answers</code> option like:</p>
|
||||
<pre><code> mkiocccentry -i answers.txt ...</code></pre>
|
||||
<div id="mkiocccentry_checks">
|
||||
<h4 id="mkiocccentry-checks"><code>mkiocccentry</code> checks</h4>
|
||||
</div>
|
||||
<p><code>mkiocccentry(1)</code> will check and warn about the following conditions:</p>
|
||||
<ul>
|
||||
<li>If the files do not exist, are not regular files or cannot be read.</li>
|
||||
<li>If <code>prog.c</code> violates <a href="next/rules.html#rule2">Rule 2</a> (see
|
||||
<a href="https://github.com/ioccc-src/mkiocccentry/blob/master/iocccsize.c">iocccsize.c</a>).</li>
|
||||
<li>If <code>prog.c</code> is empty.</li>
|
||||
<li>If <code>prog.c</code> has any high bit char (see
|
||||
<a href="https://github.com/ioccc-src/mkiocccentry/blob/master/iocccsize.c">iocccsize.c</a>).</li>
|
||||
<li>If <code>prog.c</code> has any NUL char (see
|
||||
<a href="https://github.com/ioccc-src/mkiocccentry/blob/master/iocccsize.c">iocccsize.c</a>).</li>
|
||||
<li>If <code>prog.c</code> has any unknown or invalid trigraph (see
|
||||
<a href="https://github.com/ioccc-src/mkiocccentry/blob/master/iocccsize.c">iocccsize.c</a>).</li>
|
||||
<li>If <code>prog.c</code> triggers a word buffer overflow (see
|
||||
<a href="https://github.com/ioccc-src/mkiocccentry/blob/master/iocccsize.c">iocccsize.c</a>).</li>
|
||||
<li>If <code>prog.c</code> triggers an <code>ungetc(3)</code> error (see
|
||||
<a href="https://github.com/ioccc-src/mkiocccentry/blob/master/iocccsize.c">iocccsize.c</a>).</li>
|
||||
<li>If the first rule in the <code>Makefile</code> is not <code>all</code>.</li>
|
||||
<li>If the <code>Makefile</code> does not have a <code>clean</code> rule.</li>
|
||||
<li>If the <code>Makefile</code> does not have a <code>clobber</code> rule.</li>
|
||||
<li>If the <code>Makefile</code> does not have a <code>try</code> rule.</li>
|
||||
<li>If the <code>remarks.md</code> is empty.</li>
|
||||
</ul>
|
||||
<p>Conditions that one must correct, and which <code>mkiocccentry(1)</code> will prompt until
|
||||
they are correct, are:</p>
|
||||
<ul>
|
||||
<li>Your <em>title</em> is not in the range of 1 through <code>MAX_TITLE_LEN</code> chars (see
|
||||
<a href="https://github.com/ioccc-src/mkiocccentry/blob/master/soup/limit_ioccc.h">limit_ioccc.h</a>).</li>
|
||||
<li>Your <em>title</em> does not match the regexp <code>^[0-9a-z][0-9a-z._+-]*$</code>.</li>
|
||||
<li>Your <em>abstract</em> is not between 1 and <code>MAX_ABSTRACT_LEN</code> chars
|
||||
(see <a href="https://github.com/ioccc-src/mkiocccentry/blob/master/soup/limit_ioccc.h">limit_ioccc.h</a>).</li>
|
||||
<li>the author count is not 1 through <code>MAX_AUTHORS</code> (see
|
||||
<a href="https://github.com/ioccc-src/mkiocccentry/blob/master/soup/limit_ioccc.h">limit_ioccc.h</a>).</li>
|
||||
<li>An author <em>name</em> is not 1 through <code>MAX_NAME_LEN</code> chars (see
|
||||
<a href="https://github.com/ioccc-src/mkiocccentry/blob/master/soup/limit_ioccc.h">limit_ioccc.h</a>).</li>
|
||||
<li>Duplicate author <em>name</em>.</li>
|
||||
<li><em>Country code</em> is invalid (not ISO 3166-1 2 character
|
||||
codes).</li>
|
||||
<li>An <em>email</em>, if provided, is not in the format of <code>x@y</code> or
|
||||
if <code>x</code> or <code>y</code> contain a <code>@</code>, are empty or if the total length is longer than
|
||||
<code>MAX_EMAIL_LEN</code> (see <a href="https://github.com/ioccc-src/mkiocccentry/blob/master/soup/limit_ioccc.h">limit_ioccc.h</a>).</li>
|
||||
<li>A <em>URL</em> or <em>alt URL</em>, if provided, does not start with <code>http://</code>
|
||||
or <code>https://</code> or is longer than <code>MAX_URL_LEN</code> chars (see
|
||||
<a href="https://github.com/ioccc-src/mkiocccentry/blob/master/soup/limit_ioccc.h">limit_ioccc.h</a>)
|
||||
or does not have anything after the <code>http://</code> or <code>https://</code>.</li>
|
||||
<li>A <em>mastodon handle</em>, if provided, is not in the form of
|
||||
<code>@user@site</code> (i.e. starts with an <code>@</code>, has text following it and then another
|
||||
<code>@</code> followed by more text and has no other <code>@</code>) or is longer than <code>MAX_MASTODON_LEN</code> (see
|
||||
<a href="https://github.com/ioccc-src/mkiocccentry/blob/master/soup/limit_ioccc.h">limit_ioccc.h</a>).</li>
|
||||
<li>A <em>GitHub account</em>, if provided, does not start with an <code>@</code>,
|
||||
has more than one <code>@</code> or is longer than <code>MAX_GITHUB_LEN</code> (see
|
||||
<a href="https://github.com/ioccc-src/mkiocccentry/blob/master/soup/limit_ioccc.h">limit_ioccc.h</a>).</li>
|
||||
<li>An <em>affiliation</em>, if provided, is longer than
|
||||
<code>MAX_AFFILIATION_LEN</code> (see <a href="https://github.com/ioccc-src/mkiocccentry/blob/master/soup/limit_ioccc.h">limit_ioccc.h</a>).</li>
|
||||
<li>An <em>author handle</em>, if the default is not accepted, does
|
||||
not match the regexp <code>^[0-9A-Za-z][0-9A-Za-z._+-]*$</code>.</li>
|
||||
<li>An <em>author handle</em> is repeated.</li>
|
||||
<li>The output of <code>ls</code> on the submission directory is incorrect.</li>
|
||||
</ul>
|
||||
<p>Although the <code>mkiocccentry(1)</code> tool will verify everything for you, you may wish
|
||||
to validate different parts individually with the different tools. As the
|
||||
<a href="rules.html">rules</a> state, each of these tools has a <code>-h</code> option.</p>
|
||||
<p>See the
|
||||
FAQ on “<a href="#jparse">jparse</a>”,
|
||||
the
|
||||
FAQ on “<a href="#auth_json">.auth.json</a>”,
|
||||
the
|
||||
FAQ on “<a href="#info_json">.info.json</a>”,
|
||||
the
|
||||
FAQ on “<a href="#chkentry">chkentry</a>”,
|
||||
the
|
||||
FAQ on “<a href="#txzchk">txzchk</a>”
|
||||
and the
|
||||
FAQ on “<a href="#fnamchk">fnamchk</a>”
|
||||
for more details on the tools that <code>mkiocccentry</code> either executes directly or
|
||||
indirectly as part of the packaging process, especially if you wish to run one
|
||||
or more of these tools manually.</p>
|
||||
<p>See also the <a href="next/guidelines.html">Guidelines</a> and the <a href="next/rules.html">Rules</a>
|
||||
(and in particular <a href="next/rules.html#rule17">Rule 17</a>).</p>
|
||||
<div id="faq1">
|
||||
<h2 id="section-1-history-of-the-ioccc">Section 1: History of the IOCCC</h2>
|
||||
</div>
|
||||
@@ -2751,9 +3009,9 @@ provided by the author and any other file in the winning entry, found under the
|
||||
entry’s subdirectory.</p>
|
||||
<p>If you downloaded <code>1984/mullender/1984_mullender.tar.bz2</code>, for instance, you might
|
||||
then do:</p>
|
||||
<div class="sourceCode" id="cb59"><pre class="sourceCode sh"><code class="sourceCode bash"><span id="cb59-1"><a href="#cb59-1" aria-hidden="true" tabindex="-1"></a> <span class="bu">cd</span> 1984/mullender</span>
|
||||
<span id="cb59-2"><a href="#cb59-2" aria-hidden="true" tabindex="-1"></a> <span class="fu">make</span> everything</span>
|
||||
<span id="cb59-3"><a href="#cb59-3" aria-hidden="true" tabindex="-1"></a> <span class="ex">./mullender.alt</span></span></code></pre></div>
|
||||
<div class="sourceCode" id="cb68"><pre class="sourceCode sh"><code class="sourceCode bash"><span id="cb68-1"><a href="#cb68-1" aria-hidden="true" tabindex="-1"></a> <span class="bu">cd</span> 1984/mullender</span>
|
||||
<span id="cb68-2"><a href="#cb68-2" aria-hidden="true" tabindex="-1"></a> <span class="fu">make</span> everything</span>
|
||||
<span id="cb68-3"><a href="#cb68-3" aria-hidden="true" tabindex="-1"></a> <span class="ex">./mullender.alt</span></span></code></pre></div>
|
||||
<p>to compile all versions and then run the alternate version (if you have
|
||||
a PDP-11 or VAX-11 you would be able to run the original version). For more help
|
||||
on compiling entries, see also the
|
||||
@@ -2794,8 +3052,8 @@ if you switched to each entry’s directory and ran <code>make everything</code>
|
||||
<p>If you download the 1984 tarball, i.e. <code>1984/1984.tar.bz2</code>, then you might
|
||||
extract it and then switch to the directory and compile everything of each
|
||||
entry:</p>
|
||||
<div class="sourceCode" id="cb60"><pre class="sourceCode sh"><code class="sourceCode bash"><span id="cb60-1"><a href="#cb60-1" aria-hidden="true" tabindex="-1"></a> <span class="bu">cd</span> 1984</span>
|
||||
<span id="cb60-2"><a href="#cb60-2" aria-hidden="true" tabindex="-1"></a> <span class="fu">make</span> everything</span></code></pre></div>
|
||||
<div class="sourceCode" id="cb69"><pre class="sourceCode sh"><code class="sourceCode bash"><span id="cb69-1"><a href="#cb69-1" aria-hidden="true" tabindex="-1"></a> <span class="bu">cd</span> 1984</span>
|
||||
<span id="cb69-2"><a href="#cb69-2" aria-hidden="true" tabindex="-1"></a> <span class="fu">make</span> everything</span></code></pre></div>
|
||||
<p>For more help on compiling entries, see also the
|
||||
FAQ on “<a href="#make_rules">IOCCC Makefile rules</a>”.</p>
|
||||
<p>Of course in this case you can also switch to individual entries and look at the
|
||||
@@ -3558,12 +3816,17 @@ in the case of <a href="https://github.com/ioccc-src/temp-test-ioccc/blob/master
|
||||
<p><strong>TL:DR</strong>: The contents of these JSON files contain the best known
|
||||
information about authors of IOCCC entries and is used to help form
|
||||
HTML files as well to contact an author.</p>
|
||||
<p>The content of these JSON files are used by tools from a <a href="bin/index.html">bin directory tool</a>
|
||||
to help build HTML content for the <a href="https://www.ioccc.org">official IOCCC website</a>.
|
||||
For example, the <code>index.html</code> file for each IOCCC entry contains
|
||||
selected information about the authors. Tools from the <a href="bin/index.html">bin directory</a>
|
||||
use the content of these JSON files to generate the <code>index.html</code> files for each IOCCC
|
||||
winning entry.</p>
|
||||
<p><strong>NOTE</strong>: tools to validate the <code>author_handle.json</code> files, which are only for
|
||||
winning authors, are in the works (which will be documented after they are
|
||||
developed). See the
|
||||
FAQ on “<a href="#author_handle_faq">author handles</a>”
|
||||
for more information on author handles.</p>
|
||||
<p>The content of these JSON files are used by tools from the <a href="bin/index.html">bin directory</a>
|
||||
to help build HTML content for the <a href="https://www.ioccc.org">official IOCCC website</a>.</p>
|
||||
<p>For example, the <code>index.html</code> file for each IOCCC entry contains selected
|
||||
information about the authors. Tools from the <a href="bin/index.html">bin directory</a>
|
||||
use the content of these JSON files to generate the <code>index.html</code> files for each
|
||||
IOCCC winning entry.</p>
|
||||
<p>Moreover, should the <a href="judges.html">IOCCC judges</a> need to
|
||||
contact an authors of an IOCCC entry, they will consult the contents
|
||||
of the author’s JSON file for ways to contact them.</p>
|
||||
@@ -3617,33 +3880,12 @@ is to look at an example, the <code>author_handle.json</code> file for Yusuke En
|
||||
{ "entry_id" : "2020_endoh3" }
|
||||
]
|
||||
}</code></pre>
|
||||
<p>Before we walk you through the above JSON document, we will show you how to
|
||||
validate that the JSON is validly formed.</p>
|
||||
<div id="validating_json">
|
||||
<h5 id="validating-json-documents">Validating JSON documents</h5>
|
||||
</div>
|
||||
<p>Although special tools (that will validate <code>author_handle.json</code> files) are in
|
||||
the works (which will be documented here after they are developed) there is a
|
||||
way to validate all JSON documents including these files. Until those special
|
||||
tools are developed (which will do the same as this next tool but more) we
|
||||
request that you validate the JSON with this tool that we co-developed with Cody
|
||||
Boone Ferguson. This tool, <code>jparse(1)</code>, for the time being is in the
|
||||
<a href="https://github.com/ioccc-src/mkiocccentry">mkiocccentry repo</a> but will later be
|
||||
in a separate repo. In any case you need to download the repo or <code>git clone</code> it
|
||||
and then compile it (cd to the directory and then run <code>make</code>). If you wish to
|
||||
make it easier you can do <code>make install</code> so you can run the tool from any path
|
||||
but in any case the syntax is:</p>
|
||||
<pre class="<!--sh-->"><code> jparse foo.json</code></pre>
|
||||
<p>If the tool exits 0 (and shows no output) then the JSON is valid. If it is
|
||||
invalid you should get an error but for more details you can increase the
|
||||
verbosity with the <code>-v</code> flag like:</p>
|
||||
<pre class="<!--sh-->"><code> jparse -v 3 foo.json</code></pre>
|
||||
<p>If the tool is not installed then you will obviously have to specify the path of
|
||||
the tool.</p>
|
||||
<p>If you wish to validate every JSON file in <code>author/</code> then you could do so like:</p>
|
||||
<pre class="<!--sh-->"><code> for auth in *.json; do jparse 2>/dev/null "$auth" || echo "$auth is invalid JSON" ; done</code></pre>
|
||||
<p><strong>NOTE</strong>: if you need to just check the validity of a JSON document then see the
|
||||
FAQ on “<a href="#validating_json">validating JSON documents</a>”. Taking that FAQ in mind,
|
||||
if you wish to validate every JSON file in <code>author/</code> then you could do so like:</p>
|
||||
<pre class="<!--sh-->"><code> for auth in *.json; do jparse -q "$auth" || echo "$auth is invalid JSON" ; done</code></pre>
|
||||
<p>If you see any output then it will say which file or files are invalid JSON
|
||||
(this should not actually happen).</p>
|
||||
(this should not actually happen, however).</p>
|
||||
<div id="walk_through_author_json">
|
||||
<h5 id="walk-through-of-an-author_handle.json-file">Walk through of an <code>author_handle.json</code> file</h5>
|
||||
</div>
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# FAQ Table of Contents
|
||||
|
||||
This is FAQ version **28.0.2 2024-07-26**.
|
||||
This is FAQ version **28.0.3 2024-07-27**.
|
||||
|
||||
|
||||
## Section 0 - [Submitting entries to a new IOCCC](#faq0)
|
||||
@@ -15,6 +15,11 @@ This is FAQ version **28.0.2 2024-07-26**.
|
||||
- <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_11">0.11 - How can I validate any JSON document?</a>
|
||||
- <a class="normal" href="#faq0_12">0.12 - How can I validate my `.auth.json` and/or `.info.json` files?</a>
|
||||
- <a class="normal" href="#faq0_13">0.13 - How can I validate my submission tarball?</a>
|
||||
- <a class="normal" href="#faq0_14">0.14 - What is the `fnamchk` tool?</a>
|
||||
- <a class="normal" href="#faq0_15">0.15 - What is the `mkiocccentry` tool and how do I use it?</a>
|
||||
|
||||
|
||||
## Section 1 - [History of the IOCCC](#faq1)
|
||||
@@ -736,26 +741,26 @@ author(s) of the submission:
|
||||
|
||||
**NOTE:** in `mkiocccentry` use `XX` if you want your location to be anonymous.
|
||||
|
||||
- `email` (null or double quoted string)
|
||||
- `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)
|
||||
- `url` (`null` or double quoted string)
|
||||
* The primary **URL** of this author, or `null` if not provided.
|
||||
|
||||
- `alt_url` (null or double quoted string)
|
||||
- `alt_url` (`null` or double quoted string)
|
||||
* The **alt URL** of this author, or `null` if not provided.
|
||||
|
||||
- `mastodon` (null or double quoted string)
|
||||
- `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)
|
||||
- `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)
|
||||
- `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
|
||||
@@ -859,8 +864,7 @@ valid by `chkentry`) your submission would be rejected for violating [Rule
|
||||
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)".
|
||||
FAQ on "[validating JSON documents](#validating_json)".
|
||||
|
||||
|
||||
<div id="faq0_10">
|
||||
@@ -1304,8 +1308,332 @@ valid by `chkentry`) your submission would be rejected for violating [Rule
|
||||
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)".
|
||||
FAQ on "[validating JSON documents](#validating_json)".
|
||||
|
||||
|
||||
<div id="faq0_11">
|
||||
<div id="validating_json">
|
||||
<div id="jparse">
|
||||
### FAQ 0.11: How can I validate any JSON document?
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
If you want or need to verify that a JSON document (as a string or file) is
|
||||
valid, you can use the
|
||||
[jparse](https://github.com/ioccc-src/mkiocccentry/blob/master/jparse/README.md)
|
||||
tool. This tool, `jparse(1)`, is, for the time being, in the [mkiocccentry
|
||||
repo](https://github.com/ioccc-src/mkiocccentry), but <!--XXX - update the above
|
||||
URL to point to the jparse repo when it is populated --> will later be in a
|
||||
separate repo. In any case you need to download the repo or `git clone` it and
|
||||
then compile it (cd to the directory and then run `make all`). If you wish to
|
||||
make it easier you can then do `make install` either as root or via `sudo` so
|
||||
you can run the tool from any path.
|
||||
|
||||
The syntax of `jparse(1)` is very simple:
|
||||
|
||||
|
||||
``` <!--sh-->
|
||||
jparse foo.json
|
||||
```
|
||||
|
||||
If the tool shows `valid JSON` then the document is valid JSON; otherwise it'll
|
||||
show an error message. If you don't want to see any output unless it is invalid
|
||||
you can specify the `-q` option to `jparse`. In that case an exit code of 0
|
||||
indicates the JSON is valid.
|
||||
|
||||
If you want to see more information about the parsing you can increase the
|
||||
verbosity with the `-v` option. For instance:
|
||||
|
||||
``` <!--sh-->
|
||||
jparse -v 3 foo.json
|
||||
```
|
||||
|
||||
If the tool is not installed then you will obviously have to specify the path of
|
||||
the tool.
|
||||
|
||||
|
||||
<div id="faq0_12">
|
||||
<div id="validating_auth_info_json">
|
||||
<div id="chkentry">
|
||||
### FAQ 0.12: How can I validate my `.auth.json` and/or `.info.json` files?
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
If you want to validate the `.auth.json` or `.info.json` files you
|
||||
should use `chkentry(1)` from the [mkiocccentry
|
||||
repo](https://github.com/ioccc-src/mkiocccentry).
|
||||
|
||||
`chkentry` uses the [jparse](https://github.com/ioccc-src/mkiocccentry/blob/master/jparse/README.md)
|
||||
API; you can use the `jparse` tool itself to validate JSON documents, discussed
|
||||
above in the
|
||||
FAQ on "[validating JSON documents](#validating_json)"
|
||||
but the `chkentry` tool has **additional** checks on these two IOCCC specific files.
|
||||
See the
|
||||
FAQ on "[.auth.json](#auth_json)"
|
||||
and
|
||||
FAQ on "[.info.json](#info_json)"
|
||||
for more details on these files.
|
||||
|
||||
The `chkentry(1)` tool accepts more than one command line form.
|
||||
If you pass a single argument, it is expected to be a directory that has both
|
||||
`.auth.json` and `.info.json` in it. You can also specify a `.auth.json` and/or
|
||||
`.info.json` file. An argument of "`.`" will skip that file. For instance:
|
||||
|
||||
``` <!---sh-->
|
||||
# test entry directory test_work:
|
||||
chkentry test_work
|
||||
|
||||
# run checks on .info.json:
|
||||
chkentry .info.json .
|
||||
|
||||
# run checks on .auth.json:
|
||||
chkentry . .auth.json
|
||||
|
||||
# run checks on .info.json and .auth.json:
|
||||
chkentry .info.json .auth.json
|
||||
```
|
||||
|
||||
If there is a [JSON](https://www.json.org/json-en.html) issue detected by
|
||||
`jparse(3)`, then there is a [JSON](https://www.json.org/json-en.html) error and
|
||||
`chkentry(1)` will report it as an **error**. If the parsing is OK (i.e. valid
|
||||
JSON) but there is an issue in one or both of the
|
||||
[JSON](https://www.json.org/json-en.html) files in **the context of the IOCCC**,
|
||||
it will report this as an **error**. Thus, if you were to package your
|
||||
submission manually then you would be violating [Rule
|
||||
17](next/rules.html#rule17).
|
||||
|
||||
<div id="faq0_13">
|
||||
<div id="txzchk">
|
||||
<div id="tarball">
|
||||
### FAQ 0.13 - How can I validate my submission tarball?</a>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
The tool that validates submission tarballs can be obtained from the [IOCCC
|
||||
mkiocccentry repo](https://github.com/ioccc-src/mkiocccentry). The
|
||||
`mkiocccentry` tool itself will run the validator **after** forming the tarball.
|
||||
However, you may wish to manually validate the tarball. The tool that does this
|
||||
is `txzchk`.
|
||||
|
||||
If you wish to validate the tarball without running the `mkiocccentry(1)` tool,
|
||||
for instance the tarball
|
||||
`submit.12345678-1234-4321-abcd-1234567890ab-2.1720636351.txz` you can, after
|
||||
installing the tools, do:
|
||||
|
||||
``` <!---sh-->
|
||||
txzchk submit.12345678-1234-4321-abcd-1234567890ab-2.1720636351.txz
|
||||
```
|
||||
|
||||
Assuming that the tarball exists and is valid, you should see no output.
|
||||
|
||||
If you wish to see the contents, for instance like `mkiocccentry(1)` does, you
|
||||
could do:
|
||||
|
||||
``` <!---sh-->
|
||||
txzchk -v 1 submit.12345678-1234-4321-abcd-1234567890ab-2.1720636351.txz
|
||||
```
|
||||
|
||||
As the [guidelines state](next/guidelines.html#txzchk), it is beyond the scope
|
||||
of this document to discuss the many tests that `txzchk(1)` runs; if you must
|
||||
know we refer you to the [source
|
||||
code](https://github.com/ioccc-src/mkiocccentry/blob/master/txzchk.c).
|
||||
|
||||
<div id="faq0_14">
|
||||
<div id="fnamchk">
|
||||
<div id="tarball_filename">
|
||||
### FAQ 0.14 - What is the `fnamchk` tool?
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
This tool, which is in the [mkiocccentry
|
||||
repo](https://github.com/ioccc-src/mkiocccentry), validates the directory name
|
||||
of your submission.
|
||||
|
||||
Rather than `mkiocccentry` running this tool manually, `txzchk`'s algorithm uses
|
||||
the output of this tool. If you wish to validate your tarball filename manually,
|
||||
you can do so. For instance:
|
||||
|
||||
``` <!---sh-->
|
||||
fnamchk submit.12345678-1234-4321-abcd-1234567890ab-2.1720636351.txz
|
||||
```
|
||||
|
||||
Assuming everything is OK, it would show:
|
||||
|
||||
> `12345678-1234-4321-abcd-1234567890ab-2`
|
||||
|
||||
See also the
|
||||
FAQ on "[validating your submission tarball](#txzchk)"
|
||||
for more information.
|
||||
|
||||
|
||||
|
||||
<div id="faq0_15">
|
||||
<div id="mkiocccentry">
|
||||
### FAQ 0.15 - What is the `mkiocccentry` tool and how do I use it?
|
||||
</div>
|
||||
</div>
|
||||
|
||||
This tool also comes from the [mkiocccentry
|
||||
repo](https://github.com/ioccc-src/mkiocccentry) and it is **required** that you
|
||||
use it to package your submission. Not doing so puts you at a great risk of
|
||||
violating the [Rules](next/rules.html) and in particular [Rule
|
||||
17](next/rules.html#rule17). The `mkiocccentry` tool first gathers your source
|
||||
code, your Makefile, your remarks, other information about your submission,
|
||||
information about the author (or authors) and then runs a lot of tests before (if
|
||||
all is OK) forming your tarball. After this is done it will additionally run the
|
||||
`txzchk(1)` tool (which runs the `fnamchk(1)` tool) on the submission tarball.
|
||||
|
||||
See the
|
||||
FAQ on "[submitting to the IOCCC](#submit)"
|
||||
for details on how to register for the IOCCC.
|
||||
|
||||
Once you have registered, you will need to package your entry with the
|
||||
`mkiocccentry` tool. The below details discuss this very important tool. As it
|
||||
is complicated we will explain how to use this tool.
|
||||
|
||||
As the [Guidelines](next/guidelines.html) state, the synopsis is:
|
||||
|
||||
``` <!---sh-->
|
||||
mkiocccentry [options] work_dir prog.c \
|
||||
Makefile remarks.md [file ...]
|
||||
```
|
||||
|
||||
... where `work_dir` is a directory that will be used to build the submission
|
||||
tarball, `prog.c` is your submission source code, `Makefile` is your submission's
|
||||
`Makefile`, `remarks.md` are your remarks (that will be the basis of the
|
||||
`README.md` file which will be used to form the `index.html` file, if your
|
||||
submission wins) and the remaining args are the paths to any other files you
|
||||
wish to submit.
|
||||
|
||||
The `work_dir` **MUST** already exist, as a directory, and it is an error if it
|
||||
is not a directory that can be written to. In **this** directory your **submission
|
||||
directory** will be created, with the name based on your IOCCC registration
|
||||
username, which is **in the form of a UUID** and submission number; see the
|
||||
[rules](next/rules.html) for more details on this, and in particular [Rule
|
||||
17](next/rules.html#rule17).
|
||||
|
||||
If the **_subdirectory_ in the _work directory_** already exists, you will have to
|
||||
move it, remove it or otherwise specify a different work directory (**NOT** the
|
||||
subdirectory), as it needs to be empty and the `mkiocccentry(1)` tool does not
|
||||
check this for you as it could not do anything about anyway.
|
||||
|
||||
This _subdirectory is where your files will be **copied** to_. Your _submission
|
||||
tarball_ (which you will upload to the submit server) that `txzchk(1)` will
|
||||
validate _will be placed in the **work directory**_, and **its _contents_ will
|
||||
be the _subdirectory_ with your submission's files**.
|
||||
|
||||
The `mkiocccentry(1)` tool will ask you for information about your
|
||||
submission _as well as author details_ (that will only be looked at if the
|
||||
submission wins), run some tests and run a number of other tools, as already
|
||||
mentioned and as described below.
|
||||
|
||||
To help you with editing a submission, the `mkiocccentry(1)` tool has
|
||||
some options to write _OR_ read from an answers file so you do not have to input
|
||||
the information about the author(s) and the submission itself, after saving the
|
||||
answers to a file. To write to `answers.txt` try:
|
||||
|
||||
``` <!---sh-->
|
||||
mkiocccentry -a answers.txt ...
|
||||
```
|
||||
|
||||
Alternatively, if you wish to overwrite a file, you can use the `-A`
|
||||
flag with the same option argument. Be **very careful** that you do not accidentally
|
||||
overwrite your `prog.c` or some other important file!
|
||||
|
||||
To make use of the answers file, use the `-i answers` option like:
|
||||
|
||||
``` <!---sh-->
|
||||
mkiocccentry -i answers.txt ...
|
||||
```
|
||||
|
||||
<div id="mkiocccentry_checks">
|
||||
#### `mkiocccentry` checks
|
||||
</div>
|
||||
|
||||
`mkiocccentry(1)` will check and warn about the following conditions:
|
||||
|
||||
- If the files do not exist, are not regular files or cannot be read.
|
||||
- If `prog.c` violates [Rule 2](next/rules.html#rule2) (see
|
||||
[iocccsize.c](https://github.com/ioccc-src/mkiocccentry/blob/master/iocccsize.c)).
|
||||
- If `prog.c` is empty.
|
||||
- If `prog.c` has any high bit char (see
|
||||
[iocccsize.c](https://github.com/ioccc-src/mkiocccentry/blob/master/iocccsize.c)).
|
||||
- If `prog.c` has any NUL char (see
|
||||
[iocccsize.c](https://github.com/ioccc-src/mkiocccentry/blob/master/iocccsize.c)).
|
||||
- If `prog.c` has any unknown or invalid trigraph (see
|
||||
[iocccsize.c](https://github.com/ioccc-src/mkiocccentry/blob/master/iocccsize.c)).
|
||||
- If `prog.c` triggers a word buffer overflow (see
|
||||
[iocccsize.c](https://github.com/ioccc-src/mkiocccentry/blob/master/iocccsize.c)).
|
||||
- If `prog.c` triggers an `ungetc(3)` error (see
|
||||
[iocccsize.c](https://github.com/ioccc-src/mkiocccentry/blob/master/iocccsize.c)).
|
||||
- If the first rule in the `Makefile` is not `all`.
|
||||
- If the `Makefile` does not have a `clean` rule.
|
||||
- If the `Makefile` does not have a `clobber` rule.
|
||||
- If the `Makefile` does not have a `try` rule.
|
||||
- If the `remarks.md` is empty.
|
||||
|
||||
Conditions that one must correct, and which `mkiocccentry(1)` will prompt until
|
||||
they are correct, are:
|
||||
|
||||
- Your _title_ is not in the range of 1 through `MAX_TITLE_LEN` chars (see
|
||||
[limit_ioccc.h](https://github.com/ioccc-src/mkiocccentry/blob/master/soup/limit_ioccc.h)).
|
||||
- Your _title_ does not match the regexp `^[0-9a-z][0-9a-z._+-]*$`.
|
||||
- Your _abstract_ is not between 1 and `MAX_ABSTRACT_LEN` chars
|
||||
(see [limit_ioccc.h](https://github.com/ioccc-src/mkiocccentry/blob/master/soup/limit_ioccc.h)).
|
||||
- the author count is not 1 through `MAX_AUTHORS` (see
|
||||
[limit_ioccc.h](https://github.com/ioccc-src/mkiocccentry/blob/master/soup/limit_ioccc.h)).
|
||||
- An author _name_ is not 1 through `MAX_NAME_LEN` chars (see
|
||||
[limit_ioccc.h](https://github.com/ioccc-src/mkiocccentry/blob/master/soup/limit_ioccc.h)).
|
||||
- Duplicate author _name_.
|
||||
- _Country code_ is invalid (not ISO 3166-1 2 character
|
||||
codes).
|
||||
- An _email_, if provided, is not in the format of `x@y` or
|
||||
if `x` or `y` contain a `@`, are empty or if the total length is longer than
|
||||
`MAX_EMAIL_LEN` (see [limit_ioccc.h](https://github.com/ioccc-src/mkiocccentry/blob/master/soup/limit_ioccc.h)).
|
||||
- A _URL_ or _alt URL_, if provided, does not start with `http://`
|
||||
or `https://` or is longer than `MAX_URL_LEN` chars (see
|
||||
[limit_ioccc.h](https://github.com/ioccc-src/mkiocccentry/blob/master/soup/limit_ioccc.h))
|
||||
or does not have anything after the `http://` or `https://`.
|
||||
- A _mastodon handle_, if provided, is not in the form of
|
||||
`@user@site` (i.e. starts with an `@`, has text following it and then another
|
||||
`@` followed by more text and has no other `@`) or is longer than `MAX_MASTODON_LEN` (see
|
||||
[limit_ioccc.h](https://github.com/ioccc-src/mkiocccentry/blob/master/soup/limit_ioccc.h)).
|
||||
- A _GitHub account_, if provided, does not start with an `@`,
|
||||
has more than one `@` or is longer than `MAX_GITHUB_LEN` (see
|
||||
[limit_ioccc.h](https://github.com/ioccc-src/mkiocccentry/blob/master/soup/limit_ioccc.h)).
|
||||
- An _affiliation_, if provided, is longer than
|
||||
`MAX_AFFILIATION_LEN` (see [limit_ioccc.h](https://github.com/ioccc-src/mkiocccentry/blob/master/soup/limit_ioccc.h)).
|
||||
- An _author handle_, if the default is not accepted, does
|
||||
not match the regexp `^[0-9A-Za-z][0-9A-Za-z._+-]*$`.
|
||||
- An _author handle_ is repeated.
|
||||
- The output of `ls` on the submission directory is incorrect.
|
||||
|
||||
Although the `mkiocccentry(1)` tool will verify everything for you, you may wish
|
||||
to validate different parts individually with the different tools. As the
|
||||
[rules](rules.html) state, each of these tools has a `-h` option.
|
||||
|
||||
See the
|
||||
FAQ on "[jparse](#jparse)",
|
||||
the
|
||||
FAQ on "[.auth.json](#auth_json)",
|
||||
the
|
||||
FAQ on "[.info.json](#info_json)",
|
||||
the
|
||||
FAQ on "[chkentry](#chkentry)",
|
||||
the
|
||||
FAQ on "[txzchk](#txzchk)"
|
||||
and the
|
||||
FAQ on "[fnamchk](#fnamchk)"
|
||||
for more details on the tools that `mkiocccentry` either executes directly or
|
||||
indirectly as part of the packaging process, especially if you wish to run one
|
||||
or more of these tools manually.
|
||||
|
||||
See also the [Guidelines](next/guidelines.html) and the [Rules](next/rules.html)
|
||||
(and in particular [Rule 17](next/rules.html#rule17)).
|
||||
|
||||
<div id="faq1">
|
||||
## Section 1: History of the IOCCC
|
||||
@@ -4222,12 +4550,19 @@ Anonymous `author_handle`'s match this regexp:
|
||||
information about authors of IOCCC entries and is used to help form
|
||||
HTML files as well to contact an author.
|
||||
|
||||
The content of these JSON files are used by tools from a [bin directory tool](bin/index.html)
|
||||
**NOTE**: tools to validate the `author_handle.json` files, which are only for
|
||||
winning authors, are in the works (which will be documented after they are
|
||||
developed). See the
|
||||
FAQ on "[author handles](#author_handle_faq)"
|
||||
for more information on author handles.
|
||||
|
||||
The content of these JSON files are used by tools from the [bin directory](bin/index.html)
|
||||
to help build HTML content for the [official IOCCC website](https://www.ioccc.org).
|
||||
For example, the `index.html` file for each IOCCC entry contains
|
||||
selected information about the authors. Tools from the [bin directory](bin/index.html)
|
||||
use the content of these JSON files to generate the `index.html` files for each IOCCC
|
||||
winning entry.
|
||||
|
||||
For example, the `index.html` file for each IOCCC entry contains selected
|
||||
information about the authors. Tools from the [bin directory](bin/index.html)
|
||||
use the content of these JSON files to generate the `index.html` files for each
|
||||
IOCCC winning entry.
|
||||
|
||||
Moreover, should the [IOCCC judges](judges.html) need to
|
||||
contact an authors of an IOCCC entry, they will consult the contents
|
||||
@@ -4298,48 +4633,16 @@ As of _Thu Nov 30 23:51:12 UTC 2023_, the contents was as follows:
|
||||
}
|
||||
```
|
||||
|
||||
Before we walk you through the above JSON document, we will show you how to
|
||||
validate that the JSON is validly formed.
|
||||
|
||||
<div id="validating_json">
|
||||
##### Validating JSON documents
|
||||
</div>
|
||||
|
||||
Although special tools (that will validate `author_handle.json` files) are in
|
||||
the works (which will be documented here after they are developed) there is a
|
||||
way to validate all JSON documents including these files. Until those special
|
||||
tools are developed (which will do the same as this next tool but more) we
|
||||
request that you validate the JSON with this tool that we co-developed with Cody
|
||||
Boone Ferguson. This tool, `jparse(1)`, for the time being is in the
|
||||
[mkiocccentry repo](https://github.com/ioccc-src/mkiocccentry) but will later be
|
||||
in a separate repo. In any case you need to download the repo or `git clone` it
|
||||
and then compile it (cd to the directory and then run `make`). If you wish to
|
||||
make it easier you can do `make install` so you can run the tool from any path
|
||||
but in any case the syntax is:
|
||||
**NOTE**: if you need to just check the validity of a JSON document then see the
|
||||
FAQ on "[validating JSON documents](#validating_json)". Taking that FAQ in mind,
|
||||
if you wish to validate every JSON file in `author/` then you could do so like:
|
||||
|
||||
``` <!--sh-->
|
||||
jparse foo.json
|
||||
```
|
||||
|
||||
If the tool exits 0 (and shows no output) then the JSON is valid. If it is
|
||||
invalid you should get an error but for more details you can increase the
|
||||
verbosity with the `-v` flag like:
|
||||
|
||||
``` <!--sh-->
|
||||
jparse -v 3 foo.json
|
||||
```
|
||||
|
||||
If the tool is not installed then you will obviously have to specify the path of
|
||||
the tool.
|
||||
|
||||
If you wish to validate every JSON file in `author/` then you could do so like:
|
||||
|
||||
``` <!--sh-->
|
||||
for auth in *.json; do jparse 2>/dev/null "$auth" || echo "$auth is invalid JSON" ; done
|
||||
for auth in *.json; do jparse -q "$auth" || echo "$auth is invalid JSON" ; done
|
||||
```
|
||||
|
||||
If you see any output then it will say which file or files are invalid JSON
|
||||
(this should not actually happen).
|
||||
(this should not actually happen, however).
|
||||
|
||||
|
||||
|
||||
|
||||
+63
-252
@@ -396,7 +396,7 @@ They are are provided as a <strong>VERY TENTATIVE</strong> hint at <strong>what
|
||||
MIGHT</strong> be used in the next IOCCC. In some cases they might
|
||||
even be a copy of the guidelines from the previous IOCCC.</p>
|
||||
<p>See our
|
||||
FAQ on “<a href="#feedback">rules, guidelines, tools feedback</a>”.
|
||||
FAQ on “<a href="../faq.html#feedback">rules, guidelines, tools feedback</a>”.
|
||||
as well as our
|
||||
FAQ on “<a href="../faq.html#question">asking questions</a>”
|
||||
about these guidelines.</p>
|
||||
@@ -424,7 +424,7 @@ writing by <a href="../contact.html">contacting the judges</a>.</p>
|
||||
<h2 id="ioccc-guidelines-version">IOCCC Guidelines version</h2>
|
||||
</div>
|
||||
<p class="leftbar">
|
||||
These <a href="guidelines.html">IOCCC guidelines</a> are version <strong>28.10 2024-07-15</strong>.
|
||||
These <a href="guidelines.html">IOCCC guidelines</a> are version <strong>28.11 2024-07-27</strong>.
|
||||
</p>
|
||||
<p><strong>IMPORTANT</strong>: Be <strong>SURE</strong> to read the <a href="rules.html">IOCCC rules</a>.</p>
|
||||
<div id="change_marks">
|
||||
@@ -694,13 +694,6 @@ NOT recommend these options.
|
||||
In many places it will prompt you to verify what you input, allowing you to
|
||||
correct details as you go along.
|
||||
</p>
|
||||
<p class="leftbar">
|
||||
Although the <code>mkiocccentry(1)</code> tool will verify everything for you, you may wish
|
||||
to validate different parts individually with the different tools. As the
|
||||
<a href="rules.html">rules</a> state, each of these tools has a <code>-h</code> option. However, to
|
||||
help simplify matters, we give you a brief overview below, which should also
|
||||
help you understand some of the checks the tool makes.
|
||||
</p>
|
||||
<div id="mkiocccentry-synopsis">
|
||||
<h2 id="mkiocccentry1-synopsis"><code>mkiocccentry(1)</code> synopsis</h2>
|
||||
</div>
|
||||
@@ -710,177 +703,17 @@ The synopsis of the <code>mkiocccentry(1)</code> tool is:
|
||||
<pre><code> mkiocccentry [options] work_dir prog.c \
|
||||
Makefile remarks.md [file ...]</code></pre>
|
||||
<p class="leftbar">
|
||||
… where <code>work_dir</code> is a directory that will be used to build the submission
|
||||
tarball, <code>prog.c</code> is your submission source code, <code>Makefile</code> is your submission’s
|
||||
<code>Makefile</code>, <code>remarks.md</code> are your remarks (that will be the basis of the
|
||||
<code>README.md</code> file which will be used to form the <code>index.html</code> file, if your
|
||||
submission wins) and the remaining args are the paths to any other files you
|
||||
wish to submit.
|
||||
</p>
|
||||
<p class="leftbar">
|
||||
See the <a href="rules.html">Rules</a> and in particular <a href="rules.html#rule17">Rule 17</a> for
|
||||
the requirements of these files.
|
||||
</p>
|
||||
<p class="leftbar">
|
||||
The <code>work_dir</code> <strong>MUST</strong> already exist, as a directory, and it is an error if it
|
||||
is not a directory that can be written to. In <strong>this</strong> directory your <strong>submission
|
||||
directory</strong> will be created, with the name based on your IOCCC registration
|
||||
username, which is <strong>in the form of a UUID</strong> and submission number; see the
|
||||
<a href="rules.html">rules</a> for more details on this, and in particular <a href="rules.html#rule17">Rule
|
||||
17</a>.
|
||||
</p>
|
||||
<p class="leftbar">
|
||||
If the <strong><em>subdirectory</em> in the <em>work directory</em></strong> already exists, you will have to
|
||||
move it, remove it or otherwise specify a different work directory (<strong>NOT</strong>
|
||||
subdirectory), as it needs to be empty and the <code>mkiocccentry(1)</code> tool does not
|
||||
check this for you as it could not do anything about anyway. This <em>subdirectory is
|
||||
where your files will be <strong>copied</strong> to</em>. Your <em>submission tarball</em> (which you will
|
||||
upload to the submit server) that <code>txzchk(1)</code> will validate <em>will be placed in
|
||||
the <strong>work directory</strong></em>, and <strong>its <em>contents</em> will be the <em>subdirectory</em> with your
|
||||
submission’s files</strong>.
|
||||
</p>
|
||||
<p class="leftbar">
|
||||
The <code>mkiocccentry(1)</code> tool will ask you for information about your
|
||||
submission <em>as well as author details</em> (that will only be looked at if the
|
||||
submission wins), run some tests and run a number of other tools, as already
|
||||
mentioned and as described below.
|
||||
</p>
|
||||
<p class="leftbar">
|
||||
To help you with editing a submission, the <code>mkiocccentry(1)</code> tool has
|
||||
some options to write <em>OR</em> read from an answers file so you do not have to input
|
||||
the information about the author(s) and the submission itself, after saving the
|
||||
answers to a file. To write to <code>answers.txt</code> try:
|
||||
</p>
|
||||
<pre><code> mkiocccentry -a answers.txt ...</code></pre>
|
||||
<p class="leftbar">
|
||||
Alternatively, if you wish to overwrite a file, you can use the <code>-A</code>
|
||||
flag with the same option argument. Be <strong>very careful</strong> that you do not accidentally
|
||||
overwrite your <code>prog.c</code> or some other important file!
|
||||
the information about the author(s) and the submission more than once (unless of
|
||||
course you need to make some changes, in which case you can use the option that
|
||||
overwrites the file).
|
||||
</p>
|
||||
<p class="leftbar">
|
||||
To make use of the answers file, use the <code>-i answers</code> option like:
|
||||
See the
|
||||
FAQ on “<a href="../faq.html#mkiocccentry">mkiocccentry</a>”
|
||||
for how to use this tool in more detail.
|
||||
</p>
|
||||
<pre><code> mkiocccentry -i answers.txt ...</code></pre>
|
||||
<h3 id="mkiocccentry-checks"><code>mkiocccentry</code> checks</h3>
|
||||
<p class="leftbar">
|
||||
<code>mkiocccentry(1)</code> will check and warn about the following conditions:
|
||||
</p>
|
||||
<ul>
|
||||
<li><p class="leftbar">
|
||||
if the files do not exist, are not regular files or cannot be read.
|
||||
</p></li>
|
||||
<li><p class="leftbar">
|
||||
if <code>prog.c</code> violates <a href="rules.html#rule2">Rule 2</a> (see
|
||||
<a href="https://github.com/ioccc-src/mkiocccentry/blob/master/iocccsize.c">iocccsize.c</a>).
|
||||
</p></li>
|
||||
<li><p class="leftbar">
|
||||
if <code>prog.c</code> is empty.
|
||||
</p></li>
|
||||
<li><p class="leftbar">
|
||||
if <code>prog.c</code> has any high bit char (see
|
||||
<a href="https://github.com/ioccc-src/mkiocccentry/blob/master/iocccsize.c">iocccsize.c</a>).
|
||||
</p></li>
|
||||
<li><p class="leftbar">
|
||||
if <code>prog.c</code> has any NUL char (see
|
||||
<a href="https://github.com/ioccc-src/mkiocccentry/blob/master/iocccsize.c">iocccsize.c</a>).
|
||||
</p></li>
|
||||
<li><p class="leftbar">
|
||||
if <code>prog.c</code> has any unknown or invalid trigraph (see
|
||||
<a href="https://github.com/ioccc-src/mkiocccentry/blob/master/iocccsize.c">iocccsize.c</a>).
|
||||
</p></li>
|
||||
<li><p class="leftbar">
|
||||
if <code>prog.c</code> triggers a word buffer overflow (see
|
||||
<a href="https://github.com/ioccc-src/mkiocccentry/blob/master/iocccsize.c">iocccsize.c</a>).
|
||||
</p></li>
|
||||
<li><p class="leftbar">
|
||||
if <code>prog.c</code> triggers an <code>ungetc(3)</code> error (see
|
||||
<a href="https://github.com/ioccc-src/mkiocccentry/blob/master/iocccsize.c">iocccsize.c</a>).
|
||||
</p></li>
|
||||
<li><p class="leftbar">
|
||||
if the first rule in the <code>Makefile</code> is not <code>all</code>.
|
||||
</p></li>
|
||||
<li><p class="leftbar">
|
||||
if the <code>Makefile</code> does not have a <code>clean</code> rule.
|
||||
</p></li>
|
||||
<li><p class="leftbar">
|
||||
if the <code>Makefile</code> does not have a <code>clobber</code> rule.
|
||||
</p></li>
|
||||
<li><p class="leftbar">
|
||||
if the <code>Makefile</code> does not have a <code>try</code> rule.
|
||||
</p></li>
|
||||
<li><p class="leftbar">
|
||||
if the <code>remarks.md</code> is empty.
|
||||
</p></li>
|
||||
</ul>
|
||||
<p class="leftbar">
|
||||
Conditions that one must correct, and which <code>mkiocccentry(1)</code> will prompt until
|
||||
it is correct, are:
|
||||
</p>
|
||||
<ul>
|
||||
<li><p class="leftbar">
|
||||
your <em>title</em> is not in the range of 1 through <code>MAX_TITLE_LEN</code> chars (see
|
||||
<a href="https://github.com/ioccc-src/mkiocccentry/blob/master/soup/limit_ioccc.h">limit_ioccc.h</a>).
|
||||
</p></li>
|
||||
<li><p class="leftbar">
|
||||
your <em>title</em> does not match the regexp <code>^[0-9a-z][0-9a-z._+-]*$</code>.
|
||||
</p></li>
|
||||
<li><p class="leftbar">
|
||||
your <em>abstract</em> is not between 1 and <code>MAX_ABSTRACT_LEN</code> chars
|
||||
(see <a href="https://github.com/ioccc-src/mkiocccentry/blob/master/soup/limit_ioccc.h">limit_ioccc.h</a>).
|
||||
</p></li>
|
||||
<li><p class="leftbar">
|
||||
the author count is not 1 through <code>MAX_AUTHORS</code> (see
|
||||
<a href="https://github.com/ioccc-src/mkiocccentry/blob/master/soup/limit_ioccc.h">limit_ioccc.h</a>).
|
||||
</p></li>
|
||||
<li><p class="leftbar">
|
||||
an author <em>name</em> is not 1 through <code>MAX_NAME_LEN</code> chars (see
|
||||
<a href="https://github.com/ioccc-src/mkiocccentry/blob/master/soup/limit_ioccc.h">limit_ioccc.h</a>).
|
||||
</p></li>
|
||||
<li><p class="leftbar">
|
||||
duplicate author <em>name</em>.
|
||||
</p></li>
|
||||
<li><p class="leftbar">
|
||||
<em>country code</em> is invalid (not ISO 3166-1 2 character
|
||||
codes).
|
||||
</p></li>
|
||||
<li><p class="leftbar">
|
||||
an <em>email</em>, if provided, is not in the format of <code>x@y</code> or
|
||||
if <code>x</code> or <code>y</code> contain a <code>@</code>, are empty or if the total length is longer than
|
||||
<code>MAX_EMAIL_LEN</code> (see <a href="https://github.com/ioccc-src/mkiocccentry/blob/master/soup/limit_ioccc.h">limit_ioccc.h</a>).
|
||||
</p></li>
|
||||
<li><p class="leftbar">
|
||||
a <em>URL</em> or <em>alt URL</em>, if provided, does not start with <code>http://</code>
|
||||
or <code>https://</code> or is longer than <code>MAX_URL_LEN</code> chars (see
|
||||
<a href="https://github.com/ioccc-src/mkiocccentry/blob/master/soup/limit_ioccc.h">limit_ioccc.h</a>)
|
||||
or does not have anything after the <code>http://</code> or <code>https://</code>.
|
||||
</p></li>
|
||||
<li><p class="leftbar">
|
||||
a <em>mastodon handle</em>, if provided, is not in the form of
|
||||
<code>@user@site</code> (i.e. starts with an <code>@</code>, has text following it and then another
|
||||
<code>@</code> followed by more text and has no other <code>@</code>) or is longer than <code>MAX_MASTODON_LEN</code> (see
|
||||
<a href="https://github.com/ioccc-src/mkiocccentry/blob/master/soup/limit_ioccc.h">limit_ioccc.h</a>).
|
||||
</p></li>
|
||||
<li><p class="leftbar">
|
||||
a <em>GitHub account</em>, if provided, does not start with an <code>@</code>,
|
||||
has more than one <code>@</code> or is longer than <code>MAX_GITHUB_LEN</code> (see
|
||||
<a href="https://github.com/ioccc-src/mkiocccentry/blob/master/soup/limit_ioccc.h">limit_ioccc.h</a>).
|
||||
</p></li>
|
||||
<li><p class="leftbar">
|
||||
an <em>affiliation</em>, if provided, is longer than
|
||||
<code>MAX_AFFILIATION_LEN</code> (see <a href="https://github.com/ioccc-src/mkiocccentry/blob/master/soup/limit_ioccc.h">limit_ioccc.h</a>).
|
||||
</p></li>
|
||||
<li><p class="leftbar">
|
||||
an <em>author handle</em>, if the default is not accepted, does
|
||||
not match the regexp <code>^[0-9A-Za-z][0-9A-Za-z._+-]*$</code>.
|
||||
</p></li>
|
||||
<li><p class="leftbar">
|
||||
an <em>author handle</em> is repeated.
|
||||
</p></li>
|
||||
<li><p class="leftbar">
|
||||
the output of <code>ls</code> on the submission directory is
|
||||
incorrect.
|
||||
</p></li>
|
||||
</ul>
|
||||
<p class="leftbar">
|
||||
Below are the tools that <code>mkiocccentry(1)</code> will run.
|
||||
</p>
|
||||
@@ -894,13 +727,13 @@ As we already discussed how to invoke this we will not include it here again.
|
||||
<p class="leftbar">
|
||||
<code>mkiocccentry(1)</code> will write two JSON files: <code>.auth.json</code> and
|
||||
<code>.info.json</code>. These files contain information about the author(s) and about the
|
||||
submission. These files <strong>MUST</strong> pass the checks of <code>chkentry(1)</code>. If it does
|
||||
not pass and you used <code>mkiocccentry(1)</code> it is very possibly a bug and you should
|
||||
<a href="https://github.com/ioccc-src/mkiocccentry/issues/new?assignees=&labels=bug&projects=&template=bug_report.yml&title=%5BBug%5D+%3Ctitle%3E">report
|
||||
it as a bug at the mkiocccentry issues
|
||||
submission. These files <strong>MUST</strong> pass the checks of <code>chkentry(1)</code>.
|
||||
</p>
|
||||
<p class="leftbar">
|
||||
If <code>chkentry</code> does not pass and you used <code>mkiocccentry(1)</code> it is very possibly a
|
||||
bug and you should <a href="https://github.com/ioccc-src/mkiocccentry/issues/new?assignees=&labels=bug&projects=&template=bug_report.yml&title=%5BBug%5D+%3Ctitle%3E">report it as a bug at the mkiocccentry issues
|
||||
page</a>.
|
||||
See the
|
||||
FAQ on “<a href="../faq.html#mkiocccentry_bugs">report mkiocccentry bugs</a>”.
|
||||
See the FAQ on “<a href="../faq.html#mkiocccentry_bugs">report mkiocccentry bugs</a>”.
|
||||
</p>
|
||||
<p class="leftbar">
|
||||
Assuming that <code>chkentry(1)</code> validates both <code>.auth.json</code> and
|
||||
@@ -909,31 +742,17 @@ executed. In this case, there should be no problems as <code>mkiocccentry(1)</co
|
||||
<strong>NOT</strong> form a tarball if there are any issues.
|
||||
</p>
|
||||
<p class="leftbar">
|
||||
If you want to validate the <code>.auth.json</code> or <code>.info.json</code> files you
|
||||
should use <code>chkentry(1)</code>. <code>chkentry(1)</code> accepts more than one command line form.
|
||||
If you pass a single argument, it is expected to be a directory that has both
|
||||
<code>.auth.json</code> and <code>.info.json</code> in it. You can also specify a <code>.auth.json</code> and/or
|
||||
<code>.info.json</code> file. An argument of <code>.</code> will skip that file. For instance:
|
||||
Please see the
|
||||
FAQ on “<a href="../faq.html#chkentry">validating .auth.json and/or .info.json files</a>
|
||||
for more details on this tool and how you can use it to validate your
|
||||
<code>.auth.json</code> and <code>.info.json</code> files.
|
||||
</p>
|
||||
<pre><code> # test entry directory test_work:
|
||||
chkentry test_work
|
||||
|
||||
# run checks on .info.json:
|
||||
chkentry .info.json .
|
||||
|
||||
# run checks on .auth.json:
|
||||
chkentry . .auth.json
|
||||
|
||||
# run checks on .info.json and .auth.json:
|
||||
chkentry .info.json .auth.json</code></pre>
|
||||
<p class="leftbar">
|
||||
If there is a <a href="https://www.json.org/json-en.html">JSON</a> issue detected
|
||||
by <code>jparse(8)</code>, <strong>then there is a <a href="https://www.json.org/json-en.html">JSON</a>
|
||||
error and <code>chkentry(1)</code> will report it as an <em>error</em></strong>. If the parsing is OK <strong>but
|
||||
there <em>is an issue</em> in one or both of the
|
||||
<a href="https://www.json.org/json-en.html">JSON</a> files in <em>the context of the IOCCC</em>,
|
||||
it will report this as an error</strong>. Thus, if you were to package this manually
|
||||
then you would be violating <a href="rules.html#rule17">Rule 17</a>.
|
||||
You might also wish to see the
|
||||
FAQ on “<a href="../faq.html#auth_json">.auth.json</a>”
|
||||
and the
|
||||
FAQ on “<a href="../faq.html#info_json">.info.json</a>”
|
||||
for much more information on these files.
|
||||
</p>
|
||||
<h2 id="txzchk"><code>txzchk</code></h2>
|
||||
<p class="leftbar">
|
||||
@@ -947,7 +766,46 @@ FAQ on “<a href="../faq.html#mkiocccentry_bugs">report mkiocccentry bugs</a>
|
||||
</p>
|
||||
<p class="leftbar">
|
||||
As part of its sanity checks, <code>txzchk(1)</code> will run <code>fnamchk(1)</code> on the
|
||||
<em>filename</em> to verify that the name is valid.
|
||||
<em>filename</em> to verify that the name is valid. See the
|
||||
FAQ on “<a href="../faq.html#fnamchk">fnamchk</a>”
|
||||
and <a href="#fnamchk">fnamchk below</a> for more details on this tool.
|
||||
</p>
|
||||
<p class="leftbar">
|
||||
It is beyond the scope of this document to discuss the many tests that
|
||||
<code>txzchk(1)</code> do. In this case we refer you to the <a href="https://github.com/ioccc-src/mkiocccentry/blob/master/txzchk.c">source
|
||||
code</a> or the man
|
||||
page. You might find a fun option if you do either of these!
|
||||
</p>
|
||||
<p class="leftbar">
|
||||
Of course, as <code>txzchk</code> does not extract the tarball, it is possible that if you
|
||||
manually package your submission tarball, you could still be violating <a href="rules.html#rule17">Rule
|
||||
17</a>.
|
||||
</p>
|
||||
<p class="leftbar">
|
||||
See also the
|
||||
FAQ on “<a href="../faq.html#txzchk">txzchk</a>”.
|
||||
</p>
|
||||
<h2 id="fnamchk"><code>fnamchk</code></h2>
|
||||
<p class="leftbar">
|
||||
A tool that <a href="#txzchk">txzchk</a> runs is <code>fnamchk</code>. This is an important part of
|
||||
its algorithm. If the filename is incorrect (or the filename does not match the
|
||||
directory name of the tarball) then it is an <strong>error</strong> and you risk violating
|
||||
<a href="rules.html#rule17">Rule 17</a>. Nevertheless, you can run the tool manually should
|
||||
you wish to.
|
||||
</p>
|
||||
<p class="leftbar">
|
||||
To see more details on <code>fnamchk</code> and how to manually validate your submission
|
||||
tarball filename, see the
|
||||
FAQ on “<a href="../faq.html#fnamchk">fnamchk</a>”.
|
||||
</p>
|
||||
<hr>
|
||||
<p class="leftbar">
|
||||
At the risk of stating the obvious: you run <strong>a very big risk</strong> of having
|
||||
your submission rejected if you package your own tarball and there are <strong>any
|
||||
problems</strong>. For instance, if <code>chkentry(1)</code> found a problem in your <code>.info.json</code>
|
||||
file, the <code>mkiocccentry(1)</code> tool would not package it. But if you were to package
|
||||
it manually, you would be violating <a href="rules.html#rule17">Rule 17</a>. But even if
|
||||
everything checks out OK you should not expect that everything <strong>IS</strong> OK.
|
||||
</p>
|
||||
<p class="leftbar">
|
||||
It is extremely unlikely that <code>fnamchk(1)</code> reporting an invalid filename is a
|
||||
@@ -961,53 +819,6 @@ See the
|
||||
FAQ on “<a href="../faq.html#mkiocccentry_bugs">report mkiocccentry bugs</a>”.
|
||||
</p>
|
||||
<p class="leftbar">
|
||||
If verbosity level is > 0, <code>txzchk(1)</code> will show the contents of the tarball which is
|
||||
how the <code>mkiocccentry(1)</code> shows you the tarball contents for you to review.
|
||||
</p>
|
||||
<p class="leftbar">
|
||||
It is beyond the scope of this document to discuss the many tests that
|
||||
<code>txzchk(1)</code> do. In this case we refer you to the <a href="https://github.com/ioccc-src/mkiocccentry/blob/master/txzchk.c">source
|
||||
code</a> or the man
|
||||
page. You might find a fun option if you do either of these!
|
||||
</p>
|
||||
<p class="leftbar">
|
||||
If you wish to validate the tarball without running the <code>mkiocccentry(1)</code> tool,
|
||||
for instance the tarball <code>submit.12345678-1234-4321-abcd-1234567890ab-2.1720636351.txz</code> you can
|
||||
do:
|
||||
</p>
|
||||
<pre><code> txzchk submit.12345678-1234-4321-abcd-1234567890ab-2.1720636351.txz</code></pre>
|
||||
<p class="leftbar">
|
||||
Assuming that the tarball exists and is valid, you should see no output.
|
||||
</p>
|
||||
<p class="leftbar">
|
||||
If you wish to see the contents, for instance like <code>mkiocccentry(1)</code> does, you
|
||||
could do:
|
||||
</p>
|
||||
<pre><code> txzchk -v 1 submit.12345678-1234-4321-abcd-1234567890ab-2.1720636351.txz</code></pre>
|
||||
<h2 id="fnamchk"><code>fnamchk</code></h2>
|
||||
<p class="leftbar">
|
||||
A tool that <a href="#txzchk">txzchk</a> runs is <code>fnamchk</code>. This is an important part of
|
||||
its algorithm but if you wish to validate a submission filename you can do so:
|
||||
</p>
|
||||
<pre><code> fnamchk submit.12345678-1234-4321-abcd-1234567890ab-2.1720636351.txz</code></pre>
|
||||
<p class="leftbar">
|
||||
Assuming everything is OK, it would show:
|
||||
</p>
|
||||
<blockquote>
|
||||
<p><code>12345678-1234-4321-abcd-1234567890ab-2</code></p>
|
||||
</blockquote>
|
||||
<p class="leftbar">
|
||||
… which, as stated earlier, <code>txzchk(1)</code> uses.
|
||||
</p>
|
||||
<p class="leftbar">
|
||||
At the risk of stating the obvious: you run <strong>a very big risk</strong> of having
|
||||
your submission rejected if you package your own tarball and there are <strong>any
|
||||
problems</strong>. For instance, if <code>chkentry(1)</code> found a problem in your <code>.info.json</code>
|
||||
file, the <code>mkiocccentry(1)</code> tool would not package it. But if you were to package
|
||||
it manually, you would be violating <a href="rules.html#rule17">Rule 17</a>. But even if
|
||||
everything checks out OK you should not expect that everything <strong>IS</strong> OK.
|
||||
</p>
|
||||
<p class="leftbar">
|
||||
As you can see, the use of <code>mkiocccentry(1)</code> is <strong>HIGHLY RECOMMENDED</strong>.
|
||||
</p>
|
||||
<p class="leftbar">
|
||||
|
||||
+74
-237
@@ -9,7 +9,7 @@ MIGHT** be used in the next IOCCC. In some cases they might
|
||||
even be a copy of the guidelines from the previous IOCCC.
|
||||
|
||||
See our
|
||||
FAQ on "[rules, guidelines, tools feedback](#feedback)".
|
||||
FAQ on "[rules, guidelines, tools feedback](../faq.html#feedback)".
|
||||
as well as our
|
||||
FAQ on "[asking questions](../faq.html#question)"
|
||||
about these guidelines.
|
||||
@@ -48,7 +48,7 @@ writing by [contacting the judges](../contact.html).
|
||||
</div>
|
||||
|
||||
<p class="leftbar">
|
||||
These [IOCCC guidelines](guidelines.html) are version **28.10 2024-07-15**.
|
||||
These [IOCCC guidelines](guidelines.html) are version **28.11 2024-07-27**.
|
||||
</p>
|
||||
|
||||
**IMPORTANT**: Be **SURE** to read the [IOCCC rules](rules.html).
|
||||
@@ -380,15 +380,6 @@ In many places it will prompt you to verify what you input, allowing you to
|
||||
correct details as you go along.
|
||||
</p>
|
||||
|
||||
|
||||
<p class="leftbar">
|
||||
Although the `mkiocccentry(1)` tool will verify everything for you, you may wish
|
||||
to validate different parts individually with the different tools. As the
|
||||
[rules](rules.html) state, each of these tools has a `-h` option. However, to
|
||||
help simplify matters, we give you a brief overview below, which should also
|
||||
help you understand some of the checks the tool makes.
|
||||
</p>
|
||||
|
||||
<div id="mkiocccentry-synopsis">
|
||||
## `mkiocccentry(1)` synopsis
|
||||
</div>
|
||||
@@ -402,139 +393,20 @@ The synopsis of the `mkiocccentry(1)` tool is:
|
||||
Makefile remarks.md [file ...]
|
||||
```
|
||||
|
||||
<p class="leftbar">
|
||||
... where `work_dir` is a directory that will be used to build the submission
|
||||
tarball, `prog.c` is your submission source code, `Makefile` is your submission's
|
||||
`Makefile`, `remarks.md` are your remarks (that will be the basis of the
|
||||
`README.md` file which will be used to form the `index.html` file, if your
|
||||
submission wins) and the remaining args are the paths to any other files you
|
||||
wish to submit.
|
||||
</p>
|
||||
|
||||
<p class="leftbar">
|
||||
See the [Rules](rules.html) and in particular [Rule 17](rules.html#rule17) for
|
||||
the requirements of these files.
|
||||
</p>
|
||||
|
||||
<p class="leftbar">
|
||||
The `work_dir` **MUST** already exist, as a directory, and it is an error if it
|
||||
is not a directory that can be written to. In **this** directory your **submission
|
||||
directory** will be created, with the name based on your IOCCC registration
|
||||
username, which is **in the form of a UUID** and submission number; see the
|
||||
[rules](rules.html) for more details on this, and in particular [Rule
|
||||
17](rules.html#rule17).
|
||||
</p>
|
||||
|
||||
<p class="leftbar">
|
||||
If the **_subdirectory_ in the _work directory_** already exists, you will have to
|
||||
move it, remove it or otherwise specify a different work directory (**NOT**
|
||||
subdirectory), as it needs to be empty and the `mkiocccentry(1)` tool does not
|
||||
check this for you as it could not do anything about anyway. This _subdirectory is
|
||||
where your files will be **copied** to_. Your _submission tarball_ (which you will
|
||||
upload to the submit server) that `txzchk(1)` will validate _will be placed in
|
||||
the **work directory**_, and **its _contents_ will be the _subdirectory_ with your
|
||||
submission's files**.
|
||||
</p>
|
||||
|
||||
<p class="leftbar">
|
||||
The `mkiocccentry(1)` tool will ask you for information about your
|
||||
submission _as well as author details_ (that will only be looked at if the
|
||||
submission wins), run some tests and run a number of other tools, as already
|
||||
mentioned and as described below.
|
||||
</p>
|
||||
|
||||
<p class="leftbar">
|
||||
To help you with editing a submission, the `mkiocccentry(1)` tool has
|
||||
some options to write _OR_ read from an answers file so you do not have to input
|
||||
the information about the author(s) and the submission itself, after saving the
|
||||
answers to a file. To write to `answers.txt` try:
|
||||
</p>
|
||||
|
||||
``` <!---sh-->
|
||||
mkiocccentry -a answers.txt ...
|
||||
```
|
||||
|
||||
<p class="leftbar">
|
||||
Alternatively, if you wish to overwrite a file, you can use the `-A`
|
||||
flag with the same option argument. Be **very careful** that you do not accidentally
|
||||
overwrite your `prog.c` or some other important file!
|
||||
the information about the author(s) and the submission more than once (unless of
|
||||
course you need to make some changes, in which case you can use the option that
|
||||
overwrites the file).
|
||||
</p>
|
||||
|
||||
<p class="leftbar">
|
||||
To make use of the answers file, use the `-i answers` option like:
|
||||
See the
|
||||
FAQ on "[mkiocccentry](../faq.html#mkiocccentry)"
|
||||
for how to use this tool in more detail.
|
||||
</p>
|
||||
|
||||
``` <!---sh-->
|
||||
mkiocccentry -i answers.txt ...
|
||||
```
|
||||
|
||||
<div id="mkiocccentry-checks">
|
||||
### `mkiocccentry` checks
|
||||
</div>
|
||||
|
||||
<p class="leftbar">
|
||||
`mkiocccentry(1)` will check and warn about the following conditions:
|
||||
</p>
|
||||
|
||||
- <p class="leftbar">if the files do not exist, are not regular files or cannot be read.</p>
|
||||
- <p class="leftbar">if `prog.c` violates [Rule 2](rules.html#rule2) (see
|
||||
[iocccsize.c](https://github.com/ioccc-src/mkiocccentry/blob/master/iocccsize.c)).</p>
|
||||
- <p class="leftbar">if `prog.c` is empty.</p>
|
||||
- <p class="leftbar">if `prog.c` has any high bit char (see
|
||||
[iocccsize.c](https://github.com/ioccc-src/mkiocccentry/blob/master/iocccsize.c)).</p>
|
||||
- <p class="leftbar">if `prog.c` has any NUL char (see
|
||||
[iocccsize.c](https://github.com/ioccc-src/mkiocccentry/blob/master/iocccsize.c)).</p>
|
||||
- <p class="leftbar">if `prog.c` has any unknown or invalid trigraph (see
|
||||
[iocccsize.c](https://github.com/ioccc-src/mkiocccentry/blob/master/iocccsize.c)).</p>
|
||||
- <p class="leftbar">if `prog.c` triggers a word buffer overflow (see
|
||||
[iocccsize.c](https://github.com/ioccc-src/mkiocccentry/blob/master/iocccsize.c)).</p>
|
||||
- <p class="leftbar">if `prog.c` triggers an `ungetc(3)` error (see
|
||||
[iocccsize.c](https://github.com/ioccc-src/mkiocccentry/blob/master/iocccsize.c)).</p>
|
||||
- <p class="leftbar">if the first rule in the `Makefile` is not `all`.</p>
|
||||
- <p class="leftbar">if the `Makefile` does not have a `clean` rule.</p>
|
||||
- <p class="leftbar">if the `Makefile` does not have a `clobber` rule.</p>
|
||||
- <p class="leftbar">if the `Makefile` does not have a `try` rule.</p>
|
||||
- <p class="leftbar">if the `remarks.md` is empty.</p>
|
||||
|
||||
<p class="leftbar">
|
||||
Conditions that one must correct, and which `mkiocccentry(1)` will prompt until
|
||||
it is correct, are:
|
||||
</p>
|
||||
|
||||
- <p class="leftbar">your _title_ is not in the range of 1 through `MAX_TITLE_LEN` chars (see
|
||||
[limit_ioccc.h](https://github.com/ioccc-src/mkiocccentry/blob/master/soup/limit_ioccc.h)).</p>
|
||||
- <p class="leftbar">your _title_ does not match the regexp `^[0-9a-z][0-9a-z._+-]*$`.</p>
|
||||
- <p class="leftbar">your _abstract_ is not between 1 and `MAX_ABSTRACT_LEN` chars
|
||||
(see [limit_ioccc.h](https://github.com/ioccc-src/mkiocccentry/blob/master/soup/limit_ioccc.h)).</p>
|
||||
- <p class="leftbar">the author count is not 1 through `MAX_AUTHORS` (see
|
||||
[limit_ioccc.h](https://github.com/ioccc-src/mkiocccentry/blob/master/soup/limit_ioccc.h)).</p>
|
||||
- <p class="leftbar">an author _name_ is not 1 through `MAX_NAME_LEN` chars (see
|
||||
[limit_ioccc.h](https://github.com/ioccc-src/mkiocccentry/blob/master/soup/limit_ioccc.h)).</p>
|
||||
- <p class="leftbar">duplicate author _name_.</p>
|
||||
- <p class="leftbar">_country code_ is invalid (not ISO 3166-1 2 character
|
||||
codes).</p>
|
||||
- <p class="leftbar">an _email_, if provided, is not in the format of `x@y` or
|
||||
if `x` or `y` contain a `@`, are empty or if the total length is longer than
|
||||
`MAX_EMAIL_LEN` (see [limit_ioccc.h](https://github.com/ioccc-src/mkiocccentry/blob/master/soup/limit_ioccc.h)).</p>
|
||||
- <p class="leftbar">a _URL_ or _alt URL_, if provided, does not start with `http://`
|
||||
or `https://` or is longer than `MAX_URL_LEN` chars (see
|
||||
[limit_ioccc.h](https://github.com/ioccc-src/mkiocccentry/blob/master/soup/limit_ioccc.h))
|
||||
or does not have anything after the `http://` or `https://`.</p>
|
||||
- <p class="leftbar">a _mastodon handle_, if provided, is not in the form of
|
||||
`@user@site` (i.e. starts with an `@`, has text following it and then another
|
||||
`@` followed by more text and has no other `@`) or is longer than `MAX_MASTODON_LEN` (see
|
||||
[limit_ioccc.h](https://github.com/ioccc-src/mkiocccentry/blob/master/soup/limit_ioccc.h)).</p>
|
||||
- <p class="leftbar">a _GitHub account_, if provided, does not start with an `@`,
|
||||
has more than one `@` or is longer than `MAX_GITHUB_LEN` (see
|
||||
[limit_ioccc.h](https://github.com/ioccc-src/mkiocccentry/blob/master/soup/limit_ioccc.h)).</p>
|
||||
- <p class="leftbar">an _affiliation_, if provided, is longer than
|
||||
`MAX_AFFILIATION_LEN` (see [limit_ioccc.h](https://github.com/ioccc-src/mkiocccentry/blob/master/soup/limit_ioccc.h)).</p>
|
||||
- <p class="leftbar">an _author handle_, if the default is not accepted, does
|
||||
not match the regexp `^[0-9A-Za-z][0-9A-Za-z._+-]*$`.</p>
|
||||
- <p class="leftbar">an _author handle_ is repeated.</p>
|
||||
- <p class="leftbar">the output of `ls` on the submission directory is
|
||||
incorrect.</p>
|
||||
|
||||
<p class="leftbar">
|
||||
Below are the tools that `mkiocccentry(1)` will run.
|
||||
</p>
|
||||
@@ -555,13 +427,14 @@ As we already discussed how to invoke this we will not include it here again.
|
||||
|
||||
<p class="leftbar">`mkiocccentry(1)` will write two JSON files: `.auth.json` and
|
||||
`.info.json`. These files contain information about the author(s) and about the
|
||||
submission. These files **MUST** pass the checks of `chkentry(1)`. If it does
|
||||
not pass and you used `mkiocccentry(1)` it is very possibly a bug and you should
|
||||
[report
|
||||
it as a bug at the mkiocccentry issues
|
||||
submission. These files **MUST** pass the checks of `chkentry(1)`.
|
||||
</p>
|
||||
|
||||
<p class="leftbar">
|
||||
If `chkentry` does not pass and you used `mkiocccentry(1)` it is very possibly a
|
||||
bug and you should [report it as a bug at the mkiocccentry issues
|
||||
page](https://github.com/ioccc-src/mkiocccentry/issues/new?assignees=&labels=bug&projects=&template=bug_report.yml&title=%5BBug%5D+%3Ctitle%3E).
|
||||
See the
|
||||
FAQ on "[report mkiocccentry bugs](../faq.html#mkiocccentry_bugs)".
|
||||
See the FAQ on "[report mkiocccentry bugs](../faq.html#mkiocccentry_bugs)".
|
||||
</p>
|
||||
|
||||
<p class="leftbar">
|
||||
@@ -572,38 +445,20 @@ executed. In this case, there should be no problems as `mkiocccentry(1)` should
|
||||
</p>
|
||||
|
||||
<p class="leftbar">
|
||||
If you want to validate the `.auth.json` or `.info.json` files you
|
||||
should use `chkentry(1)`. `chkentry(1)` accepts more than one command line form.
|
||||
If you pass a single argument, it is expected to be a directory that has both
|
||||
`.auth.json` and `.info.json` in it. You can also specify a `.auth.json` and/or
|
||||
`.info.json` file. An argument of `.` will skip that file. For instance:
|
||||
Please see the
|
||||
FAQ on "[validating .auth.json and/or .info.json files](../faq.html#chkentry)
|
||||
for more details on this tool and how you can use it to validate your
|
||||
`.auth.json` and `.info.json` files.
|
||||
</p>
|
||||
|
||||
``` <!---sh-->
|
||||
# test entry directory test_work:
|
||||
chkentry test_work
|
||||
|
||||
# run checks on .info.json:
|
||||
chkentry .info.json .
|
||||
|
||||
# run checks on .auth.json:
|
||||
chkentry . .auth.json
|
||||
|
||||
# run checks on .info.json and .auth.json:
|
||||
chkentry .info.json .auth.json
|
||||
```
|
||||
|
||||
<p class="leftbar">
|
||||
If there is a [JSON](https://www.json.org/json-en.html) issue detected
|
||||
by `jparse(8)`, **then there is a [JSON](https://www.json.org/json-en.html)
|
||||
error and `chkentry(1)` will report it as an _error_**. If the parsing is OK **but
|
||||
there _is an issue_ in one or both of the
|
||||
[JSON](https://www.json.org/json-en.html) files in _the context of the IOCCC_,
|
||||
it will report this as an error**. Thus, if you were to package this manually
|
||||
then you would be violating [Rule 17](rules.html#rule17).
|
||||
You might also wish to see the
|
||||
FAQ on "[.auth.json](../faq.html#auth_json)"
|
||||
and the
|
||||
FAQ on "[.info.json](../faq.html#info_json)"
|
||||
for much more information on these files.
|
||||
</p>
|
||||
|
||||
|
||||
<div id="txzchk">
|
||||
## `txzchk`
|
||||
</div>
|
||||
@@ -621,7 +476,56 @@ FAQ on "[report mkiocccentry bugs](../faq.html#mkiocccentry_bugs)".
|
||||
|
||||
<p class="leftbar">
|
||||
As part of its sanity checks, `txzchk(1)` will run `fnamchk(1)` on the
|
||||
_filename_ to verify that the name is valid.
|
||||
_filename_ to verify that the name is valid. See the
|
||||
FAQ on "[fnamchk](../faq.html#fnamchk)"
|
||||
and [fnamchk below](#fnamchk) for more details on this tool.
|
||||
</p>
|
||||
|
||||
<p class="leftbar">
|
||||
It is beyond the scope of this document to discuss the many tests that
|
||||
`txzchk(1)` do. In this case we refer you to the [source
|
||||
code](https://github.com/ioccc-src/mkiocccentry/blob/master/txzchk.c) or the man
|
||||
page. You might find a fun option if you do either of these!
|
||||
</p>
|
||||
|
||||
<p class="leftbar">
|
||||
Of course, as `txzchk` does not extract the tarball, it is possible that if you
|
||||
manually package your submission tarball, you could still be violating [Rule
|
||||
17](rules.html#rule17).
|
||||
</p>
|
||||
|
||||
<p class="leftbar">
|
||||
See also the
|
||||
FAQ on "[txzchk](../faq.html#txzchk)".
|
||||
</p>
|
||||
|
||||
<div id="fnamchk">
|
||||
## `fnamchk`
|
||||
</div>
|
||||
|
||||
<p class="leftbar">
|
||||
A tool that [txzchk](#txzchk) runs is `fnamchk`. This is an important part of
|
||||
its algorithm. If the filename is incorrect (or the filename does not match the
|
||||
directory name of the tarball) then it is an **error** and you risk violating
|
||||
[Rule 17](rules.html#rule17). Nevertheless, you can run the tool manually should
|
||||
you wish to.
|
||||
</p>
|
||||
|
||||
<p class="leftbar">
|
||||
To see more details on `fnamchk` and how to manually validate your submission
|
||||
tarball filename, see the
|
||||
FAQ on "[fnamchk](../faq.html#fnamchk)".
|
||||
</p>
|
||||
|
||||
<hr>
|
||||
|
||||
<p class="leftbar">
|
||||
At the risk of stating the obvious: you run **a very big risk** of having
|
||||
your submission rejected if you package your own tarball and there are **any
|
||||
problems**. For instance, if `chkentry(1)` found a problem in your `.info.json`
|
||||
file, the `mkiocccentry(1)` tool would not package it. But if you were to package
|
||||
it manually, you would be violating [Rule 17](rules.html#rule17). But even if
|
||||
everything checks out OK you should not expect that everything **IS** OK.
|
||||
</p>
|
||||
|
||||
<p class="leftbar">
|
||||
@@ -636,73 +540,6 @@ See the
|
||||
FAQ on "[report mkiocccentry bugs](../faq.html#mkiocccentry_bugs)".
|
||||
</p>
|
||||
|
||||
<p class="leftbar">
|
||||
If verbosity level is > 0, `txzchk(1)` will show the contents of the tarball which is
|
||||
how the `mkiocccentry(1)` shows you the tarball contents for you to review.
|
||||
</p>
|
||||
|
||||
<p class="leftbar">
|
||||
It is beyond the scope of this document to discuss the many tests that
|
||||
`txzchk(1)` do. In this case we refer you to the [source
|
||||
code](https://github.com/ioccc-src/mkiocccentry/blob/master/txzchk.c) or the man
|
||||
page. You might find a fun option if you do either of these!
|
||||
</p>
|
||||
|
||||
<p class="leftbar">
|
||||
If you wish to validate the tarball without running the `mkiocccentry(1)` tool,
|
||||
for instance the tarball `submit.12345678-1234-4321-abcd-1234567890ab-2.1720636351.txz` you can
|
||||
do:
|
||||
</p>
|
||||
|
||||
``` <!---sh-->
|
||||
txzchk submit.12345678-1234-4321-abcd-1234567890ab-2.1720636351.txz
|
||||
```
|
||||
|
||||
<p class="leftbar">
|
||||
Assuming that the tarball exists and is valid, you should see no output.
|
||||
</p>
|
||||
|
||||
<p class="leftbar">
|
||||
If you wish to see the contents, for instance like `mkiocccentry(1)` does, you
|
||||
could do:
|
||||
</p>
|
||||
|
||||
``` <!---sh-->
|
||||
txzchk -v 1 submit.12345678-1234-4321-abcd-1234567890ab-2.1720636351.txz
|
||||
```
|
||||
|
||||
<div id="fnamchk">
|
||||
## `fnamchk`
|
||||
</div>
|
||||
|
||||
<p class="leftbar">
|
||||
A tool that [txzchk](#txzchk) runs is `fnamchk`. This is an important part of
|
||||
its algorithm but if you wish to validate a submission filename you can do so:
|
||||
</p>
|
||||
|
||||
``` <!---sh-->
|
||||
fnamchk submit.12345678-1234-4321-abcd-1234567890ab-2.1720636351.txz
|
||||
```
|
||||
|
||||
<p class="leftbar">
|
||||
Assuming everything is OK, it would show:
|
||||
</p>
|
||||
|
||||
> `12345678-1234-4321-abcd-1234567890ab-2`
|
||||
|
||||
<p class="leftbar">
|
||||
... which, as stated earlier, `txzchk(1)` uses.
|
||||
</p>
|
||||
|
||||
<p class="leftbar">
|
||||
At the risk of stating the obvious: you run **a very big risk** of having
|
||||
your submission rejected if you package your own tarball and there are **any
|
||||
problems**. For instance, if `chkentry(1)` found a problem in your `.info.json`
|
||||
file, the `mkiocccentry(1)` tool would not package it. But if you were to package
|
||||
it manually, you would be violating [Rule 17](rules.html#rule17). But even if
|
||||
everything checks out OK you should not expect that everything **IS** OK.
|
||||
</p>
|
||||
|
||||
<p class="leftbar">
|
||||
As you can see, the use of `mkiocccentry(1)` is **HIGHLY RECOMMENDED**.
|
||||
</p>
|
||||
|
||||
Reference in new issue
Block a user