From 65cf4470879c47dd3a7bde13b9aa1f62e6eaade0 Mon Sep 17 00:00:00 2001
From: Cody Boone Ferguson <53008573+xexyl@users.noreply.github.com>
Date: Thu, 27 Feb 2025 14:56:01 -0800
Subject: [PATCH 1/2] Update FAQ, guidelines and quick start
This addresses most (if not all) of the recent changes to chkentry(1)
though a more thorough check will be made later after the mkiocccentry
code freeze.
---
faq.html | 73 +++++++++++++++--------
faq.md | 92 ++++++++++++++++++++--------
next/guidelines.html | 136 +++++++++++++++++++++++-------------------
next/guidelines.md | 139 +++++++++++++++++++++++--------------------
quick-start.html | 58 +++++++++---------
quick-start.md | 62 +++++++++----------
6 files changed, 324 insertions(+), 236 deletions(-)
diff --git a/faq.html b/faq.html
index ad9a3ea7d..3d553869a 100644
--- a/faq.html
+++ b/faq.html
@@ -425,7 +425,7 @@
IOCCC FAQ Table of Contents
-This is FAQ version 28.2.10 2025-02-26.
+This is FAQ version 28.2.11 2025-02-27.
Q 0.2: What platform should I assume for my submission?
Q 0.3: What should I put in my submission Makefile?
@@ -480,6 +481,7 @@
Q 3.9: What is an entry_id?
Q 3.10: What is a .entry.json file and how is it used?
Q 3.11: How can I validate any JSON document?
+Q 3.12: How can I install the mkiocccentry(1) and related tools?
@@ -680,17 +682,43 @@ have an mkiocccentry tool directory:
Once you’ve obtained the LATEST version (see the
FAQ on “obtaining the latest mkiocccentry toolkit”
to make sure of this), change to the mkiocccentry directory and then run:
+
make clobber all test
+to compile all the tools and run the test-suite.
+You do not have to run the test-suite but if you wish to make sure all is in
+order you may. If you wish to skip that:
make clobber all
-to compile all the tools.
+Jump to: top
+
+
Q 0.1.4: How do I install mkiocccentry(1) and related tools?
+
+After obtaining the toolkit (see the
+FAQ on “obtaining the latest mkiocccentry toolkit”)
+and compiling the tools (see the
+FAQ on “compiling mkiocccentry”
+above) run as either sudo(8) or root make install:
+ # if you use sudo(8):
+ sudo make install
+
+ # as root:
+ make install
+If everything goes well you should be able to run mkiocccentry(1),
+txzchk(1), chkentry(1) and all the other installed tools from any directory,
+and the tools that rely on other tools will be able to find those required tools
+from any directory too.
+Some tools like bug_report.sh and hostchk.sh are not meant to be installed
+and will not work from any directory, however.
Jump to: top
-
Q 0.1.4: How do I use mkiocccentry?
+Q 0.1.5: How do I use mkiocccentry?
Once you have registered, you will need to package your entry with the
mkiocccentry tool. If you have not already obtained the toolkit, see the
-FAQ on “obtaining the mkiocccentry toolkit”
-and the
+FAQ on “obtaining the most recent mkiocccentry
+toolkit”,
+the
FAQ on “compiling mkiocccentry”
+and the
+FAQ on “installing the mkiocccentry tools”
if you have not already done so.
The below details discuss this very important tool. As it is complicated we will
explain how to use this tool. If you want to know what it is in simpler terms,
@@ -709,15 +737,10 @@ the timestamp; see the rules for more details on t
particular Rule 17.
IMPORTANT NOTE: if you run the program outside the repo directory
(specifying the absolute or relative path to the tool) and you have not
-installed the tools then you will have to specify the options for the tools that
-are required like chkentry(1), txzchk(1) and fnamchk(1). But even if you
-have installed them but some tools are out of date (in the install path) it will
-cause problems. Additionally, if you do not have the most recent version when
-submitting a tarball it will be rejected for not having the right versions of
-the tools. This is why you MUST make sure you have the most recent version
-of all the tools and you either run it from the repo directory itself OR you
-install them (make install as via sudo or as root). We recommend you install
-the tools but if you wish to run it from the repo directory you may.
+installed the tools (and we STRONGLY recommend you do install them),
+then you will have to specify the options for the tools that are required like
+chkentry(1), txzchk(1) and fnamchk(1). And remember to make sure you have
+the latest version so you do not violate Rule 17.
If the subdirectory in the work directory (based on your submit ID and
slot number) 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
@@ -1741,16 +1764,14 @@ you can do so. For instance:
FAQ on “validating your submission tarball”
for more information.
Jump to: top
-
Q 3.3: How can I validate my submission directory?
-
If you want to validate your submission directory manually, including but not
-limited to the .auth.json or .info.json files, you should use chkentry(1)
+limited to the .auth.json and .info.json files, you should use chkentry(1)
from the mkiocccentry repo.
The chkentry(1) tool runs a variety of checks on your submission directory,
-including but not limited to, using the jparse
+including, but not limited to, using the jparse
API
to validate the two IOCCC specific JSON files (as valid JSON) and additional
checks on those files as well. An important thing that it does is verify that
@@ -1768,12 +1789,14 @@ and
FAQ on “.info.json”
for more details on the two required and very important JSON files.
The chkentry(1) tool accepts a single arg, a directory that MUST have the
-two JSON files, .auth.json and .info.json. (Okay there is an option to skip
-files but this is for the judges ONLY; use of this option to validate your
-submission puts you at a great risk of violating Rule
-17!).
-As an example, if your submission directory is 12345678-1234-4321-abcd-1234567890ab-0/ then you should run the
-following command:
+two JSON files, .auth.json and .info.json as well as the prog.c,
+Makefile and remarks.md files along with all the other files listed in the
+.info.json manifest. (Okay there is an option to skip files but this is for
+the judges ONLY; use of this option to validate your submission puts you at
+a great risk of violating Rule 17!).
+As an example, if your submission directory is
+12345678-1234-4321-abcd-1234567890ab-0/ then you should run the following
+command:
chkentry 12345678-1234-4321-abcd-1234567890ab-0
If there is a JSON issue detected by the
jparse(3) API (i.e. it is not valid JSON) it is an error and chkentry(1)
diff --git a/faq.md b/faq.md
index d4cd97f12..a0ff1240b 100644
--- a/faq.md
+++ b/faq.md
@@ -1,6 +1,6 @@
# IOCCC FAQ Table of Contents
-This is FAQ version **28.2.10 2025-02-26**.
+This is FAQ version **28.2.11 2025-02-27**.
## 0. [Entering the IOCCC: the bare minimum you need to know](#enter_questions)
@@ -9,7 +9,8 @@ This is FAQ version **28.2.10 2025-02-26**.
- **Q 0.1.1**: What is `mkiocccentry(1)` in simple terms?
- **Q 0.1.2**: How do I obtain the latest mkiocccentry toolkit?
- **Q 0.1.3**: How do I compile the mkiocccentry toolkit?
- - **Q 0.1.4**: How do I use mkiocccentry?
+ - **Q 0.1.4**: How do I install mkiocccentry(1) and related tools?
+ - **Q 0.1.5**: How do I use mkiocccentry?
- **Q 0.2**: What platform should I assume for my submission?
- **Q 0.3**: What should I put in my submission Makefile?
- **Q 0.4**: What should I put in the remarks.md file of my submission?
@@ -54,6 +55,7 @@ This is FAQ version **28.2.10 2025-02-26**.
- **Q 3.9**: What is an `entry_id`?
- **Q 3.10**: What is a `.entry.json` file and how is it used?
- **Q 3.11**: How can I validate any JSON document?
+- **Q 3.12**: How can I install the `mkiocccentry(1)` and related tools?
## 4. [Compiling IOCCC entries](#compiling)
@@ -289,23 +291,66 @@ Once you've obtained the **LATEST** version (see the
FAQ on "[obtaining the latest mkiocccentry toolkit](#obtaining_mkiocccentry)"
to make sure of this), change to the `mkiocccentry` directory and then run:
+```
+ make clobber all test
+```
+
+to compile all the tools and run the test-suite.
+
+You do not have to run the test-suite but if you wish to make sure all is in
+order you may. If you wish to skip that:
+
```
make clobber all
```
-to compile all the tools.
Jump to: [top](#)
+
+### Q 0.1.4: How do I install mkiocccentry(1) and related tools?
+
+
+After obtaining the toolkit (see the
+FAQ on "[obtaining the latest mkiocccentry toolkit](#obtaining_mkiocccentry)")
+and compiling the tools (see the
+FAQ on "[compiling mkiocccentry](#compiling_mkiocccentry)"
+above) run as either `sudo(8)` or root `make install`:
+
+
+
+```
+ # if you use sudo(8):
+ sudo make install
+
+ # as root:
+ make install
+```
+
+
+If everything goes well you should be able to run `mkiocccentry(1)`,
+`txzchk(1)`, `chkentry(1)` and all the other installed tools from any directory,
+and the tools that rely on other tools will be able to find those required tools
+from any directory too.
+
+Some tools like `bug_report.sh` and `hostchk.sh` are not meant to be installed
+and will not work from any directory, however.
+
+Jump to: [top](#)
+
+
-#### Q 0.1.4: How do I use mkiocccentry?
+#### Q 0.1.5: How do I use mkiocccentry?
Once you have registered, you will need to package your entry with the
`mkiocccentry` tool. If you have not already obtained the toolkit, see the
-FAQ on "[obtaining the mkiocccentry toolkit](#obtaining_mkiocccentry)"
-and the
+FAQ on "[obtaining the most recent mkiocccentry
+toolkit](#obtaining_mkiocccentry)",
+the
FAQ on "[compiling mkiocccentry](#compiling_mkiocccentry)"
+and the
+FAQ on "[installing the mkiocccentry tools](#installing)"
if you have not already done so.
The below details discuss this very important tool. As it is complicated we will
@@ -332,15 +377,10 @@ particular [Rule 17](next/rules.html#rule17).
**IMPORTANT NOTE**: if you run the program outside the repo directory
(specifying the absolute or relative path to the tool) and you have not
-installed the tools then you will have to specify the options for the tools that
-are required like `chkentry(1)`, `txzchk(1)` and `fnamchk(1)`. But even if you
-have installed them but some tools are out of date (in the install path) it will
-cause problems. Additionally, if you do not have the most recent version when
-submitting a tarball it will be rejected for not having the right versions of
-the tools. This is why you **MUST** make sure you have the most recent version
-of all the tools and you either run it from the repo directory itself OR you
-install them (`make install` as via `sudo` or as root). We recommend you install
-the tools but if you wish to run it from the repo directory you may.
+installed the tools (and we **STRONGLY** recommend you **do** install them),
+then you will have to specify the options for the tools that are required like
+`chkentry(1)`, `txzchk(1)` and `fnamchk(1)`. And remember to make sure you have
+the latest version so you do not violate [Rule 17](next/rules.html#rule17).
If the **_subdirectory_ in the _work directory_** (based on your submit ID and
slot number) already exists, you will have to move it, remove it or otherwise
@@ -1584,18 +1624,16 @@ for more information.
Jump to: [top](#)
-
### Q 3.3: How can I validate my submission directory?
-
If you want to validate your submission directory manually, including but not
-limited to the `.auth.json` or `.info.json` files, you should use `chkentry(1)`
+limited to the `.auth.json` and `.info.json` files, you should use `chkentry(1)`
from the [mkiocccentry repo](https://github.com/ioccc-src/mkiocccentry).
The `chkentry(1)` tool runs a variety of checks on your submission directory,
-including but not limited to, using the [jparse
+including, but not limited to, using the [jparse
API](https://github.com/ioccc-src/mkiocccentry/blob/master/jparse/man/man3/jparse.3)
to validate the two IOCCC specific JSON files (as valid JSON) and additional
checks on those files as well. An important thing that it does is verify that
@@ -1616,13 +1654,15 @@ FAQ on "[.info.json](#info_json)"
for more details on the two required and very important JSON files.
The `chkentry(1)` tool accepts a single arg, a directory that **MUST** have the
-two JSON files, `.auth.json` and `.info.json`. (Okay there is an option to skip
-files but this is for the judges **ONLY**; use of this option to validate your
-submission puts you at a great risk of violating [Rule
-17](next/rules.html#rule17)!).
+two JSON files, `.auth.json` and `.info.json` as well as the `prog.c`,
+`Makefile` and `remarks.md` files along with all the other files listed in the
+`.info.json` manifest. (Okay there is an option to skip files but this is for
+the judges **ONLY**; use of this option to validate your submission puts you at
+a great risk of violating [Rule 17](next/rules.html#rule17)!).
-As an example, if your submission directory is `12345678-1234-4321-abcd-1234567890ab-0/` then you should run the
-following command:
+As an example, if your submission directory is
+`12345678-1234-4321-abcd-1234567890ab-0/` then you should run the following
+command:
```
@@ -3557,6 +3597,7 @@ something along those lines.
Jump to: [top](#)
+
### Q 3.11: How can I validate any JSON document?
@@ -3612,6 +3653,7 @@ as the two can be different at times.
Jump to: [top](#)
+
diff --git a/next/guidelines.html b/next/guidelines.html
index 4dfbe2311..d56e36e93 100644
--- a/next/guidelines.html
+++ b/next/guidelines.html
@@ -462,7 +462,7 @@ writing by
contacting the judges.
-These IOCCC guidelines are version 28.39 2025-02-26.
+These IOCCC guidelines are version 28.40 2025-02-27.
The markdown form of these guidelines
IMPORTANT NOTE: if you run the program outside the repo directory
(specifying the absolute or relative path to the tool) and you have not
-installed the tools then you will have to specify the options for the tools that
-are required like chkentry(1), txzchk(1) and fnamchk(1). But even if you
-have installed them but some tools are out of date (in the install path) it will
-cause problems. Additionally, if you do not have the most recent version when
-submitting a tarball it will be rejected for not having the right versions of
-the tools. This is why you MUST make sure you have the most recent version
-of all the tools and you either run it from the repo directory itself OR you
-install them (make install as via sudo or as root). We recommend you install
-the tools but if you wish to run it from the repo directory you may.
+installed the tools (and we STRONGLY recommend you do install them),
+then you will have to specify the options for the tools that are required like
+chkentry(1), txzchk(1) and fnamchk(1). And remember to make sure you have
+the latest version so you do not violate Rule 17.
+See the
+FAQ on “obtaining the latest mkiocccentry tools”,
+the
+FAQ on “compiling the mkiocccentry tools”,
+the
+FAQ on “installing the mkiocccentry tools”
+and the
+FAQ on “using the mkiocccentry tools”
+for more help.
Rule 17 has been significantly modified
@@ -858,9 +862,10 @@ its algorithm.
If mkiocccentry encounters an error the program will exit and the xz
compressed tarball will not be formed. For instance, if
-chkentry fails to validate the .auth.json or .info.json
-JSON files (see below) that
-mkiocccentry(1) creates, or anything else mkiocccentry(1) does, it is an
+chkentry fails to validate the submission directory, either because
+of a validation error in the .auth.json or .info.json
+JSON files or because of
+something else that mkiocccentry(1) creates or does, it is an
error and possibly a bug that you should report as a bug at the
mkiocccentry bug report
page.
@@ -931,7 +936,17 @@ checks described above are still made but through mkiocccentry itse
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)!
+submission. After these files are formed, the chkentry(1) tool will be run on
+the submission directory; this tool not only validates the two JSON files
+(running specific checks on them after validating the JSON), but it also
+verifies that what is in the manifest in .info.json matches the contents of
+the directory, in addition to other checks. If chkentry(1) fails to validate
+anything at all, your submission WILL BE rejected!
+
+
+IMPORTANT: although chkentry(1) validates the files in the directory, it
+only inspects the contents of the two JSON files; it performs other checks on
+the other files, and those checks are run on the two JSON files as well.
If chkentry does not pass and you used mkiocccentry(1) it is very likely a
@@ -941,26 +956,21 @@ page.
make bug_report
-from the top level repo directory itself.
-See also the
+from the top level repo directory itself and attach the bug report file (it will
+tell you the name of the file). See also the
FAQ on “reporting mkiocccentry bugs”.
-Assuming that chkentry(1) successfully validates both .auth.json and
-.info.json, then the tarball will be formed and then txzchk(1) will be
-executed on it. In this case, there should be no problems, as mkiocccentry(1) should
-NOT form a tarball if there are any issues.
-
-
-NOTE: chkentry(1) also validates other things in your submission
-directory.
+Assuming that chkentry(1) successfully validates your submission directory,
+the tarball will be formed and then txzchk(1) will be executed on it. In this
+case, there should be no problems, as mkiocccentry(1) should NOT form a
+tarball if there are any issues.
If mkiocccentry(1) is used and chkentry(1) fails to validate your submission
directory, then unless it is a system specific problem, it could be a bug in
-mkiocccentry(1), chkentry(1) or possibly jparse, though this is quite
-unlikely. Nonetheless, if you believe there is a bug, you may report it as
-explained above.
+mkiocccentry(1), chkentry(1) or possibly jparse, although this is unlikely.
+Nonetheless, if you believe there is a bug, you may report it as explained above.
If you want to know what .auth.json is, see the
@@ -983,13 +993,12 @@ jparse, for more
details.
-The jparse parser, library and tools were co-developed by
-Cody Boone Ferguson and
-Landon Curt Noll in 2022 and come
-from the jparse repo. However, the
-mkiocccentry tools use a clone of the jparse
-repo at a specific release.
-Thus the mkiocccentry will at times be behind the
+The jparse parser, library and tools were co-developed by Cody Boone
+Ferguson and Landon Curt
+Noll in 2022-2025 and come from the
+jparse repo. However, the mkiocccentry
+tools use a clone of the jparse repo at
+a specific release. Thus the mkiocccentry will at times be behind the
jparse repo!
@@ -1017,10 +1026,8 @@ make sure that you’re using the correct versions, which is also verified by
Please see the
-FAQ on “validating .auth.json and/or .info.json files
-for more details on chkentry and how you can use it to validate your
-.auth.json and .info.json files (and your submission directory in general)
-manually, without having to repackage your submission.
+FAQ on “validating your submission directory
+for more details on chkentry.
You might also wish to see the
@@ -1944,46 +1951,51 @@ some Intel-like x86 architecture**.
The IOCCC size tool source is not an original work, unless you are Anthony C
Howe, in which case it is original! :-)
Submitting source code that uses the content of
-iocccsize.c, unless you are
-Anthony C Howe, might run the risk of
-violating Rule 7.
+iocccsize.c,
+unless you are Anthony C Howe, might run the
+risk of violating Rule 7.
-The txzchk(1) tool source is not an original work,
+The IOCCC submission tarball validator source is not an original work,
unless you are Cody Boone Ferguson, in
which case it is original! :-) Submitting source code that uses the contents of
txzchk.c,
-unless you are Cody Boone Ferguson, might
+unless you are Cody Boone Ferguson, might
run the risk of violating Rule 7.
-Neither the chkentry tool
-source nor
-the JSON parser and
-library
-nor
-jstrencode
-nor
+In addition to the above tools, none of the mkiocccentry
+tools, including, but not
+limited to
+mkiocccentry,
+chkentry,
+fnamchk
+and
+location,
+nor the JSON parser and
+library,
+jstrencode,
jstrdecode
-nor any of the other jparse
+or any of the other jparse
tools
-(see the jparse repo), nor the fnamchk tool
-source,
-are original works,
+(see the jparse repo), are original works,
unless you are Cody Boone Ferguson or
Landon Curt Noll, in which case they
-are original! :-) Submitting source code that uses the code of any of these tools or
-library, unless you are Cody Boone
+are original! :-) Submitting source code that uses the content of any of these tools or
+library, unless you are Cody Boone
Ferguson or Landon Curt
Noll, might run the risk of violating
Rule 7.
-Unless you are Landon Curt Noll, the
-remaining tools in the mkiocccentry repo
-are NOT original works. Submitting source code that uses the content of those tools,
-unless you are Landon Curt Noll, might
-run the risk of violating Rule 7.
+And unless you are Landon Curt Noll,
+the code in
+dbg and
+dyn_array are
+not original works. Submitting source code that uses the content of those
+libraries, unless you Landon Curt
+Noll, might run the risk of violating
+Rule 7.
Rule 7 does not prohibit you from writing your own
@@ -1999,7 +2011,7 @@ mind that writing an obfuscated version of a library runs the risk of violating
Even so, we do not recommend you try and submit a JSON parser due to
the fact it will likely exceed the source code size limit
-and because you likely can’t beat flex or
+and because you likely can’t beat flex and
bison in obfuscation. This isn’t to
say that the so-called JSON spec is not
obfuscated, but unless you have some really clever way to compact and
diff --git a/next/guidelines.md b/next/guidelines.md
index d9d891287..8cd73728a 100644
--- a/next/guidelines.md
+++ b/next/guidelines.md
@@ -50,7 +50,7 @@ Jump to: [top](#)
-These [IOCCC guidelines](guidelines.html) are version **28.39 2025-02-26**.
+These [IOCCC guidelines](guidelines.html) are version **28.40 2025-02-27**.
@@ -238,15 +238,19 @@ normal mode.
**IMPORTANT NOTE**: if you run the program outside the repo directory
(specifying the absolute or relative path to the tool) and you have not
-installed the tools then you will have to specify the options for the tools that
-are required like `chkentry(1)`, `txzchk(1)` and `fnamchk(1)`. But even if you
-have installed them but some tools are out of date (in the install path) it will
-cause problems. Additionally, if you do not have the most recent version when
-submitting a tarball it will be rejected for not having the right versions of
-the tools. This is why you **MUST** make sure you have the most recent version
-of all the tools and you either run it from the repo directory itself OR you
-install them (`make install` as via `sudo` or as root). We recommend you install
-the tools but if you wish to run it from the repo directory you may.
+installed the tools (and we **STRONGLY** recommend you **do** install them),
+then you will have to specify the options for the tools that are required like
+`chkentry(1)`, `txzchk(1)` and `fnamchk(1)`. And remember to make sure you have
+the latest version so you do not violate [Rule 17](rules.html#rule17).
+See the
+FAQ on "[obtaining the latest mkiocccentry tools](../faq.html#obtaining_mkiocccentry)",
+the
+FAQ on "[compiling the mkiocccentry tools](../faq.html#compiling_mkiocccentry)",
+the
+FAQ on "[installing the mkiocccentry tools](../faq.html#installing)"
+and the
+FAQ on "[using the mkiocccentry tools](../faq.html#using_mkiocccentry)"
+for more help.
@@ -535,9 +539,10 @@ its algorithm.
If `mkiocccentry` encounters an **error** the program will exit and the xz
compressed tarball **will not be formed**. For instance, if
-[chkentry](#chkentry) fails to validate the `.auth.json` or `.info.json`
-[JSON](https://www.json.org/json-en.html) files (see below) that
-`mkiocccentry(1)` creates, or anything else `mkiocccentry(1)` does, it is an
+[chkentry](#chkentry) fails to validate the submission directory, either because
+of a validation error in the `.auth.json` or `.info.json`
+[JSON](https://www.json.org/json-en.html) files or because of
+something else that `mkiocccentry(1)` creates or does, it is an
**error** and **possibly** a bug that you should [report as a bug at the
mkiocccentry bug report
page](https://github.com/ioccc-src/mkiocccentry/issues/new?assignees=&labels=bug&projects=&template=bug_report.yml&title=%5BBug%5D+%3Ctitle%3E).
@@ -632,7 +637,18 @@ Jump to: [top](#)
`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)`!
+submission. After these files are formed, the `chkentry(1)` tool will be run on
+the submission directory; this tool not only validates the two JSON files
+(running specific checks on them after validating the JSON), but it also
+verifies that what is in the manifest in `.info.json` matches the contents of
+the directory, in addition to other checks. If `chkentry(1)` fails to validate
+anything at all, your submission **WILL BE** rejected!
+
+
+
+**IMPORTANT**: although `chkentry(1)` validates the files in the directory, it
+only inspects the contents of the two JSON files; it performs other checks on
+the other files, and those checks are run on the two JSON files as well.
@@ -647,29 +663,23 @@ page](https://github.com/ioccc-src/mkiocccentry/issues/new?assignees=&labels=bug
```
-from the top level repo directory itself.
-See also the
+from the top level repo directory itself and attach the bug report file (it will
+tell you the name of the file). See also the
FAQ on "[reporting mkiocccentry bugs](../faq.html#mkiocccentry_bugs)".
-Assuming that `chkentry(1)` successfully validates both `.auth.json` and
-`.info.json`, then the tarball will be formed and then `txzchk(1)` will be
-executed on it. In this case, there should be no problems, as `mkiocccentry(1)` should
-**NOT** form a tarball if there are any issues.
-
-
-
-**NOTE**: `chkentry(1)` also validates other things in your submission
-directory.
+Assuming that `chkentry(1)` successfully validates your submission directory,
+the tarball will be formed and then `txzchk(1)` will be executed on it. In this
+case, there should be no problems, as `mkiocccentry(1)` should **NOT** form a
+tarball if there are any issues.
If `mkiocccentry(1)` is used and `chkentry(1)` fails to validate your submission
directory, then unless it is a system specific problem, it could be a bug in
-`mkiocccentry(1)`, `chkentry(1)` or possibly `jparse`, though this is quite
-unlikely. Nonetheless, if you believe there is a bug, you may report it as
-explained above.
+`mkiocccentry(1)`, `chkentry(1)` or possibly `jparse`, although this is unlikely.
+Nonetheless, if you believe there is a bug, you may report it as explained above.
@@ -695,13 +705,12 @@ details.
-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 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**.
-Thus the `mkiocccentry` will at times be behind the
+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-2025 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**. Thus the `mkiocccentry` will at times be behind the
[jparse repo](https://github.com/xexyl/jparse)!
@@ -733,10 +742,8 @@ make sure that you're using the correct versions, which is also verified by
Please see the
-FAQ on "[validating .auth.json and/or .info.json files](../faq.html#chkentry)
-for more details on `chkentry` and how you can use it to validate your
-`.auth.json` and `.info.json` files (and your submission directory in general)
-manually, without having to repackage your submission.
+FAQ on "[validating your submission directory](../faq.html#chkentry)
+for more details on `chkentry`.
@@ -1883,47 +1890,51 @@ We believe that Mark Twain's quote:
The IOCCC size tool source is not an original work, unless you are [Anthony C
Howe](../authors.html#Anthony_C_Howe), in which case it is original! :-)
Submitting source code that uses the content of
-[iocccsize.c](https://github.com/ioccc-src/mkiocccentry/blob/master/iocccsize.c), unless you are
-[Anthony C Howe](../authors.html#Anthony_C_Howe), might run the risk of
-violating [Rule 7](rules.html#rule7).
+[iocccsize.c](https://github.com/ioccc-src/mkiocccentry/blob/master/iocccsize.c),
+_unless_ you are [Anthony C Howe](../authors.html#Anthony_C_Howe), might run the
+risk of violating [Rule 7](rules.html#rule7).
- The `txzchk(1)` tool source is not an original work,
+
The IOCCC submission tarball validator source is not an original work,
unless you are [Cody Boone Ferguson](../authors.html#Cody_Boone_Ferguson), in
which case it is original! :-) Submitting source code that uses the contents of
[txzchk.c](https://github.com/ioccc-src/mkiocccentry/blob/master/txzchk.c),
-unless you are [Cody Boone Ferguson](../authors.html#Cody_Boone_Ferguson), might
+_unless_ you are [Cody Boone Ferguson](../authors.html#Cody_Boone_Ferguson), might
run the risk of violating [Rule 7](rules.html#rule7).
-Neither the [chkentry tool
-source](https://github.com/ioccc-src/mkiocccentry/blob/master/chkentry.c) nor
-the [JSON parser and
-library](https://github.com/ioccc-src/mkiocccentry/blob/master/jparse/README.md)
-nor
-[jstrencode](https://github.com/ioccc-src/mkiocccentry/blob/master/jparse/jstrencode.c)
-nor
+In addition to the above tools, none of the [mkiocccentry
+tools](https://github.com/ioccc-src/mkiocccentry), _including, **but not
+limited**_ to
+[mkiocccentry](https://github.com/ioccc-src/mkiocccentry/blob/master/mkiocccentry.c),
+[chkentry](https://github.com/ioccc-src/mkiocccentry/blob/master/chkentry.c),
+[fnamchk](https://github.com/ioccc-src/mkiocccentry/blob/master/test_ioccc/fnamchk.c)
+and
+[location](https://github.com/ioccc-src/mkiocccentry/blob/master/soup/location_main.c),
+nor the [JSON parser and
+library](https://github.com/ioccc-src/mkiocccentry/blob/master/jparse/README.md),
+[jstrencode](https://github.com/ioccc-src/mkiocccentry/blob/master/jparse/jstrencode.c),
[jstrdecode](https://github.com/ioccc-src/mkiocccentry/blob/master/jparse/jstrdecode.c)
-nor any of the other [jparse
+or any of the other [jparse
tools](https://github.com/ioccc-src/mkiocccentry/blob/master/jparse)
-(see the [jparse repo](https://github.com/xexyl/jparse/)), nor the [fnamchk tool
-source](https://github.com/ioccc-src/mkiocccentry/blob/master/test_ioccc/fnamchk.c),
-are original works,
+(see the [jparse repo](https://github.com/xexyl/jparse/)), are original works,
unless you are [Cody Boone Ferguson](../authors.html#Cody_Boone_Ferguson) or
[Landon Curt Noll](http://www.isthe.com/chongo/index.html), in which case they
-are original! :-) Submitting source code that uses the code of any of these tools or
-library, unless you are [Cody Boone
+are original! :-) Submitting source code that uses the content of any of these tools or
+library, _unless_ you are [Cody Boone
Ferguson](../authors.html#Cody_Boone_Ferguson) or [Landon Curt
Noll](http://www.isthe.com/chongo/index.html), might run the risk of violating
[Rule 7](rules.html#rule7).
-Unless you are [Landon Curt Noll](http://www.isthe.com/chongo/index.html), the
-remaining tools in the [mkiocccentry repo](https://github.com/ioccc-src/mkiocccentry)
-are **NOT** original works. Submitting source code that uses the content of those tools,
-unless you are [Landon Curt Noll](http://www.isthe.com/chongo/index.html), might
-run the risk of violating [Rule 7](rules.html#rule7).
-
+And unless you are [Landon Curt Noll](http://www.isthe.com/chongo/index.html),
+the code in
+[dbg](https://github.com/ioccc-src/mkiocccentry/tree/master/dbg) and
+[dyn_array](https://github.com/ioccc-src/mkiocccentry/tree/master/dyn_array) are
+not original works. Submitting source code that uses the content of those
+libraries, _unless_ you [Landon Curt
+Noll](http://www.isthe.com/chongo/index.html), might run the risk of violating
+[Rule 7](rules.html#rule7).
[Rule 7](rules.html#rule7) does not prohibit you from writing your own
@@ -1940,7 +1951,7 @@ mind that writing an obfuscated version of a library runs the risk of violating
Even so, we do not recommend you try and submit a JSON parser due to
the fact it will likely exceed [the source code size limit](rules.html#rule2)
-and because you likely can't beat [flex](https://github.com/westes/flex) or
+and because you likely can't beat [flex](https://github.com/westes/flex) and
[bison](https://www.gnu.org/software/bison/) in obfuscation. This isn't to
say that [the so-called JSON spec](https://github.com/xexyl/jparse/blob/master/json_README.md#so-called-json-spec) is not
obfuscated, but unless you have some really clever way to compact and
diff --git a/quick-start.html b/quick-start.html
index 93d20b63c..ba27761fe 100644
--- a/quick-start.html
+++ b/quick-start.html
@@ -424,6 +424,7 @@
+
This is quick start guide is version 28.0.0 2025-02-27.
Entering the IOCCC: the bare minimum you need to know
@@ -431,7 +432,7 @@
To submit your code to the IOCCC, you MUST follow these steps:
-
0. Verify that the IOCCC is pending or open for submissions
+0. Verify that the IOCCC is pending or open for submissions
First, check the “current status of the IOCCC” page to see current contest status.
You may only register for the IOCCC when the IOCCC is either pending
@@ -439,7 +440,7 @@ or open.
You may only submit your entries to the IOCCC when the IOCCC is open.
See also the IOCCC news for more information.
-
1. Read the latest IOCCC rules and review the IOCCC guidelines
+1. Read the latest IOCCC rules and review the IOCCC guidelines
Please pay close attention to the official IOCCC rules.
You are also highly encouraged to review the
@@ -447,7 +448,7 @@ or open.
suggestions, useful hints, and IOCCC humor. :-)
-
2. Register for the IOCCC
+2. Register for the IOCCC
IMPORTANT: You may only register for the IOCCC when the IOCCC is either pending
@@ -455,7 +456,7 @@ or open. See “pending or open,
then follow the directions on “how to register for the IOCCC”.
-
3. Wait for your submit server username and initial password
+3. Wait for your submit server username and initial password
Once you have registered for the IOCCC,
and once the contest is OPEN, one of the
@@ -477,7 +478,7 @@ password, and the CONTEST IS OPENContact the IOCCC
for assistance.
-
4. Login to the submit server and change your password
+4. Login to the submit server and change your password
Using the Username and Initial password you receive via email in
step 3, you need to login to the IOCCC submit server.
@@ -487,7 +488,7 @@ from when one of the
IOCCC judges sent that email.
is only ready for submissions
ONLY WHEN THE CONTEST IS open.
Please visit the “change your submit server initial password” page for detailed instructions.
-
5. Obtain and compile the latest mkiocccentry toolkit
+5. Obtain and compile the latest mkiocccentry toolkit
Once the contest is open, download the most recent
version of the mkiocccentry toolkit.
@@ -496,12 +497,14 @@ the
mkiocccentry toolkit
could change. Once the content is
open, be sure
you
have the latest version installed.
To help you, please see the
-FAQ on “how to obtain the most recent mkiocccentry”
+FAQ on “how to obtain the most recent mkiocccentry”,
+the
+FAQ on “compiling mkiocccentry toolkit”
and the
-FAQ on “compiling mkiocccentry toolkit”,
+FAQ on “installing the mkiocccentry tools”
for more details.
-
6. Run the mkiocccentry tool to form your submission tarball
+6. Run the mkiocccentry tool to form your submission tarball
For more details on mkiocccentry, what it is, how to obtain it and how to use
it, see the
@@ -525,7 +528,7 @@ guidelines.
prog.c
path to the C source for your submission
Makefile
-Makefile to build (make all) and cleanup (make clean & make clobber) as well
+
Makefile to build (make all) and clean up (make clean & make clobber) as well
as the other required rules
remarks.md
Remarks about your entry in markdown format: see the
@@ -533,24 +536,6 @@ FAQ on “remarks.md”
for more info.
NOTE: Please see our IOCCC markdown guide for important information on using markdown in the IOCCC.
-
NOTE: It is NOT necessary to install the tools to use them as you can run
-the tools from the top of the mkiocccentry repo directory just fine, though
-you’ll have to use the form of ./mkiocccentry instead of just mkiocccentry.
-However, installing it will make it easier for you as you can run it from your
-submission’s directory. See the
-FAQ on “installing mkiocccentry”
-at the mkiocccentry repo.
-
IMPORTANT NOTE: if you run the program outside the repo directory
-(specifying the absolute or relative path to the tool) and you have not
-installed the tools then you will have to specify the options for the tools that
-are required like chkentry(1), txzchk(1) and fnamchk(1). But even if you
-have installed them but some tools are out of date (in the install path) it will
-cause problems. Additionally, if you do not have the most recent version when
-submitting a tarball it will be rejected for not having the right versions of
-the tools. This is why you MUST make sure you have the most recent version
-of all the tools and you either run it from the repo directory itself OR you
-install them (make install as via sudo or as root). We recommend you install
-the tools but if you wish to run it from the repo directory you may.
If the mkiocccentry tool indicates that there is a problem with your
submission, especially if it identifies a Rule 2, or
any other rule, related problem, you are strongly encouraged to revise and
@@ -558,9 +543,24 @@ correct your entry and then re-run the mkiocccentry tool.
If you choose to risk violating rules, be sure and explain your reason
for doing so in your remarks.md file.
See also Rule 17!
+
IMPORTANT NOTE: if you run the program outside the repo directory
+(specifying the absolute or relative path to the tool) and you have not
+installed the tools (and we STRONGLY recommend you do install them),
+then you will have to specify the options for the tools that are required like
+chkentry(1), txzchk(1) and fnamchk(1). And remember to make sure you have
+the latest version so you do not violate Rule 17.
+See the
+FAQ on “obtaining the latest mkiocccentry tools”,
+the
+FAQ on “compiling the mkiocccentry tools”,
+the
+FAQ on “installing the mkiocccentry tools”
+and the
+FAQ on “using the mkiocccentry tools”
+for more help.
-
7. Upload your submission to the IOCCC submit server
+7. Upload your submission to the IOCCC submit server
The screenshots on the “how to upload your submission to the IOCCC” page
diff --git a/quick-start.md b/quick-start.md
index 1cdac2008..314d1641b 100644
--- a/quick-start.md
+++ b/quick-start.md
@@ -1,3 +1,5 @@
+This is quick start guide is version **28.0.0 2025-02-27**.
+
# Entering the IOCCC: the bare minimum you need to know
@@ -8,7 +10,7 @@ To submit your code to the IOCCC, you **MUST** follow these steps:
-#### 0. Verify that the IOCCC is pending or open for submissions
+## 0. Verify that the IOCCC is pending or open for submissions
First, check the "**[current status of the IOCCC](status.html)**" page to see current contest status.
@@ -21,7 +23,7 @@ See also the [IOCCC news](news.html#news) for more information.
-#### 1. Read the latest IOCCC rules and review the IOCCC guidelines
+## 1. Read the latest IOCCC rules and review the IOCCC guidelines
Please pay close attention to the [official IOCCC rules](next/rules.html).
@@ -33,7 +35,7 @@ suggestions, useful hints, and IOCCC humor. :-)
-#### 2. Register for the IOCCC
+## 2. Register for the IOCCC
@@ -45,7 +47,7 @@ then follow the directions on "**[how to register for the IOCCC](next/register.h
-#### 3. Wait for your submit server username and initial password
+## 3. Wait for your submit server username and initial password
Once you have [registered for the IOCCC](next/register.html),
@@ -74,7 +76,7 @@ for assistance.
-#### 4. Login to the submit server and change your password
+## 4. Login to the submit server and change your password
Using the **Username** and **Initial password** you receive via email in
@@ -90,7 +92,7 @@ Please visit the "**[change your submit server initial password](next/pw-change.
-#### 5. Obtain and compile the latest mkiocccentry toolkit
+## 5. Obtain and compile the latest mkiocccentry toolkit
Once the contest is [open](status.html#open), download the most recent
@@ -102,14 +104,16 @@ could change. Once the content is [open](status.html#open), be sure
you **have the latest** version installed.
To help you, please see the
-FAQ on "[how to obtain the most recent mkiocccentry](#obtaining_mkiocccentry)"
+FAQ on "[how to obtain the most recent mkiocccentry](faq.html#obtaining_mkiocccentry)",
+the
+FAQ on "[compiling mkiocccentry toolkit](faq.html#compiling_mkiocccentry)"
and the
-FAQ on "[compiling mkiocccentry toolkit](#compiling_mkiocccentry)",
+FAQ on "[installing the mkiocccentry tools](faq.html#install)"
for more details.
-#### 6. Run the mkiocccentry tool to form your submission tarball
+## 6. Run the mkiocccentry tool to form your submission tarball
For more details on `mkiocccentry`, what it is, how to obtain it and how to use
@@ -145,7 +149,7 @@ Three files are required to exist in `topdir`:
* `Makefile`
- Makefile to build (make all) and cleanup (make clean & make clobber) as well
+ Makefile to build (make all) and clean up (make clean & make clobber) as well
as the other required rules
* `remarks.md`
@@ -156,26 +160,6 @@ Three files are required to exist in `topdir`:
**NOTE**: Please see our [IOCCC markdown guide](markdown.html) for **important information** on using markdown in the IOCCC.
-**NOTE**: It is *NOT* necessary to install the tools to use them as you can run
-the tools from the top of the `mkiocccentry` repo directory just fine, though
-you'll have to use the form of `./mkiocccentry` instead of just `mkiocccentry`.
-However, installing it will make it easier for you as you can run it from your
-submission's directory. See the
-FAQ on "**[installing mkiocccentry](https://github.com/ioccc-src/mkiocccentry/blob/master/FAQ.md#install)**"
-at the mkiocccentry repo.
-
-**IMPORTANT NOTE**: if you run the program outside the repo directory
-(specifying the absolute or relative path to the tool) and you have not
-installed the tools then you will have to specify the options for the tools that
-are required like `chkentry(1)`, `txzchk(1)` and `fnamchk(1)`. But even if you
-have installed them but some tools are out of date (in the install path) it will
-cause problems. Additionally, if you do not have the most recent version when
-submitting a tarball it will be rejected for not having the right versions of
-the tools. This is why you **MUST** make sure you have the most recent version
-of all the tools and you either run it from the repo directory itself OR you
-install them (`make install` as via `sudo` or as root). We recommend you install
-the tools but if you wish to run it from the repo directory you may.
-
If the `mkiocccentry` tool indicates that there is a problem with your
submission, especially if it identifies a [Rule 2](next/rules.html#rule2), or
any other rule, related problem, you are **strongly** encouraged to revise and
@@ -186,10 +170,26 @@ for doing so in your `remarks.md` file.
See also [Rule 17](next/rules.html#rule17)!
+**IMPORTANT NOTE**: if you run the program outside the repo directory
+(specifying the absolute or relative path to the tool) and you have not
+installed the tools (and we **STRONGLY** recommend you **do** install them),
+then you will have to specify the options for the tools that are required like
+`chkentry(1)`, `txzchk(1)` and `fnamchk(1)`. And remember to make sure you have
+the latest version so you do not violate [Rule 17](rules.html#rule17).
+See the
+FAQ on "[obtaining the latest mkiocccentry tools](faq.html#obtaining_mkiocccentry)",
+the
+FAQ on "[compiling the mkiocccentry tools](faq.html#compiling_mkiocccentry)",
+the
+FAQ on "[installing the mkiocccentry tools](faq.html#installing)"
+and the
+FAQ on "[using the mkiocccentry tools](faq.html#using_mkiocccentry)"
+for more help.
+
-#### 7. Upload your submission to the IOCCC submit server
+## 7. Upload your submission to the IOCCC submit server
From 2199f31bc53bc98c6dc9fdee9094acf53059c5fa Mon Sep 17 00:00:00 2001
From: Cody Boone Ferguson <53008573+xexyl@users.noreply.github.com>
Date: Thu, 27 Feb 2025 15:01:27 -0800
Subject: [PATCH 2/2] Fix link in quick-start.html
---
quick-start.html | 2 +-
quick-start.md | 2 +-
2 files changed, 2 insertions(+), 2 deletions(-)
diff --git a/quick-start.html b/quick-start.html
index ba27761fe..56aea7213 100644
--- a/quick-start.html
+++ b/quick-start.html
@@ -548,7 +548,7 @@ for doing so in your
remarks.md file.
installed the tools (and we
STRONGLY recommend you
do install them),
then you will have to specify the options for the tools that are required like
chkentry(1),
txzchk(1) and
fnamchk(1). And remember to make sure you have
-the latest version so you do not violate
Rule 17.
+the latest version so you do not violate
Rule 17.
See the
FAQ on “
obtaining the latest mkiocccentry tools”,
the
diff --git a/quick-start.md b/quick-start.md
index 314d1641b..f4a07325d 100644
--- a/quick-start.md
+++ b/quick-start.md
@@ -175,7 +175,7 @@ See also [Rule 17](next/rules.html#rule17)!
installed the tools (and we **STRONGLY** recommend you **do** install them),
then you will have to specify the options for the tools that are required like
`chkentry(1)`, `txzchk(1)` and `fnamchk(1)`. And remember to make sure you have
-the latest version so you do not violate [Rule 17](rules.html#rule17).
+the latest version so you do not violate [Rule 17](next/rules.html#rule17).
See the
FAQ on "[obtaining the latest mkiocccentry tools](faq.html#obtaining_mkiocccentry)",
the