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. In cases where the above summary and the algorithm implemented by
the IOCCC size tool source code conflict, the algorithm implemented
by the IOCCC size tool source code is preferred by the judges. Take note that this secondary limit imposed by the IOCCC size tool
obviates some of the need to Unless you are cramped for space, or unless you are entering the
‘Best one liner’ category, we suggest that you format your program
in a more creative way than simply forming excessively long lines. We prefer programs that are portable across a wide variety of Unix-like
operating systems (e.g., Linux, GNU Hurd, BSD, Unix, etc.). You are in a maze of twisty guidelines, all different. There are at least zero judges who think that
Fideism has little
or nothing to do with the IOCCC judging process. You very well might not be completely be prohibited from failing to not You very well might not be completely be prohibited from failing to not partly
+misunderstand this particular guideline, but of course, we could not possibly
+comment! :-) Nevertheless, you are neither prohibited, nor are you fully
+required to determine that this or the previous sentence is either false and/or
+perhaps misleading. Therefore, it might be wise for you to not fail to consider
+to not do so, accordingly. Thank you very much. Any complaints about the above guideline could be addressed to the
Speaker of the House of Commons, or to the speaker of your national
@@ -1247,10 +1252,9 @@ This is one of the reasons why the IOCCC rules and
Entries are judged by Leonid A. Broukhis and Landon Curt Noll. Each submission submitted is given a random id number and subdirectory. The
-submission files including, but not limited to 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),
From 902d6a3f25391790a40ed40414f38069b53fd2a9 Mon Sep 17 00:00:00 2001
From: Cody Boone Ferguson <53008573+xexyl@users.noreply.github.com>
Date: Tue, 2 Jul 2024 05:54:01 -0700
Subject: [PATCH 2/2] Format fixes in guidelines
With the exception of some code blocks they now look much nicer on a
smaller screen.
---
next/guidelines.html | 42 +++++++++++++++++++++++-------------------
next/guidelines.md | 43 +++++++++++++++++++++++--------------------
2 files changed, 46 insertions(+), 39 deletions(-)
diff --git a/next/guidelines.html b/next/guidelines.html
index 0f18a8dc2..9cd0103de 100644
--- a/next/guidelines.html
+++ b/next/guidelines.html
@@ -459,7 +459,7 @@ you are using the correct versions of these items before using the
IOCCC submission URL.
| The Rule 2a size has increased from 4096 to 4993 bytes.| The Rule 2b size has increased from 2053 to 2503 bytes.| The default way to compile submissions is now -std=gnu17 -O3 -g3 -Wall -Wextra -pedantic. See below for more details about the example Makefile
+| The new default way to compile submissions: -std=gnu17 -O3 -g3 -Wall -Wextra -pedantic. See below for more details about the example Makefile
for more help.| Submissions are in the form of a single xz compressed tarball.| To assist in the formation of the xz compressed tarball for submission, use the
@@ -565,11 +565,13 @@ ASCII formfeed, and ASCII carriage return.| There are at least 2 other reasons for selecting 2503 as the 2nd limit
-| besides the fact that 2503 is a prime. These reasons
-| may be searched for and discovered if you are “Curios!” about 2503. :-)
-| Moreover, 2053 was the number of the kernel disk pack of one of the
-| judge’s BESM-6, and 2503 is a decimal anagram of 2053.| There are at least 2 other reasons for selecting
+| 2503 as the 2nd limit besides the fact that 2503
+| is a prime. These reasons may be searched for
+| and discovered if you are “Curios!” about 2503. :-)
+| Moreover, 2053 was the number of the kernel disk
+| pack of one of the judge’s BESM-6, and 2503 is a
+| decimal anagram of 2053.#define C reserved words in an effort
to get around the size limits of Rule 2.-h option. However, to help simplify
matters, we give you a brief overview below.
| The synopsis of the mkiocccentry(1) tool is:
+ ./mkiocccentry [options] work_dir prog.c Makefile remarks.md [file ...] ./mkiocccentry [options] work_dir prog.c \
+ Makefile remarks.md [file ...]| where the work_dir is a directory that is used to form the
xz compressed tarball that txzchk(1) validates, prog.c is your submission
source code, Makefile is your Makefile, remarks.md is your remarks and
@@ -671,7 +674,7 @@ If you pass a single argument, it is expected to be a directory that has both
# run checks on .auth.json:
./chkentry . .auth.json
- # run checks on both .info.json and .auth.json:
+ # run checks on .info.json and .auth.json:
./chkentry .info.json .auth.json
| If there is a JSON issue detected
by jparse(8), then there is a JSON
@@ -870,7 +873,7 @@ interfaces to their compilers, once one learns how to invoke a shell.
+ #include <windows.h> /* we DISLIKE this include */ #include <windows.h> /* we DISLIKE this */
| You are well advised to submit entries that conform to the Single UNIX Specification Version 4.| To quote the IOCCC judges:
-
-partly misunderstand this particular guideline, but of course, we could
-not possibly comment! :-) Nevertheless, you are neither prohibited, nor are
-you fully required to determine that this or the previous sentence is either false
-and/or perhaps misleading. Therefore, it might be wise for you to not fail to
-consider to not do so, accordingly. Thank you very much.prog.c, Makefile (that we
-form from your submitted Makefile and any additional “how to build”
-information you provide), as well as any data files that you submit are all
-placed under their own directory and stored and judged from this directory.prog.c, Makefile,
+remarks.md as well as any data files that you submit, are all placed under
+their own directory and stored and judged from this directory.
Any information about the authors is not read by the judges until
the judging process is complete, and then only from entries that have
won an award. Because we do not read this information for entries that
diff --git a/next/guidelines.md b/next/guidelines.md
index da2210de7..2fb3c0631 100644
--- a/next/guidelines.md
+++ b/next/guidelines.md
@@ -109,7 +109,7 @@ IOCCC submission URL.
**`|`** The [Rule 2b](rules.html#rule2b) size has **increased from 2053 to 2503** bytes.
-**`|`** The default way to compile submissions is now `-std=gnu17 -O3 -g3
+**`|`** The new default way to compile submissions: `-std=gnu17 -O3 -g3
-Wall -Wextra -pedantic`. See below for more details about the example Makefile
for more help.
@@ -249,11 +249,13 @@ In cases where the above summary and the algorithm implemented by
the IOCCC size tool source code conflict, the algorithm implemented
by the IOCCC size tool source code is preferred by the judges.
-**`|`** There are at least 2 other reasons for selecting 2503 as the 2nd limit
-**`|`** besides the fact that 2503 is a prime. These reasons
-**`|`** may be searched for and discovered if you are ["Curios!" about 2503](https://t5k.org/curios/page.php/2503.html). :-)
-**`|`** Moreover, 2053 was the number of the kernel disk pack of one of the
-**`|`** judge's BESM-6, and 2503 is a decimal anagram of 2053.
+**`|`** There are at least 2 other reasons for selecting
+**`|`** 2503 as the 2nd limit besides the fact that 2503
+**`|`** is a prime. These reasons may be searched for
+**`|`** and discovered if you are ["Curios!" about 2503](https://t5k.org/curios/page.php/2503.html). :-)
+**`|`** Moreover, 2053 was the number of the kernel disk
+**`|`** pack of one of the judge's BESM-6, and 2503 is a
+**`|`** decimal anagram of 2053.
Take note that this secondary limit imposed by the IOCCC size tool
obviates some of the need to `#define` C reserved words in an effort
@@ -283,7 +285,8 @@ matters, we give you a brief overview below.
**`|`** The synopsis of the `mkiocccentry(1)` tool is:
```
- ./mkiocccentry [options] work_dir prog.c Makefile remarks.md [file ...]
+ ./mkiocccentry [options] work_dir prog.c \
+ Makefile remarks.md [file ...]
```
**`|`** where the `work_dir` is a directory that is used to form the
@@ -397,7 +400,7 @@ If you pass a single argument, it is expected to be a directory that has both
# run checks on .auth.json:
./chkentry . .auth.json
- # run checks on both .info.json and .auth.json:
+ # run checks on .info.json and .auth.json:
./chkentry .info.json .auth.json
```
@@ -687,8 +690,9 @@ Specification](https://en.wikipedia.org/wiki/Single_UNIX_Specification)
environment. Therefore do not assume the system has a
[windows.h](https://en.wikipedia.org/wiki/Windows.h) include file:
+
```
- #include
-> partly misunderstand this particular _guideline_, but of course, we could
-> not possibly comment! :-) Nevertheless, you are neither prohibited, nor are
-> you fully required to determine that this or the previous sentence is either false
-> and/or perhaps misleading. Therefore, it might be wise for you to not fail to
-> consider to not do so, accordingly. Thank you very much.
+> You very well might not be completely be prohibited from failing to not partly
+misunderstand this particular _guideline_, but of course, we could not possibly
+comment! :-) Nevertheless, you are neither prohibited, nor are you fully
+required to determine that this or the previous sentence is either false and/or
+perhaps misleading. Therefore, it might be wise for you to not fail to consider
+to not do so, accordingly. Thank you very much.
Any complaints about the above _guideline_ could be addressed to the
Speaker of the House of Commons, or to the speaker of your national
@@ -1169,10 +1173,9 @@ This is one of the reasons why the [IOCCC rules](rules.html) and
Entries are judged by Leonid A. Broukhis and Landon Curt Noll.
Each submission submitted is given a random id number and subdirectory. The
-submission files including, but not limited to `prog.c`, `Makefile` (that we
-form from your submitted `Makefile` and any additional "**how to build**"
-information you provide), as well as any data files that you submit are all
-placed under their own directory and stored and judged from this directory.
+submission files including, but not limited to `prog.c`, `Makefile`,
+`remarks.md` as well as any data files that you submit, are all placed under
+their own directory and stored and judged from this directory.
Any information about the authors is not read by the judges until
the judging process is complete, and then only from entries that have