Skip to content
This repository has been archived by the owner on Dec 30, 2024. It is now read-only.

Commit

Permalink
Merge pull request #2764 from xexyl/guidelines-rules-faq
Browse files Browse the repository at this point in the history 
Updates/fixes to guidelines, rules and FAQ
  • Loading branch information
@lcn2
lcn2 authored Dec 7, 2024
2 parents 8c4db22 + a7711e6 commit 06850be
Show file tree
Hide file tree
Showing 6 changed files with 120 additions and 71 deletions.
4 changes: 2 additions & 2 deletions faq.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -425,7 +425,7 @@ <h2>Frequently Asked Questions</h2>

<!-- BEFORE: 1st line of markdown file: faq.md -->
<h1 id="ioccc-faq-table-of-contents">IOCCC FAQ Table of Contents</h1>
<p>This is FAQ version <strong>28.1.7 2024-12-06</strong>.</p>
<p>This is FAQ version <strong>28.1.8 2024-12-07</strong>.</p>
<h2 id="entering-the-ioccc-the-bare-minimum-you-need-to-know">0. <a href="#enter_questions">Entering the IOCCC: the bare minimum you need to know</a></h2>
<ul>
<li><strong>Q 0.0</strong>: <a class="normal" href="#submit">How can I enter the IOCCC?</a></li>
Expand Down Expand Up @@ -707,7 +707,7 @@ <h4 id="q-0.1.1-what-is-mkiocccentry-in-simple-terms">Q 0.1.1: What is <code>mki
<div id="obtaining_mkiocccentry">
<h4 id="q-0.1.2-how-do-i-obtain-the-latest-mkiocccentry-toolkit">Q 0.1.2: How do I obtain the latest mkiocccentry toolkit?</h4>
</div>
<p>Before you use it, make sure you have the most recent version. If you do not
<p>Before you use it, make <strong>SURE</strong> you have the most recent version. If you do not
have an mkiocccentry tool directory:</p>
<pre><code> cd some_directory
git clone [email protected]:ioccc-src/mkiocccentry.git
Expand Down
4 changes: 2 additions & 2 deletions faq.md
View file
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# IOCCC FAQ Table of Contents

This is FAQ version **28.1.7 2024-12-06**.
This is FAQ version **28.1.8 2024-12-07**.


