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

Add FAQs about the mkiocccentry tools

Browse Source 
Several new FAQ entries have been added to discuss some of the details
of chkentry, txzchk, fnamchk, jparse and maybe others that are related
to the rules and guidelines (and in particular rule 17 and how to
package submission tarballs). As there are new FAQ entries on these
(which is much of what was in the guidelines) the guidelines have been
shortened for these additions.

Looking over the rendered html files it seems okay but I believe that
these entries are works in progress and not complete.

For reference the new FAQ version is 28.0.3 2024-07-27 and the new
guidelines version is 28.11 2024-07-27.
This commit is contained in:
Cody Boone Ferguson committed 2024-07-27 12:27:39 -07:00
1 parent 5b4d848cb3
commit b70c510124
4 files changed
+783 -590
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

next/guidelines.html
+63 -252
View File
@@ -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=&amp;labels=bug&amp;projects=&amp;template=bug_report.yml&amp;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=&amp;labels=bug&amp;projects=&amp;template=bug_report.yml&amp;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 &gt; 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">
next/guidelines.md
+74 -237
View File
@@ -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>