Merge pull request #2604 from xexyl/guidelines-faq-mkiocccentry
This commit is contained in:
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="next/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](next/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