## 0. [Entering the IOCCC: the bare minimum you need to know](#enter_questions)
Expand Down Expand Up @@ -341,7 +341,7 @@ Jump to: [top](#)
#### Q 0.1.2: How do I obtain the latest mkiocccentry toolkit?
</div>

Before you use it, make sure you have the most recent version. If you do not
Before you use it, make **SURE** you have the most recent version. If you do not
have an mkiocccentry tool directory:

``` <!---sh-->
Expand Down
47 changes: 27 additions & 20 deletions next/guidelines.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -457,7 +457,7 @@ <h1 id="ioccc-guidelines-version">IOCCC Guidelines version</h1>
</div>
</div>
<p class="leftbar">
These <a href="guidelines.html">IOCCC guidelines</a> are version <strong>28.27 2024-12-06</strong>.
These <a href="guidelines.html">IOCCC guidelines</a> are version <strong>28.28 2024-12-07</strong>.
</p>
<p><strong>IMPORTANT</strong>: Be <strong>SURE</strong> to read the <a href="rules.html">IOCCC rules</a>.</p>
<p>Jump to: <a href="#">top</a></p>
Expand Down Expand Up @@ -715,16 +715,8 @@ <h1 id="mkiocccentry"><code>mkiocccentry</code></h1>
FAQ on “<a href="../faq.html#mkiocccentry_bugs">reporting mkiocccentry bugs</a>”.
</p>
<p class="leftbar">
If you want to know what <code>.auth.json</code> is, see the
FAQ on “<a href="../faq.html#auth_json">.auth.json</a>”.
If you want to know what the <code>.info.json</code> file is, see the
FAQ on “<a href="../faq.html#info_json">.info.json</a>”.
On the other hand, if you want to know a bit more details about <code>chkentry</code>, see the
FAQ about “<a href="../faq.html#chkentry">chkentry</a>”.
</p>
<p class="leftbar">
However, even if <code>mkiocccentry</code> or one of the tools it invokes reports an error,
<strong>does not</strong> necessarily mean it is a bug in the code. It might be an issue with
it <strong>does not</strong> necessarily mean it is a bug in the code. It might be an issue with
your submission. Thus if you report an error as a bug it might not be something
that will be fixed as there might not be anything wrong with the tools.
</p>
Expand Down Expand Up @@ -798,10 +790,18 @@ <h2 id="chkentry"><code>chkentry</code></h2>
<p class="leftbar">
If <code>mkiocccentry(1)</code> is used and <code>chkentry(1)</code> fails to validate either of the
files, then unless it is a system specific problem, it is likely a bug in
<code>mkiocccentry(1)</code>, <code>chkentry(1)</code> or possibly <code>jparse</code>, though these are quite
<code>mkiocccentry(1)</code>, <code>chkentry(1)</code> or possibly <code>jparse</code>, though this is quite
unlikely.
</p>
<p class="leftbar">
If you want to know what <code>.auth.json</code> is, see the
FAQ on “<a href="../faq.html#auth_json">.auth.json</a>”.
If you want to know what the <code>.info.json</code> file is, see the
FAQ on “<a href="../faq.html#info_json">.info.json</a>”.
On the other hand, if you want to know a bit more details about <code>chkentry</code>, see the
FAQ about “<a href="../faq.html#chkentry">chkentry</a>”.
</p>
<p class="leftbar">
<code>chkentry</code> uses the <code>jparse</code> library. See the
<a href="https://github.com/ioccc-src/mkiocccentry/blob/master/jparse/README.md">jparse
README.md</a>
Expand All @@ -816,7 +816,7 @@ <h2 id="chkentry"><code>chkentry</code></h2>
<p class="leftbar">
The <code>jparse</code> parser, library and tools were co-developed by
<a href="../authors.html#Cody_Boone_Ferguson">Cody Boone Ferguson</a> and
<a href="http://www.isthe.com/chongo/index.html">Landon Curt Noll</a> in 2022 and comes
<a href="http://www.isthe.com/chongo/index.html">Landon Curt Noll</a> in 2022 and come
from the <a href="https://github.com/xexyl/jparse">jparse repo</a>. However, the
<strong>mkiocccentry tools use a <em>clone</em></strong> of the <a href="https://github.com/xexyl/jparse">jparse
repo</a> <strong>at a <em>specific</em> release</strong>.
Expand All @@ -826,22 +826,29 @@ <h2 id="chkentry"><code>chkentry</code></h2>
<p class="leftbar">
You do <strong>NOT need to install</strong> <code>jparse</code> from the <a href="https://github.com/xexyl/jparse">jparse
repo</a>! The <code>mkiocccentry</code> tools link in the
static library from <code>mkiocccentry</code>’s clone itself. This also goes for the
<a href="https://github.com/lcn2/dbg">dbg</a> and
<a href="https://github.com/lcn2/dyn_array">dyn_array</a> libraries that the <code>mkiocccentry</code>
tools, the <code>dyn_array</code> library uses and the <code>jparse</code> library uses.
static library from the <code>mkiocccentry</code>’s <em>clone</em>.
</p>
<p class="leftbar">
The <code>mkiocccentry</code> toolkit <em>also</em> has a clone of <em>both</em> the <a href="https://github.com/lcn2/dbg">dbg
library</a> and the
<a href="https://github.com/lcn2/dyn_array">dyn_array library</a>; the <a href="https://github.com/lcn2/dyn_array">dyn_array
library</a> uses the <a href="https://github.com/lcn2/dbg">dbg
library</a> and the <a href="https://github.com/xexyl/jparse">jparse
library</a> uses both libraries but unlike in the
<a href="https://github.com/xexyl/jparse">jparse repo</a>, the libraries do not need to be
installed separately, in order to use the tools in <code>mkiocccentry</code>.
</p>
<p class="leftbar">
In other words, <code>mkiocccentry</code> <strong>contains everything</strong> you need, and <em>even if you
do install</em> the libraries from their respective repos, it/they will <strong>not be
used</strong> when compiling the <code>mkiocccentry</code> tools. This is important to
make sure that you’re using the correct versions, which is verified by
<code>chkentry</code>.
<code>chkentry</code>. See <a href="rules.html#rule17">Rule 17</a>!
</p>
<p class="leftbar">
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
for more details on <code>chkentry</code> and how you can use it to validate your
<code>.auth.json</code> and <code>.info.json</code> files manually, without having to repackage your
submission.
</p>
Expand Down Expand Up @@ -1193,7 +1200,7 @@ <h2 id="magic-in-the-makefile">Magic in the Makefile</h2>
<h2 id="the-clobber-rule">The clobber rule</h2>
</div>
<p class="leftbar">
When <code>make clobber</code> is invoked, we request that submission be restored
When <code>make clobber</code> is invoked, we request that submissions be restored
to its original submission state. For example, any temporary files
created during the build process, or during execution should be
removed by the <code>clobber</code> rule.
Expand All @@ -1206,7 +1213,7 @@ <h1 id="our-likes-and-dislikes">OUR LIKES AND DISLIKES:</h1>
</div>
<p class="leftbar">
We <strong>LIKE</strong> submissions that use an edited variant of the
example Makefile, as described in the <a href="#makefile">Makefile section</a>,
example Makefile, as described and linked to in the <a href="#makefile">Makefile section</a>,
renamed as <code>Makefile</code> of course. This makes it easier for the <a href="../judges.html">IOCCC Judges</a>
to test your submission. And if your submissions wins, it makes it easier to integrate it into
the <a href="https://www.ioccc.org/index.html">Official IOCCC winner website</a>.
Expand Down
52 changes: 31 additions & 21 deletions next/guidelines.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -43,7 +43,7 @@ Jump to: [top](#)
</div>

<p class="leftbar">
These [IOCCC guidelines](guidelines.html) are version **28.27 2024-12-06**.
These [IOCCC guidelines](guidelines.html) are version **28.28 2024-12-07**.
</p>

**IMPORTANT**: Be **SURE** to read the [IOCCC rules](rules.html).
Expand Down Expand Up @@ -360,18 +360,9 @@ page](https://github.com/ioccc-src/mkiocccentry/issues/new?assignees=&labels=bug
FAQ on "[reporting mkiocccentry bugs](../faq.html#mkiocccentry_bugs)".
</p>

<p class="leftbar">
If you want to know what `.auth.json` is, see the
FAQ on "[.auth.json](../faq.html#auth_json)".
If you want to know what the `.info.json` file is, see the
FAQ on "[.info.json](../faq.html#info_json)".
On the other hand, if you want to know a bit more details about `chkentry`, see the
FAQ about "[chkentry](../faq.html#chkentry)".
</p>

<p class="leftbar">
However, even if `mkiocccentry` or one of the tools it invokes reports an error,
**does not** necessarily mean it is a bug in the code. It might be an issue with
it **does not** necessarily mean it is a bug in the code. It might be an issue with
your submission. Thus if you report an error as a bug it might not be something
that will be fixed as there might not be anything wrong with the tools.
</p>
Expand All @@ -389,6 +380,8 @@ In many places it will prompt you to verify what you input, allowing you to
correct details as you go along.
</p>



Jump to: [top](#)

<div id="mkiocccentry-synopsis">
Expand Down Expand Up @@ -470,10 +463,19 @@ executed on it. In this case, there should be no problems, as `mkiocccentry(1)`
<p class="leftbar">
If `mkiocccentry(1)` is used and `chkentry(1)` fails to validate either of the
files, then unless it is a system specific problem, it is likely a bug in
`mkiocccentry(1)`, `chkentry(1)` or possibly `jparse`, though these are quite
`mkiocccentry(1)`, `chkentry(1)` or possibly `jparse`, though this is quite
unlikely.
</p>

<p class="leftbar">
If you want to know what `.auth.json` is, see the
FAQ on "[.auth.json](../faq.html#auth_json)".
If you want to know what the `.info.json` file is, see the
FAQ on "[.info.json](../faq.html#info_json)".
On the other hand, if you want to know a bit more details about `chkentry`, see the
FAQ about "[chkentry](../faq.html#chkentry)".
</p>

<p class="leftbar">
`chkentry` uses the `jparse` library. See the
[jparse
Expand All @@ -490,7 +492,7 @@ details.
<p class="leftbar">
The `jparse` parser, library and tools were co-developed by
[Cody Boone Ferguson](../authors.html#Cody_Boone_Ferguson) and
[Landon Curt Noll](http://www.isthe.com/chongo/index.html) in 2022 and comes
[Landon Curt Noll](http://www.isthe.com/chongo/index.html) in 2022 and come
from the [jparse repo](https://github.com/xexyl/jparse). However, the
**mkiocccentry tools use a _clone_** of the [jparse
repo](https://github.com/xexyl/jparse) **at a _specific_ release**.
Expand All @@ -501,24 +503,32 @@ Thus the `mkiocccentry` will at times be behind the
<p class="leftbar">
You do **NOT need to install** `jparse` from the [jparse
repo](https://github.com/xexyl/jparse)! The `mkiocccentry` tools link in the
static library from `mkiocccentry`'s clone itself. This also goes for the
[dbg](https://github.com/lcn2/dbg) and
[dyn_array](https://github.com/lcn2/dyn_array) libraries that the `mkiocccentry`
tools, the `dyn_array` library uses and the `jparse` library uses.
static library from the `mkiocccentry`'s _clone_.
</p>

<p class="leftbar">
The `mkiocccentry` toolkit _also_ has a clone of _both_ the [dbg
library](https://github.com/lcn2/dbg) and the
[dyn_array library](https://github.com/lcn2/dyn_array); the [dyn_array
library](https://github.com/lcn2/dyn_array) uses the [dbg
library](https://github.com/lcn2/dbg) and the [jparse
library](https://github.com/xexyl/jparse) uses both libraries but unlike in the
[jparse repo](https://github.com/xexyl/jparse), the libraries do not need to be
installed separately, in order to use the tools in `mkiocccentry`.
</p>

<p class="leftbar">
In other words, `mkiocccentry` **contains everything** you need, and _even if you
do install_ the libraries from their respective repos, it/they will **not be
used** when compiling the `mkiocccentry` tools. This is important to
make sure that you're using the correct versions, which is verified by
`chkentry`.
`chkentry`. See [Rule 17](rules.html#rule17)!
</p>

<p class="leftbar">
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
for more details on `chkentry` and how you can use it to validate your
`.auth.json` and `.info.json` files manually, without having to repackage your
submission.
</p>
Expand Down Expand Up @@ -978,7 +988,7 @@ Again, please note that in macOS, `/usr/bin/gcc` is actually `clang`!
</div>

<p class="leftbar">
When `make clobber` is invoked, we request that submission be restored
When `make clobber` is invoked, we request that submissions be restored
to its original submission state. For example, any temporary files
created during the build process, or during execution should be
removed by the `clobber` rule.
Expand All @@ -995,7 +1005,7 @@ Jump to: [top](#)

<p class="leftbar">
We **LIKE** submissions that use an edited variant of the
example Makefile, as described in the [Makefile section](#makefile),
example Makefile, as described and linked to in the [Makefile section](#makefile),
renamed as `Makefile` of course. This makes it easier for the [IOCCC Judges](../judges.html)
to test your submission. And if your submissions wins, it makes it easier to integrate it into
the [Official IOCCC winner website](https://www.ioccc.org/index.html).
Expand Down
42 changes: 29 additions & 13 deletions next/rules.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -462,7 +462,7 @@ <h2 id="ioccc-rules-version">IOCCC Rules version</h2>
</div>
<p>Jump to: <a href="#">top</a></p>
<p class="leftbar">
These <a href="rules.html">IOCCC rules</a> are version <strong>28.13 2024-12-06</strong>.
These <a href="rules.html">IOCCC rules</a> are version <strong>28.14 2024-12-07</strong>.
</p>
<p><strong>IMPORTANT</strong>: Be sure to read the <a href="guidelines.html">IOCCC guidelines</a>.</p>
<p>Jump to: <a href="#">top</a></p>
Expand Down Expand Up @@ -666,10 +666,10 @@ <h2 id="rule-5">Rule 5</h2>
original submission including, but not limited to <code>prog.c</code>, the <code>Makefile</code>
(that we create from your how to build instructions), as well as any data
files you submit.</p>
<p>If you submission wishes to modify such content, it <strong>MUST</strong> first copy the
<p>If you submission needs (or wishes :-) ) to modify such content, it <strong>MUST</strong> first copy the
file to a new filename and then modify that copy.</p>
<p class="leftbar">
You may use your entry to form a copy, or you make use your <code>Makefile</code> to form that copy.
You may use your submission to form a copy, or you can make use of your <code>Makefile</code> to form that copy.
</p>
<p class="leftbar">
If you do make a copy and then modify that copy, please be sure that
Expand Down Expand Up @@ -704,7 +704,15 @@ <h2 id="rule-7">Rule 7</h2>
<p>If you submit any content that is owned by others, you <strong>MUST
detail that ownership</strong> (i.e., who owns what) <strong><em>AND</em> document the
permission you obtained</strong>.</p>
<p>Please note that the IOCCC size tool is <strong>NOT</strong> an original work.</p>
<p class="leftbar">
Please note that the IOCCC size tool, the tools in the <a href="https://github.com/ioccc-src/mkiocccentry">mkiocccentry
repo</a> and the tools and library in
the <a href="https://github.com/xexyl/jparse/issues">jparse repo</a> (that the
<a href="https://github.com/ioccc-src/mkiocccentry">mkiocccentry repo</a> clones) are
<strong>NOT</strong> original works, unless of course you’re the respective authors, in
which case they are. Of course, neither are any of the previous
winning entries, unless of course you’re the winner! :-)
</p>
<p class="leftbar">
See also <a href="#rule5">Rule 5</a>, <a href="#rule18">Rule 18</a> and <a href="#rule21">Rule 21</a>.
</p>
Expand Down Expand Up @@ -805,7 +813,7 @@ <h3 id="tldr-rule-17---use-mkiocccentry1">TL;DR Rule 17 - Use <code>mkiocccentry
</p>
<p class="leftbar">
The <a href="https://github.com/ioccc-src/mkiocccentry">mkiocccentry repo</a>
contains <strong>IMPORTANT</strong> tools such as:
contains <strong>IMPORTANT</strong> tools and libraries such as:
</p>
<ul>
<li><p class="leftbar">
Expand All @@ -824,7 +832,7 @@ <h3 id="tldr-rule-17---use-mkiocccentry1">TL;DR Rule 17 - Use <code>mkiocccentry
<code>fnamchk(1)</code>
</p></li>
<li><p class="leftbar">
<code>jparse(1)</code> and <code>jparse(8)</code> (which <code>chkentry(1)</code> uses)
<code>jparse(1)</code> (and other tools) and <code>jparse(3)</code> (which <code>chkentry(1)</code> uses)
</p></li>
</ul>
<p class="leftbar">
Expand All @@ -837,12 +845,14 @@ <h3 id="tldr-rule-17---use-mkiocccentry1">TL;DR Rule 17 - Use <code>mkiocccentry
<a href="guidelines.html">guidelines</a>.
</p>
<p class="leftbar">
You do not explicitly need to invoke <code>jparse(1)</code> but the <code>jparse(8)</code>
library will be used when compiling various tools.
You do not explicitly need to invoke <code>jparse(1)</code> but the <code>jparse(3)</code>
library will be used when compiling the tools.
</p>
<p class="leftbar">
Of course you <strong>can</strong> invoke <code>jparse(1)</code> if you wish to validate your own JSON
data file or some other JSON file.
Of course you <strong>can</strong> invoke <code>jparse(1)</code> if you wish to validate a JSON file but
the only JSON files you might want to validate for the IOCCC are validated
by <code>chkentry(1)</code>, and that is what you should use to make sure you conform to
this rule.
</p>
<p><strong>IMPORTANT</strong>: Make <strong>SURE</strong> you have the most recent version of the
<code>mkiocccentry</code> toolkit! Not doing so will put you at a great risk of violating
Expand Down Expand Up @@ -1033,20 +1043,26 @@ <h3 id="rule-17---the-complex-details">Rule 17 - The COMPLEX details</h3>
package your submission; <code>mkiocccentry(1)</code> will run the above mentioned tools
(that do not act on the tarball) <strong>before</strong> creating the tarball and after the
tarball is created it will then verify that the tarball is okay by running
<code>txzchk(1)</code> on it.
<code>txzchk(1)</code> on it. If any step fails it is an error and submitting the
submission will result in violating this rule.
</p>
<p class="leftbar">
<strong>MAKE SURE</strong> you use the correct release of the repository; you should do this
<strong>AFTER</strong> the contest opens (pull any changes or if you prefer download the
repository via the download option at GitHub).
repository via the download option at GitHub). See the
FAQ on “<a href="../faq.html#obtaining_mkiocccentry">obtaining mkiocccentry</a>”
for more help on ensuring you do have the most up to date release.
</p>
<p class="leftbar">
We recommend that you run <code>make</code> and then install the tools (and man pages) via
<code>make install</code> (as root or using <code>sudo(1)</code> to help you run these tools from your
submission’s directory. The <code>make install</code> will install in <code>/usr/local</code>.
However, <strong>you do not have</strong> to install them, but in that case you’ll have to run it
from the toolkit’s directory or use the correct options to specify the path to
the necessary tools, and also specify the path to your files.
</p>
<p class="leftbar">
These tools will link in the <code>jparse(8)</code> library; <code>chkentry(1)</code> uses the parser
These tools will link in the <code>jparse(3)</code> library; <code>chkentry(1)</code> uses the parser
to validate the <a href="https://www.json.org/json-en.html">JSON</a> but the other tools
use parts of the library as well.
</p>
Expand Down
Loading

0 comments on commit 06850be

Please sign in to comment.