mkiocccentry tool?See the markdown syntax guide. See also CommonMark Spec.
+mkiocccentry tool?As the mkiocccentry toolkit is +crucial in the contest, both for submitters and the judges, if you find a bug +(or you think you find a bug) we would be grateful if you were to report it at +the mkiocccentry issues +page.
+When opening an issue for what you think is a bug, PLEASE use the ‘Bug report’ +option +and PLEASE state in the title what tool you think has a bug.
+When reporting a bug, PLEASE make sure to run the bug_report.sh script.
+This is extremely helpful and without it it makes it much harder to determine
+the problem (at least in some cases :-) ). Describing the problem in as much
+detail as you can and attaching any relevant screenshots, other files (in
+addition to the bug report log file) and so on will also be very helpful.
To run the bug_report.sh script, switch to the mkiocccentry directory and
+then run:
./bug_report.shLet it do its thing and when it’s done it will tell you the name of the log +file. If it does not find a problem but you think there is a problem, please +still do feel free to report it and do make sure you attach the log nonetheless. +If it does find problems, it will give you a summary of the problems and when +you attach the log file we will see those too.
While you may put in as much or as little as you wish into your entry’s +
First, PLEASE read the IOCCC markdown guidelines.
+Next, while you may put in as much or as little as you wish into your entry’s
remarks.md file, we do have few important suggestions:
We recommend that you explain how to use your entry. Explain the command line (if any command line options and arguments are used) @@ -1125,7 +1153,6 @@ rounds; we look at the author name only if an entry wins. See the guidelines if this is not clear!
If you downloaded 1984/mullender/1984_mullender.tar.bz2, for instance, you might
then do:
cd 1984/mullender
- make everything
- ./mullender.alt cd 1984/mullender
+ make everything
+ ./mullender.altto compile all versions and then run the alternate version (if you have
a PDP-11 or VAX-11 you would be able to run the original version). For more help
on compiling entries, see also 3.0 - What Makefile rules are available to
@@ -2003,8 +2030,8 @@ if you switched to each entry’s directory and ran If you download the 1984 tarball, i.e. For more help on compiling entries, see also 3.0 - What Makefile rules are
available to build or clean up IOCCC entries?. Of course in this case you can also switch to individual entries and look at the
diff --git a/faq.md b/faq.md
index be86112e1..e101f4b23 100644
--- a/faq.md
+++ b/faq.md
@@ -10,6 +10,8 @@
- [0.5 - How may I comment or make a suggestion on IOCCC rules, guidelines and tools?](#faq0_5)
- [0.6 - What is the best way to ask a question about the IOCCC rules, guideline and tools?](#faq0_6)
- [0.7 - What are the IOCCC best practices for using markdown?](#faq0_7)
+- [0.8 - How do I report bugs in a `mkiocccentry` tool?](#faq0_8)
+
## Section 1 - [History of the IOCCC](#faq1)
@@ -538,6 +540,42 @@ See also [CommonMark Spec](https://spec.commonmark.org/current/).
+ IMPORTANT: Be SURE to read the IOCCC rules. No feathers stuck in tarball. IMPORTANT: Be sure to read the IOCCC guidelines. make everything
1984/1984.tar.bz2, then you might
extract it and then switch to the directory and compile everything of each
entry: cd 1984
- make everything cd 1984
+ make everythingIOCCC Guidelines version
| These IOCCC guidelines are version 28.3 2024-07-01.| These IOCCC guidelines are version 28.4 2024-07-02.Change marks
@@ -603,28 +603,34 @@ tool will also do a rudimentary check on the Makefile and run other
well. You can override warnings but doing so puts you at risk of violating
rules.
| On the other hand, some issues are an error and the xz compressed
-tarball will not be formed. For instance, if chkentry(1) fails to validate the
-.auth.json or .info.json JSON files that mkiocccentry(1) creates, it is an error and
-possibly a bug that you should report at the mkiocccentry issues
-page.chkentry(1) fails to validate
+the .auth.json or .info.json JSON files
+that mkiocccentry(1) creates, it is an error and possibly a bug that you
+should report at the mkiocccentry issues
+page. PLEASE run the
+bug_report.sh script to help us out here! See the the FAQ about reporting
+bugs in the mkiocccentry repo.
| Assuming that chkentry(1) passes for both .auth.json and
.info.json then the tarball will be formed and then txzchk(1) will be
-executed. In this case, there should be no problems as mkiocccentry(1) should
+executed. In this case, there should be no problems as mkiocccentry(1) would
NOT form a tarball if there are any issues.| txzchk(1) performs a wide number of sanity checks on the xz
-compressed tarball and if any issues (feathers :-) ) are found then it is very
-possibly a bug in one of the tools and you should report it at the mkiocccentry
-issues page.feathers :-) ) are found and if you used
+mkiocccentry(1), then it is very possibly a bug in one of the tools and you
+should report it at the mkiocccentry issues
+page. PLEASE run the
+bug_report.sh script to help us out here! See the FAQ about reporting bugs
+in the mkiocccentry repo.
| As part of its sanity checks, txzchk(1) will run fnamchk(1) on the
filename to verify that the name is valid. If this test does not pass, then it
is flagged by txzchk(1) but it is not an error if you wish to ignore it.
Ignoring this, however, risks violating Rule 17 which is a
-big risk.| txzchk(1) will show the contents of the tarball which is how the
-mkiocccentry(1) shows you the tarball contents for you to review.mkiocccentry(1) would prevent this from happening.
+| By default, txzchk(1) will show the contents of the tarball which is
+how the mkiocccentry(1) shows you the tarball contents for you to review.| 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 again. To write to answers.txt try:answers.txt try:
./mkiocccentry -a answers.txt ...| Alternatively, if you wish to overwrite a file, you can use the -A
flag with the same option argument. Be careful that you do not accidentally
@@ -641,7 +647,7 @@ contents of the tarball and the words:| If you give the option -q it will not report anything unless there
-are certain error conditions, for instance fnamchk(1) reports there is a
+are certain error conditions, for instance if fnamchk(1) reports there is a
problem with the filename; if txzchk(1) exits 0 then there are no problems
detected.| If you wish to run fnamchk(1) directly you can do so like:chkentry(1). chkentry(1) accepts more than
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:
-
+ ./chkentry test_work # tests entry directory test_work
+
- # test entry directory test_work:
+ ./chkentry test_work
- ./chkentry .info.json . # run checks on .info.json file
+ # run checks on .info.json:
+ ./chkentry .info.json .
- ./chkentry . .auth.json # run checks on .auth.json
+ # run checks on .auth.json:
+ ./chkentry . .auth.json
- ./chkentry .info.json .auth.json # run check on both files| If there is a JSON error detected by jparse(8), then it is an error
-and chkentry(1) will report this. If an issue is found in one or both of the
-JSON files it will also report this.| 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. Even if everything checks out OK you should not expect that everything
-IS OK.| If there is a JSON issue detected
+by jparse(8), then there is a JSON
+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 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.| 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. But even if
+everything checks out OK you should not expect that everything IS OK.| As you can see, the use of mkiocccentry(1) is HIGHLY RECOMMENDED.| We recommend that you use the
example Makefile
diff --git a/next/guidelines.md b/next/guidelines.md
index bdaeeea0e..da2210de7 100644
--- a/next/guidelines.md
+++ b/next/guidelines.md
@@ -43,7 +43,7 @@ writing by [contacting the judges](../contact.html).
## IOCCC Guidelines version
IOCCC Rules version
| These IOCCC rules are version 28.3 2024-07-01.| These IOCCC rules are version 28.4 2024-07-02.Change marks
@@ -683,13 +683,13 @@ the following files:
.info.json.auth.json| The .info.json must be valid JSON and pass the chkentry(1) test.| The .auth.json must be valid JSON and pass the chkentry(1) test.| The .info.json must be valid JSON and pass the chkentry(1) tests.| The .auth.json must be valid JSON and pass the chkentry(1) tests.| You submission may have additional files, however the filenames of those additional files MUST:
-
+^[0-9A-Za-z][0-9A-Za-z._+-]*$| * Be less than 100 characters in length
+| * Match the regular expression: ^[0-9A-Za-z][0-9A-Za-z._+-]*$| The mkiocccentry(1) tool will not package any files that do not meet
+those requirements.| The Makefile must be a non-empty file in GNU
Makefile form. See the
Makefile.example,
@@ -727,20 +727,34 @@ by the mkiocccentry(1) tool):.info.json which contains information about the entry.| The txzchk(1) tool will verify these for you and the chkentry(1)
-tool will do additional checks on the contents of the .auth.json and
-.info.json files.| The txzchk(1) tool will verify these (and other things) for you and
+the chkentry(1) tool will do additional checks on the contents of the
+.auth.json and .info.json files.| The tarball filename MUST pass fnamchk(1); the tool txzchk(1)
-which is run by mkiocccentry(1) before packaging your tarball will run
-fnamchk(1).fnamchk(1) as part of its algorithm. If you use mkiocccentry(1)
+there should be no problem but if you were to package things manually it is
+possible there could be a problem.
+| The fnamchk(1), which txzchk(1) executes, will verify that the
+filename is correct.| These checks MUST PASS.| Where Rule 17 and the tools from the latest
release of the mkiocccentry repo
conflict, the IOCCC Judges will use their best judgment which
is likely to favor mkiocccentry repo code.| This means you MAKE SURE that you use mkiocccentry(1) to
+| This means you should MAKE SURE that you use mkiocccentry(1) to
package your submission; mkiocccentry(1) will run the above mentioned tools
-before creating the tarball.txzchk(1) on it.
+| These tools will link in the jparse(8) library and chkentry(1)
+actually uses the parser to validate the
+JSON.| If you run into a problem with one or more of these tools, PLEASE
+report it at the mkiocccentry issues
+page, making sure to run
+bug_report.sh. See the guidelines for help here and also
+read the FAQ about reporting bugs in the mkiocccentry
+repo.| To state the obvious: submissions that violate Rule 17 will be rejected,
so be sure to use the latest release of the mkiocccentry repo,
to form and test your submission’s xz compressed tarball.
+**`|`** * Match the regular expression: `^[0-9A-Za-z][0-9A-Za-z._+-]*$`
+
+**`|`** The `mkiocccentry(1)` tool will not package any files that do not meet
+those requirements.
**`|`** The `Makefile` must be a non-empty file in [GNU
Makefile](https://www.gnu.org/software/make/manual/make.html) form. See the
@@ -496,13 +499,17 @@ by the `mkiocccentry(1)` tool):
only be looked at if the submission wins).
* `.info.json` which contains information about the entry.
-**`|`** The `txzchk(1)` tool will verify these for you and the `chkentry(1)`
-tool will do additional checks on the contents of the `.auth.json` and
-`.info.json` files.
+**`|`** The `txzchk(1)` tool will verify these (and other things) for you and
+the `chkentry(1)` tool will do additional checks on the contents of the
+`.auth.json` and `.info.json` files.
**`|`** The tarball filename **MUST** pass `fnamchk(1)`; the tool `txzchk(1)`
-which is run by `mkiocccentry(1)` **before packaging your tarball** will run
-`fnamchk(1)`.
+will run `fnamchk(1)` as part of its algorithm. If you use `mkiocccentry(1)`
+there should be no problem but if you were to package things manually it is
+possible there could be a problem.
+
+**`|`** The `fnamchk(1)`, which `txzchk(1)` executes, will verify that the
+filename is correct.
**`|`** These checks **MUST PASS**.
@@ -511,9 +518,22 @@ release of the [mkiocccentry repo](https://github.com/ioccc-src/mkiocccentry)
conflict, the [IOCCC Judges](../judges.html) will use their best judgment which
is likely to favor [mkiocccentry repo](https://github.com/ioccc-src/mkiocccentry) code.
-**`|`** This means you **MAKE SURE** that you use `mkiocccentry(1)` to
+**`|`** This means you should **MAKE SURE** that you use `mkiocccentry(1)` to
package your submission; `mkiocccentry(1)` will run the above mentioned tools
-**before** creating the tarball.
+(that do not act on the tarball) **before** creating the tarball and after the
+tarball is created it will then verify that the tarball is okay by running
+`txzchk(1)` on it.
+
+**`|`** These tools will link in the `jparse(8)` library and `chkentry(1)`
+actually uses the parser to validate the
+[JSON](https://www.json.org/json-en.html).
+
+**`|`** If you run into a problem with one or more of these tools, **PLEASE**
+report it at the [mkiocccentry issues
+page](https://github.com/ioccc-src/mkiocccentry/issues), **making sure to run
+`bug_report.sh`**. See the [guidelines](guidelines.html) for help here and also
+read [the FAQ about reporting bugs in the mkiocccentry
+repo](../faq.html#mkiocccentry_bugs).
**`|`** To state the obvious: submissions that violate [Rule 17](#rule17) **will be rejected**,
so be sure to use the latest release of the [mkiocccentry repo](https://github.com/ioccc-src/mkiocccentry),