From 52deabd02ada8d693cb2121386004c00dcd84707 Mon Sep 17 00:00:00 2001
From: Cody Boone Ferguson <53008573+xexyl@users.noreply.github.com>
Date: Sun, 2 Feb 2025 10:16:35 -0800
Subject: [PATCH 01/16] Add remarks.example.md, update FAQ/guidelines
The next/remarks.example.md filename is kind of a misnomer but it was
named this way to match Makefile.example. It has brief instructions
along with a link to the FAQ about what one should put in their
remarks.md file (and the FAQ links to the new file as a starting point
as it has instructions).
The markdown guidelines were updated to note that if one does use
sections in remarks.md file they should start out at heading level 3
(###) and for each subsection increment it by one (up to level 6).
---
faq.html | 22 +++++++++++++------
faq.md | 24 +++++++++++++++------
markdown.html | 30 +++++++++++++++++++++-----
markdown.md | 47 +++++++++++++++++++++++++++++++++++------
next/remarks.example.md | 27 +++++++++++++++++++++++
5 files changed, 127 insertions(+), 23 deletions(-)
create mode 100644 next/remarks.example.md
diff --git a/faq.html b/faq.html
index 6af4dd737..581d05cd9 100644
--- a/faq.html
+++ b/faq.html
@@ -425,7 +425,7 @@
IOCCC FAQ Table of Contents
-This is FAQ version 28.2.2 2025-01-30.
+This is FAQ version 28.2.3 2025-02-02.
- Q 0.0: How can I enter the IOCCC?
@@ -628,10 +628,12 @@ code, your Makefile, your remarks, any other data files you wish to provide (up
to a maximum, including the mandatory files, defined in
limit_ioccc.h
as MAX_FILE_COUNT) and other information about your submission,
-information about the author (or authors), and then it runs a lot of tests before (if
-all is OK) forming your tarball. After this is done it will additionally run the
-txzchk(1) tool (which runs the fnamchk(1) tool) on the submission tarball.
-The tool chkentry(1) will also be run, before creating the tarball. See the
+information about the author (or authors), and then it runs a lot of tests.
+If everything is OK, it will write the required .auth.json and .info.json
+files, checking each with chkentry(1) and then, if all is OK, it will create
+the tarball. After the tarball is formed, it will run txzchk(1) on it, which
+runs fnamchk(1). If all is OK, your submission tarball should be good to go.
+Please see
FAQ on “txzchk”,
the
FAQ on “fnamchk”
@@ -797,7 +799,15 @@ the one linked to above.
-First, PLEASE read the IOCCC markdown guidelines.
+PLEASE look at the example remarks.md to give you a better idea of how
+it should be formed:
+
+Read the instructions in the file and PLEASE pay especial attention to the
+instructions, including the IOCCC markdown guidelines. You will
+observe that it links back to this FAQ as to what you should or should not say.
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
diff --git a/faq.md b/faq.md
index f12383137..3434e9034 100644
--- a/faq.md
+++ b/faq.md
@@ -1,6 +1,6 @@
# IOCCC FAQ Table of Contents
-This is FAQ version **28.2.2 2025-01-30**.
+This is FAQ version **28.2.3 2025-02-02**.
## 0. [Entering the IOCCC: the bare minimum you need to know](#enter_questions)
@@ -217,10 +217,14 @@ code, your Makefile, your remarks, any other data files you wish to provide (up
to a maximum, including the mandatory files, defined in
[limit_ioccc.h](https://github.com/ioccc-src/mkiocccentry/blob/master/soup/limit_ioccc.h)
as `MAX_FILE_COUNT`) and other information about your submission,
-information about the author (or authors), and then it runs a lot of tests before (if
-all is OK) forming your tarball. After this is done it will additionally run the
-`txzchk(1)` tool (which runs the `fnamchk(1)` tool) on the submission tarball.
-The tool `chkentry(1)` will also be run, before creating the tarball. See the
+information about the author (or authors), and then it runs a lot of tests.
+
+If everything is OK, it will write the required `.auth.json` and `.info.json`
+files, checking each with `chkentry(1)` and then, if all is OK, it will create
+the tarball. After the tarball is formed, it will run `txzchk(1)` on it, which
+runs `fnamchk(1)`. If all is OK, your submission tarball should be good to go.
+
+Please see
FAQ on "[txzchk](#txzchk)",
the
FAQ on "[fnamchk](#fnamchk)"
@@ -431,7 +435,15 @@ Jump to: [top](#)
-First, **PLEASE** read the [IOCCC markdown guidelines](markdown.html).
+**PLEASE** look at the example remarks.md to give you a better idea of how
+it should be formed:
+
+- [view example remarks.md](%%REPO_URL%%/next/remarks.example.md)
+- [remarks.md example](next/remarks.example.md)
+
+Read the instructions in the file and **PLEASE** pay especial attention to the
+instructions, including the [IOCCC markdown guidelines](markdown.html). You will
+observe that it links back to this FAQ as to what you should or should not say.
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:
diff --git a/markdown.html b/markdown.html
index 6f2d54bb7..aa9b7bf05 100644
--- a/markdown.html
+++ b/markdown.html
@@ -431,13 +431,13 @@
IOCCC Markdown guidelines version
-These IOCCC markdown guidelines are version 28.1 2024-12-27.
+These IOCCC markdown guidelines are version 28.1 2025-02-02.
IMPORTANT: Be sure to read the IOCCC rules and IOCCC
guidelines.
Jump to: top
-
-
IOCCC Markdown guidelines
+
+
IOCCC Markdown Guidelines Introduction
The IOCCC makes extensive use of markdown.
For example, when submitting to the IOCCC
@@ -454,9 +454,29 @@ FAQ on “remarks.md submission file”.
Nevertheless, the IOCCC does have certain practices that we ask authors to follow.
Some of these relate to use of markdown directly and others relate to injecting HTML
into the markdown file.
-
In particular there are things we ask people to please NOT use in
-markdown files for the IOCCC:
Jump to: top
+
+
+
+
IF (it is not required) you do use sections in your remarks.md file (this does
+not apply to other markdown files), PLEASE start at level three:
+
# Foo <=== no thank you
+ ## Foo <=== no thank you
+
Instead, start sections with 3 #s:
+
### Section 0
+
For each subsection of the current section, add another #, up to 6, going back
+to 3 for new sections. For instance:
+
### Section 0
+ ...
+ #### First subsection of section 0
+ ...
+ ##### Second subsection of section 0
+ ...
+ ###### Third subsection of section 0
+ ...
+ ### Section 1
+ ...
+ Etc.
Please do NOT use the name attributes in HTML <a>...</a> hyperlink elements
diff --git a/markdown.md b/markdown.md
index 480e52738..b823d434e 100644
--- a/markdown.md
+++ b/markdown.md
@@ -7,7 +7,7 @@
-These [IOCCC markdown guidelines](markdown.html) are version **28.1 2024-12-27**.
+These [IOCCC markdown guidelines](markdown.html) are version **28.1 2025-02-02**.
**IMPORTANT**: Be sure to read the [IOCCC rules](next/rules.html) and [IOCCC
@@ -16,8 +16,8 @@ guidelines](next/guidelines.html).
Jump to: [top](#)
-
-## IOCCC Markdown guidelines
+
+## IOCCC Markdown Guidelines Introduction
The IOCCC makes extensive use of [markdown](https://daringfireball.net/projects/markdown/).
@@ -38,11 +38,46 @@ Nevertheless, the IOCCC does have certain practices that we ask authors to follo
Some of these relate to use of markdown directly and others relate to injecting HTML
into the markdown file.
-In particular there are things we ask people to please **NOT** use in
-markdown files for the IOCCC:
-
Jump to: [top](#)
+
+## Please DO start `remarks.md` sections at level 3 (`###`), increasing for subsections up to 6 (`######`)
+
+
+IF (it is not required) you do use sections in your `remarks.md` file (this does
+not apply to other markdown files), **PLEASE** start at level three:
+
+```
+ # Foo <=== no thank you
+ ## Foo <=== no thank you
+```
+
+Instead, start sections with 3 `#`s:
+
+
+```
+ ### Section 0
+```
+
+For each subsection of the current section, add another `#`, up to 6, going back
+to 3 for new sections. For instance:
+
+
+```
+ ### Section 0
+ ...
+ #### First subsection of section 0
+ ...
+ ##### Second subsection of section 0
+ ...
+ ###### Third subsection of section 0
+ ...
+ ### Section 1
+ ...
+ Etc.
+```
+
+
## Please do NOT use the `name` attributes in HTML `
...` hyperlink elements
diff --git a/next/remarks.example.md b/next/remarks.example.md
new file mode 100644
index 000000000..dbec0609b
--- /dev/null
+++ b/next/remarks.example.md
@@ -0,0 +1,27 @@
+# Instructions
+
+0. Create an empty file `remarks.md` in your submission directory
+(alternatively after reading this file, delete everything in it and rename it
+`remarks.md`).
+
+1. For help with markdown format please see this [helpful
+guide](https://www.markdownguide.org/basic-syntax/).
+
+2. Please see and follow the [IOCCC markdown
+guidelines](https://www.ioccc.org/markdown.html). Doing this helps the judges
+integrate your remarks into a `README.md`, should you win.
+
+3. After reading this file, write your remarks in your `remarks.md` file (as
+mentioned in step 0).
+
+4. When packaging your submission with `mkiocccentry(1)`, make sure that the
+`remarks.md` is in the `topdir`.
+
+**IMPORTANT NOTE**: make **SURE** you read the IOCCC
+[Rules](https://www.ioccc.org/next/rules.html) and
+[Guidelines](https://www.ioccc.org/next/guidelines.html)!
+
+# What should you say?
+
+Please see the
+FAQ on "[what to put in your remarks](../faq.html#remarks)".
From 25dc2446bdc3ca4a8973e0f1ed7990b28dd378a7 Mon Sep 17 00:00:00 2001
From: Cody Boone Ferguson <53008573+xexyl@users.noreply.github.com>
Date: Sun, 2 Feb 2025 10:19:16 -0800
Subject: [PATCH 02/16] Typo fix in SECURITY.html
---
SECURITY.html | 4 ++--
SECURITY.md | 4 ++--
2 files changed, 4 insertions(+), 4 deletions(-)
diff --git a/SECURITY.html b/SECURITY.html
index f6571a453..9998bc3e3 100644
--- a/SECURITY.html
+++ b/SECURITY.html
@@ -450,8 +450,8 @@ interface
instead.
Important Disclaimer
IOCCC code is for educational and entertainment purposes only. We do NOT
-recommend installing any winning IOCCC entry code. Use code found the IOCCC repo
-and in the IOCCC web site at your own risk!
+recommend installing any winning IOCCC entry code. Use code found in the IOCCC repo
+and in the IOCCC website
at your own risk!
The IOCCC and the IOCCC judges DISCLAIM ALL
WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF
MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THEY BE LIABLE FOR ANY SPECIAL,
diff --git a/SECURITY.md b/SECURITY.md
index efa6febeb..0e605aff8 100644
--- a/SECURITY.md
+++ b/SECURITY.md
@@ -35,8 +35,8 @@ instead.
# Important Disclaimer
IOCCC code is for **educational and entertainment purposes only**. We do **NOT**
-recommend installing any winning IOCCC entry code. Use code found the IOCCC repo
-and in the IOCCC web site **at your own risk!**
+recommend installing any winning IOCCC entry code. Use code found in the IOCCC repo
+and in the IOCCC website **at your own risk!**
The [IOCCC](index.html) and the [IOCCC judges](judges.html) DISCLAIM ALL
WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF
From c533706ded82c5c4966a2d05d93c1b7f1396b19e Mon Sep 17 00:00:00 2001
From: Cody Boone Ferguson <53008573+xexyl@users.noreply.github.com>
Date: Sun, 2 Feb 2025 10:21:01 -0800
Subject: [PATCH 03/16] Update mkiocccentry synopsis in quick-start.html
The FAQ and guidelines need to be improved in this regard but the quick
start guide is now consistent with the syntax found in mkiocccentry
(which is noted in the FAQ).
---
quick-start.html | 28 ++++++++++++++++------------
quick-start.md | 31 +++++++++++++++++--------------
2 files changed, 33 insertions(+), 26 deletions(-)
diff --git a/quick-start.html b/quick-start.html
index 77341230e..2b73ff130 100644
--- a/quick-start.html
+++ b/quick-start.html
@@ -512,21 +512,25 @@ the
FAQ on”how to use mkiocccentry“)
and the mkiocccentry section in the
guidelines.
-
mkiocccentry work_dir prog.c Makefile remarks.md [file ...]
+
mkiocccentry [options] workdir topdir
where:
-work_dir
-directory where the entry directory and tarball are formed
workdir
+directory where the submission directory and tarball are formed
topdir
+directory where your files to be packaged are in
+
Three files are required to exist in topdir:
+
prog.c
-path to the C source for your entry
path to the C source for your submission
Makefile
-Makefile to build (make all) and cleanup (make clean & make clobber)
Makefile to build (make all) and cleanup (make clean & make clobber) as well
+as the other required rules
remarks.md
Remarks about your entry in markdown format: see the
-FAQ on “remarks.md”
+FAQ on “remarks.md”
for more info.
[file …]
-Optional extra data files to include with your entry
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
@@ -536,10 +540,10 @@ 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.
-
If the mkiocccentry tool indicates that there is a problem with your entry,
-especially if it identifies a Rule 2, or any other
-rule, related problem, you are strongly encouraged to revise and correct
-your entry and then re-run the mkiocccentry tool.
+
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
+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!
diff --git a/quick-start.md b/quick-start.md
index ad86fb58f..7e3662627 100644
--- a/quick-start.md
+++ b/quick-start.md
@@ -124,33 +124,36 @@ guidelines](next/guidelines.html#mkiocccentry).
```
- mkiocccentry work_dir prog.c Makefile remarks.md [file ...]
+ mkiocccentry [options] workdir topdir
```
where:
-* `work_dir`
+* `workdir`
- directory where the entry directory and tarball are formed
+ directory where the submission directory and tarball are formed
+
+* `topdir`
+
+ directory where your files to be packaged are in
+
+Three files are required to exist in `topdir`:
* `prog.c`
- path to the C source for your entry
+ path to the C source for your submission
* `Makefile`
- Makefile to build (make all) and cleanup (make clean & make clobber)
+ Makefile to build (make all) and cleanup (make clean & make clobber) as well
+ as the other required rules
* `remarks.md`
Remarks about your entry in markdown format: see the
- FAQ on "[remarks.md](#remarks_md)"
+ FAQ on "[remarks.md](faq.html#remarks_md)"
for more info.
-* [file ...]
-
- Optional extra data files to include with your entry
-
**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
@@ -161,10 +164,10 @@ submission's directory. See the
FAQ on "**[installing mkiocccentry](https://github.com/ioccc-src/mkiocccentry/blob/master/FAQ.md#install)**"
at the mkiocccentry repo.
-If the `mkiocccentry` tool indicates that there is a problem with your entry,
-especially if it identifies a [Rule 2](next/rules.html#rule2), or any other
-rule, related problem, you are **strongly** encouraged to revise and correct
-your entry and then re-run the `mkiocccentry` tool.
+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
+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.
From b2777be3fbd53db90089b5b5a2a7a753532b7d2c Mon Sep 17 00:00:00 2001
From: Cody Boone Ferguson <53008573+xexyl@users.noreply.github.com>
Date: Sun, 2 Feb 2025 10:22:58 -0800
Subject: [PATCH 04/16] Typo fixes in contact.html
---
contact.html | 6 +++---
contact.md | 6 +++---
2 files changed, 6 insertions(+), 6 deletions(-)
diff --git a/contact.html b/contact.html
index efa4245b6..06c5f88a9 100644
--- a/contact.html
+++ b/contact.html
@@ -444,11 +444,11 @@ FAQ on “
submitting a pull request”.
If you are trying to:
In general, unless you have a fix, if you want to report something, you should instead first look at the IOCCC
issues to see if the
diff --git a/contact.md b/contact.md
index 555f0396c..d33f36c78 100644
--- a/contact.md
+++ b/contact.md
@@ -20,11 +20,11 @@ FAQ on "[submitting a pull request](faq.html#pull_request)".
If you are trying to:
* **Report a bug in an IOCCC winning entry** - See our
-FAQ on "[report entry bug](faq.html#report_bug)"
+FAQ on "[reporting an entry bug](faq.html#report_bug)"
* **Report an IOCCC website problem** - See our
-FAQ on "[report website problem](faq.html#report_web_problem)"
+FAQ on "[reporting a website problem](faq.html#report_web_problem)"
* **Report a broken or wrong web link** - See our
-FAQ on "[report broken link](faq.html#fix_link)"
+FAQ on "[reporting a broken link](faq.html#fix_link)"
In general, unless you have a fix, if you want to report something, you should instead first look at the [IOCCC
issues](https://github.com/ioccc-src/winner/issues) to see if the
From 5e5dacfb5cadfc6000709c2738897a0ca2fc7ef9 Mon Sep 17 00:00:00 2001
From: Cody Boone Ferguson <53008573+xexyl@users.noreply.github.com>
Date: Sun, 2 Feb 2025 12:37:38 -0800
Subject: [PATCH 05/16] Add to Makefile.example note about +x
Since only try.sh and try.alt.sh files may be executable in submission
tarballs, the Makefile.example now notes this and shows how one can
adjust this if they need to. This is also in the guidelines, rules and
FAQ but those cannot be committed yet.
---
next/Makefile.example | 6 +++++-
1 file changed, 5 insertions(+), 1 deletion(-)
diff --git a/next/Makefile.example b/next/Makefile.example
index 4e5438327..3380c00f8 100644
--- a/next/Makefile.example
+++ b/next/Makefile.example
@@ -153,12 +153,16 @@ ALT_TARGET=
#
DATA=
-
#################
# build the entry
#################
all: data ${TARGET}
+ # NOTE: only try.sh and try.alt.sh scripts will be made executable in
+ # the tarball so if you need any scripts that are executable, make sure
+ # to use ${CHMOD} +x on them like:
+ #
+ # ${CHMOD} +x foo.sh
.PHONY: all data try clean clobber install
From b0f512b86506103b1d9767863c5d666b89bf22d1 Mon Sep 17 00:00:00 2001
From: Cody Boone Ferguson <53008573+xexyl@users.noreply.github.com>
Date: Sun, 2 Feb 2025 12:41:24 -0800
Subject: [PATCH 06/16] chmod +x next/try.sh and next/try.alt.sh
---
next/try.alt.sh | 0
next/try.sh | 0
2 files changed, 0 insertions(+), 0 deletions(-)
mode change 100644 => 100755 next/try.alt.sh
mode change 100644 => 100755 next/try.sh
diff --git a/next/try.alt.sh b/next/try.alt.sh
old mode 100644
new mode 100755
diff --git a/next/try.sh b/next/try.sh
old mode 100644
new mode 100755
From a2e216ec827a2cdf75865af8340a41a4888944b6 Mon Sep 17 00:00:00 2001
From: Cody Boone Ferguson <53008573+xexyl@users.noreply.github.com>
Date: Mon, 3 Feb 2025 07:43:52 -0800
Subject: [PATCH 07/16] Update rules, guidelines and FAQ for file perms
Rule 17 mandates specific file permissions for files/directories in
submission tarballs but the documentation did not state this. More work
might need to be done here but it should be better now.
---
faq.html | 58 +++++++++++-----
faq.md | 66 +++++++++++++-----
next/guidelines.html | 130 +++++++++++++++++-----------------
next/guidelines.md | 162 ++++++++++++++++++++++---------------------
next/rules.html | 45 ++++++++----
next/rules.md | 51 +++++++++-----
6 files changed, 299 insertions(+), 213 deletions(-)
diff --git a/faq.html b/faq.html
index 581d05cd9..eab2d5a95 100644
--- a/faq.html
+++ b/faq.html
@@ -425,7 +425,7 @@
IOCCC FAQ Table of Contents
-
This is FAQ version 28.2.3 2025-02-02.
+
This is FAQ version 28.2.4 2025-02-03.
@@ -799,35 +800,36 @@ the one linked to above.
-
PLEASE look at the example remarks.md to give you a better idea of how
-it should be formed:
+
PLEASE look at the template remarks.md to give you a better idea of how
+it should be formed, as it has some instructions you should follow:
-
Read the instructions in the file and PLEASE pay especial attention to the
-instructions, including the IOCCC markdown guidelines. You will
-observe that it links back to this FAQ as to what you should or should not say.
+
PLEASE pay especial attention to the instructions, including the IOCCC
+markdown guidelines. You will observe that it links back to this
+FAQ as to what you should or should not say.
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
+
We recommend that you explain how to use your submission. Explain the
command line (if any command line options and arguments are used)
and any input or actions if applicable.
-
We highly recommend that you explain why you think your entry is
+
We highly recommend that you explain why you think your submission is
well obfuscated.
For those submissions that win the IOCCC, we often use much of text from the
remarks.md file in the Author’s remarks section of the index.html file.
For this reason, a well written remarks.md file is considered a plus.
While not required, consider adding bit of humor to your remarks.md
-as most people who are not humor impaired, as well as the IOCCC judges
-appreciate the opportunity for a fun read as well as a chuckle or two.
+as most people who are not humor impaired, as well as the IOCCC judges (who
+might or might not be humour impaired :-) ), appreciate the opportunity for a
+fun read as well as a chuckle or two.
What helps:
-- explaining what your entry does
-- how to entice it to do what it is supposed to do
-- what obfuscations are used
-- what are the limitations of your entry in respect of portability and/or input data
-- how it works (if you are really condescending)
+- explaining what your entry does.
+- how to entice it to do what it is supposed to do.
+- what obfuscations are used.
+- what are the limitations of your entry in respect of portability and/or input data.
+- how it works (if you are really condescending).
What does not help:
@@ -839,11 +841,13 @@ it, not very obfuscated entries have a minuscule chance to win (although
in the C code for that matter) - we like to be unbiased during the judging
rounds; we look at the author name only if an entry wins. See the
guidelines AND rules if this is not clear!
-- leaving the remark section empty.
+- leaving the remark section empty (which would also indicate that you did not
+use
mkiocccentry(1), as it requires it to not be of size 0, though if you only
+include whitespace you would still be violating Rule 17).
Jump to: top
-
Q 0.5 What should I do with the try.sh and try.alt.sh scripts?
+Q 0.5: What should I do with the try.sh and try.alt.sh scripts?
If your submission has more than one use, or if you have interesting ways to
invoke your program, perhaps using other commonly installed tools (or tools
@@ -868,6 +872,22 @@ but we do enjoy interesting and creative uses of submissions.
example Makefile that you modify for your submission. See the
FAQ on “
submission Makefiles.
Jump to: top
+
+
Q 0.6: What permissions may my files be and what if I need different permissions?
+
+
As Rule 17 states, files in your submission tarball MUST be
+specific permissions. In particular: directories MUST be drwxr-xr-x (i.e.
+0755), the optional files, try.sh or try.alt.sh, if provided, MUST be
+-r-xr-xr-x (i.e. 0555) and all other files MUST be -r--r--r-- (i.e.
+0444).
+
If you need a file to be executable, say a script, then make sure you do so in
+the appropriate place in your Makefile. See the
+FAQ on “submission Makefile”
+for more details.
+
Do remember that if your submission requires different filenames, then you
+MUST make a COPY of them in your Makefile. See also Rule
+11.
+Jump to:
top
-**PLEASE** look at the example remarks.md to give you a better idea of how
-it should be formed:
+**PLEASE** look at the template remarks.md to give you a better idea of how
+it should be formed, as it has some instructions you should follow:
-- [view example remarks.md](%%REPO_URL%%/next/remarks.example.md)
-- [remarks.md example](next/remarks.example.md)
+- [view template remarks.md](%%REPO_URL%%/next/remarks.example.md)
+- [remarks.md template](next/remarks.example.md)
-Read the instructions in the file and **PLEASE** pay especial attention to the
-instructions, including the [IOCCC markdown guidelines](markdown.html). You will
-observe that it links back to this FAQ as to what you should or should not say.
+**PLEASE** pay especial attention to the instructions, including the [IOCCC
+markdown guidelines](markdown.html). You will observe that it links back to this
+FAQ as to what you should or should not say.
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
+We recommend that you explain how to use your submission. Explain the
command line (if any command line options and arguments are used)
and any input or actions if applicable.
-We highly recommend that you explain why you think your entry is
+We highly recommend that you explain why you think your submission is
well obfuscated.
For those submissions that win the IOCCC, we often use much of text from the
@@ -460,17 +461,18 @@ For those submissions that win the IOCCC, we often use much of text from the
For this reason, a well written `remarks.md` file is considered a plus.
While not required, consider adding bit of humor to your `remarks.md`
-as most people who are not humor impaired, as well as the IOCCC judges
-appreciate the opportunity for a fun read as well as a chuckle or two.
+as most people who are not humor impaired, as well as the IOCCC judges (who
+might or might not be humour impaired :-) ), appreciate the opportunity for a
+fun read as well as a chuckle or two.
#### What helps:
-- explaining what your entry does
-- how to entice it to do what it is supposed to do
-- what obfuscations are used
-- what are the limitations of your entry in respect of portability and/or input data
-- how it works (if you are really condescending)
+- explaining what your entry does.
+- how to entice it to do what it is supposed to do.
+- what obfuscations are used.
+- what are the limitations of your entry in respect of portability and/or input data.
+- how it works (if you are really condescending).
#### What does not help:
@@ -483,13 +485,15 @@ it, not very obfuscated entries have a minuscule chance to win (although
in the C code for that matter) - we like to be unbiased during the judging
rounds; we look at the author name only if an entry wins. See the
[guidelines](next/guidelines.html) **AND** [rules](next/rules.html) if this is not clear!
-- leaving the remark section empty.
+- leaving the remark section empty (which would also indicate that you did not
+use `mkiocccentry(1)`, as it requires it to not be of size 0, though if you only
+include whitespace you would still be violating [Rule 17](next/rules.html#rule17)).
Jump to: [top](#)
-### Q 0.5 What should I do with the `try.sh` and `try.alt.sh` scripts?
+### Q 0.5: What should I do with the `try.sh` and `try.alt.sh` scripts?
If your submission has more than one use, or if you have interesting ways to
@@ -522,6 +526,30 @@ FAQ on "[submission Makefiles](#makefile).
Jump to: [top](#)
+
+
+
+### Q 0.6: What permissions may my files be and what if I need different permissions?
+
+
+As [Rule 17](#rule17) states, files in your submission tarball **MUST** be
+specific permissions. In particular: directories **MUST** be `drwxr-xr-x` (i.e.
+`0755`), the optional files, `try.sh` or `try.alt.sh`, if provided, **MUST** be
+`-r-xr-xr-x` (i.e. `0555`) and all other files **MUST** be `-r--r--r--` (i.e.
+`0444`).
+
+If you need a file to be executable, say a script, then make sure you do so in
+the appropriate place in your Makefile. See the
+FAQ on "[submission Makefile](#makefile)"
+for more details.
+
+Do remember that if your submission requires different filenames, then you
+**MUST** make a **COPY** of them in your `Makefile`. See also [Rule
+11](next/rules.html#rule11).
+
+
+
+Jump to: [top](#)
diff --git a/next/guidelines.html b/next/guidelines.html
index 0903d2bde..c6b6e90cb 100644
--- a/next/guidelines.html
+++ b/next/guidelines.html
@@ -461,7 +461,7 @@ writing by
contacting the judges.
-These IOCCC guidelines are version 28.35 2025-01-30.
+These IOCCC guidelines are version 28.36 2025-02-03.
The markdown form of these guidelines
@@ -613,8 +613,12 @@ before this option will work a second time, just like in normal mode.
to account for the new mkiocccentry repo tools.
Thus, you are STRONGLY advised to use the mkiocccentry(1) tool
as found in the mkiocccentry repo
-to form the file to upload to the submit server. Not
-doing so puts you at a very big risk of violating Rule 17.
+using mkiocccentry(1) the submit server. Uploading
+a tarball not formed by mkiocccentry(1) puts you at a very big risk of
+violating Rule 17, especially as mkiocccentry(1) does a
+great number of things that are required, and it also runs many checks, and if
+any of those checks fail, you are at a very great risk of having your submission
+rejected for violating Rule 17.
See the
@@ -816,66 +820,6 @@ specific terminal brand. Programs that work in a standard xterm
are considered more portable.
Jump to: top
-
-
-The maximum total number of files that may be submitted has changed to 39 files.
-However, of those files, 5 are mandatory (prog.c, Makefile, remarks.md and
-the two JSON files generated by mkiocccentry(1), .info.json and
-.auth.json).
-
-
-Additionally, three of the files, if included, MUST be
-specific file(name)s and in the top level directory, or they will be counted as
-an extra file, not an optional file.
-
-
-In particular, any file that is not prog.c, Makefile, remarks.md,
-try.sh, prog.alt.c or try.alt.sh will be counted as an extra file, and if
-try.sh, prog.alt.c or try.alt.sh are not in the top level directory they
-will also be counted as an extra file. The .info.json and .auth.json files
-are not counted as extra files but are required.
-
-
-In other words, the actual amount of EXTRA files is 31.
-
-
-Of course, if you use the optional filenames without
-the files being our intended use, in order to get past the file limit, that
-would be an abuse of rules. For more details on the optional files, see the
-FAQ on the “try.sh script system”
-and the
-FAQ on “alt code”.
-
-
-If you do need to include more files, you may do so by including as an extra
-file, a tarball. This does NOT have to pass txzchk(1) tests; only the
-submission tarball must pass the txzchk(1) tests. See the txzchk
-section for more details on this important tool.
-
-
-If you DO include a tarball, and the build process or the program extracts
-said tarball(s), the make clobber rule MUST remove them.
-
-
-IMPORTANT REMINDER: make SURE your tarball does NOT reveal who you are!
-The mkiocccentry(1) tool creates a v7 format tarball to prevent this. You can
-do the same like:
-
-
tar --format=v7 -cJf foo.txz directory
-
-See Rule 17 and in particular the part about the maximum
-number of files. If you do not follow these points, you
-are at a great risk of violating Rule 17!
-
-
-NOTE: if you want to include a test-suite that requires a lot of files,
-please suggest this in your remarks.md and if your submission wins it can
-be done. In other words you should not use a tarball for a test-suite unless you
-have a very good reason for this (and if you do, make SURE you specify why
-in your remarks.md).
-
mkiocccentry
Rule 17 (the mkiocccentry(1) rule) states that
@@ -1082,6 +1026,66 @@ Of course, as txzchk does not extract the tarball, it is possible t
manually package your submission tarball, you could still be violating Rule
17.
+
+
+The maximum total number of files that may be submitted has changed to 39 files.
+However, of those files, 5 are mandatory (prog.c, Makefile, remarks.md and
+the two JSON files generated by mkiocccentry(1), .info.json and
+.auth.json).
+
+
+Additionally, three of the files, if included, MUST be
+specific file(name)s and in the top level directory, or they will be counted as
+an extra file, not an optional file.
+
+
+In particular, any file that is not prog.c, Makefile, remarks.md,
+try.sh, prog.alt.c or try.alt.sh will be counted as an extra file, and if
+try.sh, prog.alt.c or try.alt.sh are not in the top level directory they
+will also be counted as an extra file. The .info.json and .auth.json files
+are not counted as extra files but are required.
+
+
+In other words, the actual amount of EXTRA files is 31.
+
+
+Of course, if you use the optional filenames without
+the files being our intended use, in order to get past the file limit, that
+would be an abuse of rules. For more details on the optional files, see the
+FAQ on the “try.sh script system”
+and the
+FAQ on “alt code”.
+
+
+If you do need to include more files, you may do so by including as an extra
+file, a tarball. This does NOT have to pass txzchk(1) tests; only the
+submission tarball must pass the txzchk(1) tests. See the txzchk
+section for more details on this important tool.
+
+
+If you DO include a tarball, and the build process or the program extracts
+said tarball(s), the make clobber rule MUST remove them.
+
+
+IMPORTANT REMINDER: make SURE your tarball does NOT reveal who you are!
+The mkiocccentry(1) tool creates a v7 format tarball to prevent this. You can
+do the same like:
+
+ tar --format=v7 -cJf foo.txz directory
+
+See Rule 17 and in particular the part about the maximum
+number of files. If you do not follow these points, you
+are at a great risk of violating Rule 17!
+
+
+NOTE: if you want to include a test-suite that requires a lot of files,
+please suggest this in your remarks.md and if your submission wins it can
+be done. In other words you should not use a tarball for a test-suite unless you
+have a very good reason for this (and if you do, make SURE you specify why
+in your remarks.md).
+
See also the
FAQ on “txzchk”.
diff --git a/next/guidelines.md b/next/guidelines.md
index d8aa7f03c..27d78b377 100644
--- a/next/guidelines.md
+++ b/next/guidelines.md
@@ -49,7 +49,7 @@ Jump to: [top](#)
-These [IOCCC guidelines](guidelines.html) are version **28.35 2025-01-30**.
+These [IOCCC guidelines](guidelines.html) are version **28.36 2025-02-03**.
@@ -238,8 +238,12 @@ before this option will work a second time, just like in normal mode.
to account for the new [mkiocccentry repo](https://github.com/ioccc-src/mkiocccentry) tools.
Thus, you are **STRONGLY** advised to use the `mkiocccentry(1)` tool
as found in the [mkiocccentry repo](https://github.com/ioccc-src/mkiocccentry)
-to form the file to upload to the [submit server](https://submit.ioccc.org). Not
-doing so puts you at a very big risk of violating [Rule 17](rules.html#rule17).
+using `mkiocccentry(1)` the [submit server](https://submit.ioccc.org). Uploading
+a tarball not formed by `mkiocccentry(1)` puts you at a very big risk of
+violating [Rule 17](rules.html#rule17), especially as `mkiocccentry(1)` does a
+great number of things that are required, and it also runs many checks, and if
+any of those checks fail, you are at a very great risk of having your submission
+rejected for violating [Rule 17](rules.html#rule17).
@@ -485,81 +489,6 @@ are considered more portable.
Jump to: [top](#)
-
-
-
-The maximum total number of files that may be submitted has changed to 39 files.
-However, of those files, 5 are mandatory (`prog.c`, `Makefile`, `remarks.md` and
-the two JSON files generated by `mkiocccentry(1)`, `.info.json` and
-`.auth.json`).
-
-
-
-Additionally, three of the files, if included, **MUST** be
-specific file(name)s and in the top level directory, or they will be counted as
-an extra file, not an optional file.
-
-
-
-In particular, any file that is not `prog.c`, `Makefile`, `remarks.md`,
-`try.sh`, `prog.alt.c` or `try.alt.sh` will be counted as an extra file, and if
-`try.sh`, `prog.alt.c` or `try.alt.sh` are not in the top level directory they
-will also be counted as an extra file. The `.info.json` and `.auth.json` files
-are not counted as extra files but are required.
-
-
-
-In other words, the actual amount of **EXTRA** files is 31.
-
-
-
-Of course, if you use the optional filenames without
-the files being our intended use, in order to get past the file limit, that
-would be an abuse of rules. For more details on the optional files, see the
-FAQ on the "[try.sh script system](../faq.html#try_script)"
-and the
-FAQ on "[alt code](../faq.html#alt_code)".
-
-
-
-If you do need to include more files, you may do so by including as an extra
-file, a tarball. This does **NOT** have to pass `txzchk(1)` tests; only the
-submission tarball must pass the `txzchk(1)` tests. See the [txzchk
-section](#txzchk) for more details on this important tool.
-
-
-
-If you **DO** include a tarball, and the build process or the program extracts
-said tarball(s), the make `clobber` rule **MUST** remove them.
-
-
-
-**IMPORTANT REMINDER**: make **SURE** your tarball does **NOT** reveal who you are!
-The `mkiocccentry(1)` tool creates a v7 format tarball to prevent this. You can
-do the same like:
-
-
-```
- tar --format=v7 -cJf foo.txz directory
-```
-
-
-See [Rule 17](rules.html#rule17) and in particular the part about the [maximum
-number of files](rules.html#max-files). If you do not follow these points, you
-are at a great risk of violating [Rule 17](rules.html#rule17)!
-
-
-
-**NOTE**: if you want to include a test-suite that requires a lot of files,
-please suggest this in your `remarks.md` and if your submission wins it can
-be done. In other words you should not use a tarball for a test-suite unless you
-have a very good reason for this (and if you do, make **SURE** you specify why
-in your `remarks.md`).
-
-
-
# `mkiocccentry`
@@ -818,6 +747,83 @@ manually package your submission tarball, you could still be violating [Rule
17](rules.html#rule17).
+
+
+
+The maximum total number of files that may be submitted has changed to 39 files.
+However, of those files, 5 are mandatory (`prog.c`, `Makefile`, `remarks.md` and
+the two JSON files generated by `mkiocccentry(1)`, `.info.json` and
+`.auth.json`).
+
+
+
+Additionally, three of the files, if included, **MUST** be
+specific file(name)s and in the top level directory, or they will be counted as
+an extra file, not an optional file.
+
+
+
+In particular, any file that is not `prog.c`, `Makefile`, `remarks.md`,
+`try.sh`, `prog.alt.c` or `try.alt.sh` will be counted as an extra file, and if
+`try.sh`, `prog.alt.c` or `try.alt.sh` are not in the top level directory they
+will also be counted as an extra file. The `.info.json` and `.auth.json` files
+are not counted as extra files but are required.
+
+
+
+In other words, the actual amount of **EXTRA** files is 31.
+
+
+
+Of course, if you use the optional filenames without
+the files being our intended use, in order to get past the file limit, that
+would be an abuse of rules. For more details on the optional files, see the
+FAQ on the "[try.sh script system](../faq.html#try_script)"
+and the
+FAQ on "[alt code](../faq.html#alt_code)".
+
+
+
+If you do need to include more files, you may do so by including as an extra
+file, a tarball. This does **NOT** have to pass `txzchk(1)` tests; only the
+submission tarball must pass the `txzchk(1)` tests. See the [txzchk
+section](#txzchk) for more details on this important tool.
+
+
+
+If you **DO** include a tarball, and the build process or the program extracts
+said tarball(s), the make `clobber` rule **MUST** remove them.
+
+
+
+**IMPORTANT REMINDER**: make **SURE** your tarball does **NOT** reveal who you are!
+The `mkiocccentry(1)` tool creates a v7 format tarball to prevent this. You can
+do the same like:
+
+
+```
+ tar --format=v7 -cJf foo.txz directory
+```
+
+
+See [Rule 17](rules.html#rule17) and in particular the part about the [maximum
+number of files](rules.html#max-files). If you do not follow these points, you
+are at a great risk of violating [Rule 17](rules.html#rule17)!
+
+
+
+**NOTE**: if you want to include a test-suite that requires a lot of files,
+please suggest this in your `remarks.md` and if your submission wins it can
+be done. In other words you should not use a tarball for a test-suite unless you
+have a very good reason for this (and if you do, make **SURE** you specify why
+in your `remarks.md`).
+
+
+
+
+
See also the
FAQ on "[txzchk](../faq.html#txzchk)".
diff --git a/next/rules.html b/next/rules.html
index dc636dd9a..15cd07622 100644
--- a/next/rules.html
+++ b/next/rules.html
@@ -460,9 +460,8 @@ writing by contacting the judges.
IOCCC Rules version
-Jump to: top
-These IOCCC rules are version 28.19 2025-01-30.
+These IOCCC rules are version 28.21 2025-02-03.
The markdown form of these rules
@@ -973,8 +972,8 @@ if you need to include more files than this maximum.
Extra files are defined as files that are not the required files (prog.c,
Makefile, remarks.md and the two generated by mkiocccentry(1) .info.json
-and .auth.json) and the optional files (try.sh, prog.alt.c and
-try.alt.sh).
+and .auth.json) and files that are also not the optional files (try.sh,
+prog.alt.c and try.alt.sh).
Jump to: top
Rule 17 - The COMPLEX details
@@ -1056,7 +1055,7 @@ See also the markdown synta
and the CommonMark Spec.
-The xz compressed tarball file MUST be less than or equal 3999971 octets in size.
+The xz compressed tarball file MUST be less than or equal to 3999971 octets in size.
When your submission’s xz compressed tarball is uncompressed,
@@ -1092,11 +1091,10 @@ Filenames in your entry (that is, not including the files generated by the
-Be <= 38 characters in length
+Be <= 38 characters in length.
-NOT have a / (excluding the entry directory that
-the mkiocccentry(1) tool generates).
+NOT have a leading /.
NOT contain a path component of: . (that is, with
@@ -1116,12 +1114,12 @@ Match the regular expression
NOT be a directory depth > 4.
-NOT have a total path length > 99 characters.
+NOT have a total path length > 99 characters.
-Additionally, the submission tarball created by mkiocccentry(1) MUST have
-the following files (generated by the mkiocccentry(1) tool):
+The submission tarball created by mkiocccentry(1) MUST have
+the additional files that are generated by the mkiocccentry(1) tool:
+The chkentry(1) tool will validate these two JSON files prior to the tarball
+being formed.
+
+
+Files and directories in your submission tarball MUST be specific
+permissions and mkiocccentry(1) does this for you. In particular: directories
+MUST be drwxr-xr-x (i.e. 0755), the optional files, try.sh or
+try.alt.sh, if provided, MUST be -r-xr-xr-x (i.e. 0555) and all other
+files MUST be -r--r--r-- (i.e. 0444). If the files do not have these
+permissions, your submission WILL be rejected for violating Rule
+17! If you do need different permissions, then see the
+FAQ on “file permissions”. Also keep in mind
+Rule 4, Rule 5 and Rule 21.
+
+
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 (including JSON validity). If these checks
-fail it is an error and mkiocccentry(1) will fail. In this case it is very
-possibly a bug; please report it as a bug at the mkiocccentry issues
+fail it is an error and mkiocccentry(1) will fail. In this case (it fails and
+you used mkiocccentry(1)) it is very possibly a bug; please report it as
+a bug at the mkiocccentry issues
page.
@@ -1162,7 +1176,8 @@ having your submission rejected for violating Rule 17!
The maximum number of files your submission tarball may contain, not counting
the optional files (prog.alt.c, try.sh, try.alt.sh) and the mandatory
-files (prog.c, Makefile, remarks.md) is 31. This is defined in the macro
+files (prog.c, Makefile, remarks.md plus the mkiocccentry(1) generated
+files .auth.json and .info.json) is 31. This is defined in the macro
MAX_EXTRA_FILE_COUNT in
soup/limit_ioccc.h
in the mkiocccentry repo. See the
@@ -1251,7 +1266,7 @@ do this AFTER the contest status h
CC BY-SA 4.0 DEED Attribution-ShareAlike 4.0 International
-You (the author(s)) MUST own the contents of your submission OR
+
You (the author(s)) MUST own the content of your submission OR
you MUST HAVE PERMISSION from the owner(s) to submit their content.
You MUST NOT submit anything that cannot be submitted under that license.
Jump to: top
diff --git a/next/rules.md b/next/rules.md
index 799cdb90b..fe0e6cf5a 100644
--- a/next/rules.md
+++ b/next/rules.md
@@ -51,11 +51,9 @@ Jump to: [top](#)
-Jump to: [top](#)
-
-These [IOCCC rules](rules.html) are version **28.19 2025-01-30**.
+These [IOCCC rules](rules.html) are version **28.21 2025-02-03**.
@@ -747,8 +745,8 @@ if you need to include more files than this maximum.
Extra files are defined as files that are not the required files (`prog.c`,
`Makefile`, `remarks.md` and the two generated by `mkiocccentry(1)` `.info.json`
-and `.auth.json`) and the optional files (`try.sh`, `prog.alt.c` and
-`try.alt.sh`).
+and `.auth.json`) and files that are also not the optional files (`try.sh`,
+`prog.alt.c` and `try.alt.sh`).
Jump to: [top](#)
@@ -835,7 +833,7 @@ and the [CommonMark Spec](https://spec.commonmark.org/current/).
-The xz compressed tarball file **MUST** be less than or equal **3999971** octets in size.
+The xz compressed tarball file **MUST** be less than or equal to **3999971** octets in size.
@@ -850,8 +848,6 @@ Your submission's xz compressed tarball **MUST** pass the `txzchk(1)` test. See
the [guidelines](guidelines.html) for more details on this tool.
-
-
**IMPORTANT**: Make **SURE** you have the most recent version of the
`mkiocccentry` toolkit! Not doing so will put you at a great risk of violating
@@ -861,7 +857,6 @@ for more details.
-
You are **HIGHLY ENCOURAGED** to use the `mkiocccentry(1)` tool to form your
submission's xz compressed tarball. See the [guidelines](guidelines.html) for
@@ -880,9 +875,8 @@ Filenames in your entry (that is, not including the files generated by the
`mkiocccentry(1)` tool or the tools it or any other tool invokes) **MUST**:
-* Be <= **38** characters in length
-* **NOT** have a **`/`** (excluding the entry directory that
-the `mkiocccentry(1)` tool generates).
+* Be <= **38** characters in length.
+* **NOT** have a leading **`/`**.
* **NOT** contain a path component of: **`.`** (that is, with
the exception of files generated by `mkiocccentry(1)` itself, it must have
**NO** **`.`**).
@@ -892,11 +886,11 @@ the exception of files generated by `mkiocccentry(1)` itself, it must have
`^[0-9A-Za-z]+[0-9A-Za-z_+.-]*$` (again, excluding files generated by
`mkiocccentry(1)`).
* **NOT** be a directory depth > 4.
-* **NOT** have a total path length > 99 characters.
+* **NOT** have a total **path** length > 99 characters.
-Additionally, the submission tarball created by `mkiocccentry(1)` **MUST** have
-the following files (generated by the `mkiocccentry(1)` tool):
+The submission tarball created by `mkiocccentry(1)` **MUST** have
+the additional files that are generated by the `mkiocccentry(1)` tool:
* `.auth.json` which contains information about the author or
@@ -904,12 +898,30 @@ authors (that will only be looked at if the submission wins).
* `.info.json` which contains information about the
entry.
+
+The `chkentry(1)` tool will validate these two JSON files _prior to_ the tarball
+being formed.
+
+
+
+Files and directories in your submission tarball **MUST** be specific
+permissions and `mkiocccentry(1)` does this for you. In particular: directories
+**MUST** be `drwxr-xr-x` (i.e. `0755`), the optional files, `try.sh` or
+`try.alt.sh`, if provided, **MUST** be `-r-xr-xr-x` (i.e. `0555`) and all other
+files **MUST** be `-r--r--r--` (i.e. `0444`). If the files do not have these
+permissions, your submission **WILL** be rejected for violating [Rule
+17](#rule17)! If you do need different permissions, then see the
+FAQ on "[file permissions](../faq.html#file_perms)". Also keep in mind
+[Rule 4](#rule4), [Rule 5](#rule5) and [Rule 21](#rule21).
+
+
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 (including JSON validity). If these checks
-fail it is an error and `mkiocccentry(1)` will fail. In this case it is very
-**possibly** a bug; please [report it as a bug at the mkiocccentry issues
+fail it is an error and `mkiocccentry(1)` will fail. In this case (it fails and
+you used `mkiocccentry(1)`) it is very **possibly** a bug; please [report it as
+a bug at the mkiocccentry issues
page](https://github.com/ioccc-src/mkiocccentry/issues/new?assignees=&labels=bug&projects=&template=bug_report.yml&title=%5BBug%5D+%3Ctitle%3E).
@@ -938,7 +950,8 @@ having your submission rejected for violating [Rule 17](#rule17)!
The maximum number of files your submission tarball may contain, not counting
the optional files (`prog.alt.c`, `try.sh`, `try.alt.sh`) and the mandatory
-files (`prog.c`, `Makefile`, `remarks.md`) is 31. This is defined in the macro
+files (`prog.c`, `Makefile`, `remarks.md` plus the `mkiocccentry(1)` generated
+files `.auth.json` and `.info.json`) is 31. This is defined in the macro
`MAX_EXTRA_FILE_COUNT` in
[soup/limit_ioccc.h](https://github.com/ioccc-src/mkiocccentry/blob/master/soup/limit_ioccc.h)
in the [mkiocccentry repo](https://github.com/ioccc-src/mkiocccentry). See the
@@ -1049,7 +1062,7 @@ The entirety of your submission must be submitted under the following license:
**[CC BY-SA 4.0 DEED Attribution-ShareAlike 4.0 International](https://creativecommons.org/licenses/by-sa/4.0/)**
-You (the author(s)) **MUST** own the contents of your submission **OR**
+You (the author(s)) **MUST** own the content of your submission **OR**
you **MUST HAVE PERMISSION** from the owner(s) to submit their content.
You **MUST NOT** submit anything that cannot be submitted under that license.
From d2c6b42078ee56c2bf9b907f55555c4f5862d66a Mon Sep 17 00:00:00 2001
From: Cody Boone Ferguson <53008573+xexyl@users.noreply.github.com>
Date: Thu, 6 Feb 2025 10:13:53 -0800
Subject: [PATCH 08/16] Add important note about mkiocccentry execution
It is highly recommended that you run the tool from either the repo
directory itself (making sure you have the most up to date version of
course) or make sure you have installed it (also making sure you have
the most recent version). Not doing this will cause issues with checks
and in the case of out of date versions the submission would be rejected
due to violating rule 17. One can specify the options to mkiocccentry
for the tools required but if you forget or don't have the most up to
date version you will very likely run into problems.
---
faq.html | 10 ++++++++++
faq.md | 11 +++++++++++
next/guidelines.html | 12 ++++++++++++
next/guidelines.md | 13 +++++++++++++
quick-start.html | 10 ++++++++++
quick-start.md | 11 +++++++++++
6 files changed, 67 insertions(+)
diff --git a/faq.html b/faq.html
index eab2d5a95..e5573faa5 100644
--- a/faq.html
+++ b/faq.html
@@ -697,6 +697,16 @@ directory will be created, with the name based on your IOCCC registrati
username, which is in the form of a UUID, and submission number; see the
rules for more details on this, and in 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).
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
diff --git a/faq.md b/faq.md
index a2bfa8853..ef3433712 100644
--- a/faq.md
+++ b/faq.md
@@ -319,6 +319,17 @@ username, which is **in the form of a UUID**, and submission number; see the
[rules](next/rules.html) for more details on this, and in 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).
+
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
diff --git a/next/guidelines.html b/next/guidelines.html
index c6b6e90cb..cefbde128 100644
--- a/next/guidelines.html
+++ b/next/guidelines.html
@@ -609,6 +609,18 @@ that if the directory exists already, you will have to remove it or move it
before this option will work a second time, just like in 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).
+
+
Rule 17 has been significantly modified
to account for the new mkiocccentry repo tools.
Thus, you are STRONGLY advised to use the mkiocccentry(1) tool
diff --git a/next/guidelines.md b/next/guidelines.md
index 27d78b377..709074189 100644
--- a/next/guidelines.md
+++ b/next/guidelines.md
@@ -233,6 +233,19 @@ that if the directory exists already, you will have to remove it or move it
before this option will work a second time, just like in 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).
+
+
[Rule 17](rules.html#rule17) has been **significantly modified**
to account for the new [mkiocccentry repo](https://github.com/ioccc-src/mkiocccentry) tools.
diff --git a/quick-start.html b/quick-start.html
index 2b73ff130..ff688bd6f 100644
--- a/quick-start.html
+++ b/quick-start.html
@@ -540,6 +540,16 @@ 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.
+However, an 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).
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
diff --git a/quick-start.md b/quick-start.md
index 7e3662627..0ba5b7f3e 100644
--- a/quick-start.md
+++ b/quick-start.md
@@ -164,6 +164,17 @@ submission's directory. See the
FAQ on "**[installing mkiocccentry](https://github.com/ioccc-src/mkiocccentry/blob/master/FAQ.md#install)**"
at the mkiocccentry repo.
+However, an **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).
+
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
From f5bf279807238085e7d250198940408e5b6dd13c Mon Sep 17 00:00:00 2001
From: Cody Boone Ferguson <53008573+xexyl@users.noreply.github.com>
Date: Fri, 7 Feb 2025 11:58:19 -0800
Subject: [PATCH 09/16] Update FAQ about new mkiocccentry process
---
faq.html | 108 ++++++++++++++++++++++++++++++++++++++++++++++++++-----
faq.md | 100 ++++++++++++++++++++++++++++++++++++++++++++++-----
2 files changed, 190 insertions(+), 18 deletions(-)
diff --git a/faq.html b/faq.html
index e5573faa5..e46c4cfe5 100644
--- a/faq.html
+++ b/faq.html
@@ -425,7 +425,7 @@
IOCCC FAQ Table of Contents
-This is FAQ version 28.2.4 2025-02-03.
+This is FAQ version 28.2.5 2025-02-07.
- Q 0.0: How can I enter the IOCCC?
@@ -714,12 +714,12 @@ subdirectory), as it needs to be empty.
This subdirectory is where your files will be copied to. Your submission
tarball (which you will upload to the submit server) that txzchk(1) will
validate will be placed in the work directory, and its contents will
-be the subdirectory with your submission’s files.
-The mkiocccentry(1) tool will ask you for information about your
+be the subdirectory with your submission’s files.
+The mkiocccentry(1) tool will also ask you for information about your
submission as well as author details (that will only be looked at if the
-submission wins), run some tests and run a number of other tools, as briefly
-mentioned earlier, and as described in the
-“finer details” section.
+submission wins), run some tests and run a number of other tools, as
+mentioned above, and as described in the “finer
+details” section.
See also the
mkiocccentry repo FAQ
for more up to date information on downloading, compiling, and related FAQ information.
@@ -1392,7 +1392,9 @@ Jump to: top
Q 3.0: What sort of checks does the mkiocccentry tool perform?
-mkiocccentry(1) will check and warn about the following conditions:
+In addition to the checks in the mkiocccentry process
+described below, mkiocccentry(1) will check and warn about the following
+conditions:
- If the files do not exist, are not regular files or cannot be read.
- If
prog.c violates Rule 2 (see
@@ -1412,8 +1414,9 @@ Jump to: top
- If the
Makefile does not have a clean rule.
- If the
Makefile does not have a clobber rule.
- If the
Makefile does not have a try rule.
-- If the
remarks.md is empty.
+If your Makefile is empty or remarks.md is empty it is an error and you will
+have to fix it.
Conditions that one must correct, and which mkiocccentry(1) will prompt until
they are correct, are:
@@ -1448,8 +1451,95 @@ has more than one @ or is longer than MAX_GITHUB_LEN (
- An author handle, if the default is not accepted, does
not match the regexp
^[0-9A-Za-z][0-9A-Za-z._+-]*$.
- An author handle is repeated.
-- The output of
ls on the submission directory is incorrect.
+
+
mkiocccentry process
+
+The mkiocccentry(1) tool performs the following steps:
+
+- Change to the
topdir.
+- Traverses the directory, gathering lists of ignored files and files to copy
+to the submission directory.
+
+- If the depth is too deep it is an error (see
MAX_PATH_DEPTH in
+limit_ioccc.h).
+- If a file is not a sane relative path it is an error (see the
+Rules and Guidelines for more
+details).
+- If the path length (all components) are too long it is an error (see
+
MAX_PATH_LEN in
+limit_ioccc.h).
+- If a filename is too long it is an error (see
MAX_FILENAME_LEN in
+limit_ioccc.h).
+- If a directory is not readable it is an error.
+- If
prog.c, Makefile or remarks.md are not found it is an error.
+- If too many files that are not
prog.c, Makefile, remarks.md,
+try.sh, prog.alt.c or try.alt.sh are found, it is an error (see
+MAX_EXTRA_FILE_COUNT in
+limit_ioccc.h).
+
+- The user is presented with lists of files (including symlinks) and
+directories that were ignored as well as files and directories to be added, both
+required and non-required files.
+
+- Symlinks are ignored and may not be included.
+- Certain filenames are forbidden and are not allowed.
mkiocccentry(1)
+will warn let you know about this. If you do not confirm that this is okay
+it is an error.
+- Certain directories like
.git, CVS and other RCS directories are not
+allowed but are ignored (and not descended into). You will be presented with
+a list of these directories and be asked to confirm it as well.
+- The user is asked to verify each list, including the list of files to be
+added, and if the user says it is not OK the program will abort.
+
+- The non-ignored files are copied under
+
workdir/submit.USERNAME-SLOT.TIMESTAMP, in the correct subdirectories.
+
+- As it copies
prog.c it runs iocccsize(1) and other tests on it,
+allowing you to override issues.
+- As it copies
Makefile it runs tests on it, allowing you to override
+certain issues. Makefile may not be empty.
+- As it copies
remarks.m it checks that it is not empty (if it is empty it
+is an error). remarks.md may not be empty.
+- Only
try.sh and try.alt.sh may be executable (mode 0555).
+- Directories are made prior to the copying of the files.
+- Directories will be made with mode
0755.
+- Other files are mode
0444.
+txzchk(1) verifies these.
+cd submit.USERNAME-SLOT.TIMESTAMP.make -f Makefile clobber.
+
+- If this fails it is not an error but you are warned about it; if the
+Makefile does not exist it is an error.
+
- Traverse the new tree from
., collecting files in the submission directory.
+
+- If an invalid file or directory is found it is an error.
+- If the depth is too deep it is an error.
+- If
prog.c, Makefile or remarks.md are missing it is an error.
+- If a file is not a sane relative path it is an error (see the
+Rules and Guidelines for more
+details).
+- If the path length (all components) are too long it is an error (see
+
MAX_PATH_LEN in
+limit_ioccc.h).
+- If a filename is too long it is an error (see
MAX_FILENAME_LEN in
+limit_ioccc.h).
+- If a directory is not readable it is an error.
+- If too many files that are not
prog.c, Makefile, remarks.md,
+try.sh, prog.alt.c or try.alt.sh are found, it is an error (see
+MAX_EXTRA_FILE_COUNT in
+limit_ioccc.h).
+
+- Report on files that were copied in (3) but are now gone: asking the user to verify.
+- Present the list of non-dot files that remain and ask the user to confirm.
+- Create the
.info.json and .auth.json files, running chkenry(1) on each.
+- List the submission directory contents, asking the user once again to verify
+everything is okay.
+- Form the tarball and run
txzchk(1) on it.
+
+If any of the steps fail or if the user says something is not okay, it aborts.
Although the mkiocccentry(1) tool will verify everything for you, you may wish
to validate different parts individually with the different tools. As the
rules state, each of these tools has a -h option.
diff --git a/faq.md b/faq.md
index ef3433712..8e7f3edb6 100644
--- a/faq.md
+++ b/faq.md
@@ -1,6 +1,6 @@
# IOCCC FAQ Table of Contents
-This is FAQ version **28.2.4 2025-02-03**.
+This is FAQ version **28.2.5 2025-02-07**.
## 0. [Entering the IOCCC: the bare minimum you need to know](#enter_questions)
@@ -339,12 +339,11 @@ This _subdirectory is where your files will be **copied** to_. Your _submission
tarball_ (which you will upload to the submit server) that `txzchk(1)` will
validate _will be placed in the **work directory**_, and **its _contents_ will
be the _subdirectory_ with your submission's files**.
-
-The `mkiocccentry(1)` tool will ask you for information about your
+The `mkiocccentry(1)` tool will also ask you for information about your
submission _as well as author details_ (that will only be looked at if the
-submission wins), run some tests and run a number of other tools, as briefly
-mentioned earlier, and as described in the
-"[finer details](#mkiocccentry_details)" section.
+submission wins), run some tests and run a number of other tools, as
+mentioned above, and as described in the "[finer
+details](#mkiocccentry_details)" section.
See also the
[mkiocccentry repo FAQ](https://github.com/ioccc-src/mkiocccentry/blob/master/FAQ.md)
@@ -1213,7 +1212,9 @@ Jump to: [top](#)
### Q 3.0: What sort of checks does the mkiocccentry tool perform?
-`mkiocccentry(1)` will check and warn about the following conditions:
+In addition to the checks in the [mkiocccentry process](#mkiocccentry_process)
+described below, `mkiocccentry(1)` will check and warn about the following
+conditions:
- If the files do not exist, are not regular files or cannot be read.
- If `prog.c` violates [Rule 2](next/rules.html#rule2) (see
@@ -1233,7 +1234,9 @@ Jump to: [top](#)
- If the `Makefile` does not have a `clean` rule.
- If the `Makefile` does not have a `clobber` rule.
- If the `Makefile` does not have a `try` rule.
-- If the `remarks.md` is empty.
+
+If your `Makefile` is empty or `remarks.md` is empty it is an error and you will
+have to fix it.
Conditions that one must correct, and which `mkiocccentry(1)` will prompt until
they are correct, are:
@@ -1269,7 +1272,86 @@ has more than one `@` or is longer than `MAX_GITHUB_LEN` (see
- An _author handle_, if the default is not accepted, does
not match the regexp `^[0-9A-Za-z][0-9A-Za-z._+-]*$`.
- An _author handle_ is repeated.
-- The output of `ls` on the submission directory is incorrect.
+
+
+#### `mkiocccentry` process
+
+
+The `mkiocccentry(1)` tool performs the following steps:
+
+0. Change to the `topdir`.
+1. Traverses the directory, gathering lists of ignored files and files to copy
+to the submission directory.
+ * If the depth is too deep it is an error (see `MAX_PATH_DEPTH` in
+[limit_ioccc.h](https://github.com/ioccc-src/mkiocccentry/blob/master/soup/limit_ioccc.h)).
+ * If a file is not a sane relative path it is an error (see the
+ [Rules](next/rules.html#) and [Guidelines](next/guidelines.html) for more
+ details).
+ * If the path length (all components) are too long it is an error (see
+ `MAX_PATH_LEN` in
+ [limit_ioccc.h](https://github.com/ioccc-src/mkiocccentry/blob/master/soup/limit_ioccc.h)).
+ * If a filename is too long it is an error (see `MAX_FILENAME_LEN` in
+ [limit_ioccc.h](https://github.com/ioccc-src/mkiocccentry/blob/master/soup/limit_ioccc.h)).
+ * If a directory is not readable it is an error.
+ * If `prog.c`, `Makefile` or `remarks.md` are not found it is an error.
+ * If too many files that are not `prog.c`, `Makefile`, `remarks.md`,
+ `try.sh`, `prog.alt.c` or `try.alt.sh` are found, it is an error (see
+ `MAX_EXTRA_FILE_COUNT` in
+ [limit_ioccc.h](https://github.com/ioccc-src/mkiocccentry/blob/master/soup/limit_ioccc.h)).
+2. The user is presented with lists of files (including symlinks) and
+directories that were ignored as well as files and directories to be added, both
+required and non-required files.
+ * Symlinks are ignored and may not be included.
+ * Certain filenames are forbidden and are not allowed. `mkiocccentry(1)`
+ will warn let you know about this. If you do not confirm that this is okay
+ it is an error.
+ * Certain directories like `.git`, `CVS` and other RCS directories are not
+ allowed but are ignored (and not descended into). You will be presented with
+ a list of these directories and be asked to confirm it as well.
+ * The user is asked to verify each list, including the list of files to be
+ added, and if the user says it is not OK the program will abort.
+3. The non-ignored files are copied under
+`workdir/submit.USERNAME-SLOT.TIMESTAMP`, in the correct subdirectories.
+ * As it copies `prog.c` it runs `iocccsize(1)` and other tests on it,
+ allowing you to override issues.
+ * As it copies `Makefile` it runs tests on it, allowing you to override
+ certain issues. `Makefile` may not be empty.
+ * As it copies `remarks.m` it checks that it is not empty (if it is empty it
+ is an error). `remarks.md` may not be empty.
+ * Only `try.sh` and `try.alt.sh` may be executable (mode `0555`).
+ * Directories are made prior to the copying of the files.
+ * Directories will be made with mode `0755`.
+ * Other files are mode `0444`.
+ * `txzchk(1)` verifies these.
+4. `cd submit.USERNAME-SLOT.TIMESTAMP`.
+5. `make -f Makefile clobber`.
+ * If this fails it is not an error but you are warned about it; if the
+ Makefile does not exist it is an error.
+6. Traverse the new tree from `.`, collecting files in the submission directory.
+ * If an invalid file or directory is found it is an error.
+ * If the depth is too deep it is an error.
+ * If `prog.c`, `Makefile` or `remarks.md` are missing it is an error.
+ * If a file is not a sane relative path it is an error (see the
+ [Rules](next/rules.html#) and [Guidelines](next/guidelines.html) for more
+ details).
+ * If the path length (all components) are too long it is an error (see
+ `MAX_PATH_LEN` in
+ [limit_ioccc.h](https://github.com/ioccc-src/mkiocccentry/blob/master/soup/limit_ioccc.h)).
+ * If a filename is too long it is an error (see `MAX_FILENAME_LEN` in
+ [limit_ioccc.h](https://github.com/ioccc-src/mkiocccentry/blob/master/soup/limit_ioccc.h)).
+ * If a directory is not readable it is an error.
+ * If too many files that are not `prog.c`, `Makefile`, `remarks.md`,
+ `try.sh`, `prog.alt.c` or `try.alt.sh` are found, it is an error (see
+ `MAX_EXTRA_FILE_COUNT` in
+ [limit_ioccc.h](https://github.com/ioccc-src/mkiocccentry/blob/master/soup/limit_ioccc.h)).
+7. Report on files that were copied in (3) but are now gone: asking the user to verify.
+8. Present the list of non-dot files that remain and ask the user to confirm.
+9. Create the `.info.json` and `.auth.json` files, running `chkenry(1)` on each.
+10. List the submission directory contents, asking the user once again to verify
+everything is okay.
+11. Form the tarball and run `txzchk(1)` on it.
+
+If any of the steps fail or if the user says something is not okay, it aborts.
Although the `mkiocccentry(1)` tool will verify everything for you, you may wish
to validate different parts individually with the different tools. As the
From c6e1c09401e131ea1b8f4a7bf0400c8193c398dc Mon Sep 17 00:00:00 2001
From: Cody Boone Ferguson <53008573+xexyl@users.noreply.github.com>
Date: Sat, 8 Feb 2025 10:34:24 -0800
Subject: [PATCH 10/16] Update FAQ and rules for mkiocccentry
Additional things were added to the process (and as for the rules it
notes that remarks.md is only checked for size > 0, not that it has
content).
---
faq.html | 79 ++++++++++++++++++++++++++++------------------
faq.md | 83 ++++++++++++++++++++++++++++++-------------------
next/rules.html | 6 ++--
next/rules.md | 6 ++--
4 files changed, 108 insertions(+), 66 deletions(-)
diff --git a/faq.html b/faq.html
index e46c4cfe5..e8f66416b 100644
--- a/faq.html
+++ b/faq.html
@@ -425,7 +425,7 @@
IOCCC FAQ Table of Contents
-This is FAQ version 28.2.5 2025-02-07.
+This is FAQ version 28.2.6 2025-02-08.
- Q 0.0: How can I enter the IOCCC?
@@ -1463,9 +1463,10 @@ to the submission directory.
- If the depth is too deep it is an error (see
MAX_PATH_DEPTH in
limit_ioccc.h).
-- If a file is not a sane relative path it is an error (see the
-Rules and Guidelines for more
-details).
+- If a filename or directory name is not a sane relative path, not allowed
+or will not be added for some reason, it will be added to a relevant list to show to
+the user later, to let them know it is ignored (see the
+Rules and Guidelines for more details).
- If the path length (all components) are too long it is an error (see
MAX_PATH_LEN in
limit_ioccc.h).
@@ -1478,49 +1479,65 @@ details).
MAX_EXTRA_FILE_COUNT in
limit_ioccc.h).
-- The user is presented with lists of files (including symlinks) and
-directories that were ignored as well as files and directories to be added, both
-required and non-required files.
+
- The user is presented with lists of files, symlinks and directories found.
-- Symlinks are ignored and may not be included.
-- Certain filenames are forbidden and are not allowed.
mkiocccentry(1)
-will warn let you know about this. If you do not confirm that this is okay
-it is an error.
-- Certain directories like
.git, CVS and other RCS directories are not
+ - Symlinks are ignored and may not be included. You will be warned about
+this.
+- Certain filenames (such as
README.md, index.html and various others)
+are forbidden and are not allowed. mkiocccentry(1) will warn and let you
+know about this.
+- Certain directories like
.git, CVS and other RCS related directories are not
allowed but are ignored (and not descended into). You will be presented with
-a list of these directories and be asked to confirm it as well.
+a list of these directories.
+- No file or directory starting with
. will be allowed.
+- List of directories that will be made.
+- List of required and non-required files that will be added.
- The user is asked to verify each list, including the list of files to be
added, and if the user says it is not OK the program will abort.
- The non-ignored files are copied under
-
workdir/submit.USERNAME-SLOT.TIMESTAMP, in the correct subdirectories.
+workdir/submit.USERNAME-SLOT.TIMESTAMP (created prior to traversing the
+topdir), making sure to keep the files in the correct directory.
-- As it copies
prog.c it runs iocccsize(1) and other tests on it,
-allowing you to override issues.
-- As it copies
Makefile it runs tests on it, allowing you to override
-certain issues. Makefile may not be empty.
-- As it copies
remarks.m it checks that it is not empty (if it is empty it
-is an error). remarks.md may not be empty.
-- Only
try.sh and try.alt.sh may be executable (mode 0555).
- Directories are made prior to the copying of the files.
-- Directories will be made with mode
0755.
-- Other files are mode
0444.
-txzchk(1) verifies these.- Directories MUST be (and will be made) with mode
0755.
+try.sh and try.alt.sh MUST be (and will be copied as) executable (in
+particular: mode 0555).- Other files MUST be (and will be copied as) mode
0444.
+txzchk(1) verifies these modes (and much more).
cd submit.USERNAME-SLOT.TIMESTAMP.make -f Makefile clobber.
-- If this fails it is not an error but you are warned about it; if the
-Makefile does not exist it is an error.
+- If this fails it is not an error but you are warned about it (even so, see
+Rule 20).
- Traverse the new tree from
., collecting files in the submission directory.
- If an invalid file or directory is found it is an error.
- If the depth is too deep it is an error.
-- If
prog.c, Makefile or remarks.md are missing it is an error.
+- If
prog.c, Makefile or remarks.md are missing (or not readable
+regular files) it is an error.
+iocccsize(1) (via the mkiocccentry(1) function check_prog_c()) will
+be run on your prog.c, allowing you to override any warnings; if you do not
+override an issue flagged it is an error but if warnings from check_prog_c()
+are ignored you risk violating the Rules, including Rule
+2.check_Makefile() will be run on Makefile; if it is a non-readable or
+empty file it is an error but otherwise you may override any warnings
+(risking violating the Rules, especially Rule
+17 and Rule 20).check_remarks_md() will be run on your remarks.m; if it is not a
+regular readable file or it is empty it is an error. Otherwise it will
+proceed. Note it does not check that there is any text in the file, just
+that the file size is not 0.- If a file is not a sane relative path it is an error (see the
Rules and Guidelines for more
-details).
+details, and for even more details see the comments in the jparse function
+sane_relative_path() in the
+jparse/util.c
+file at the mkiocccentry repo (this
+comes from the jparse repo).
- If the path length (all components) are too long it is an error (see
MAX_PATH_LEN in
limit_ioccc.h).
@@ -1532,7 +1549,8 @@ details).
MAX_EXTRA_FILE_COUNT in
limit_ioccc.h).
-Report on files that were copied in (3) but are now gone: asking the user to verify.
+Report on files that were copied in (3) and directories made in (3) but are
+now gone: asking the user to verify.
Present the list of non-dot files that remain and ask the user to confirm.
Create the .info.json and .auth.json files, running chkenry(1) on each.
List the submission directory contents, asking the user once again to verify
@@ -1559,7 +1577,8 @@ for more details on the tools that mkiocccentry either executes dir
indirectly as part of the packaging process, especially if you wish to run one
or more of these tools manually.
See also the Guidelines and the Rules
-(and in particular Rule 17).
+(especially Rule 2, Rule
+17, Rule 20).
Jump to: top
diff --git a/faq.md b/faq.md
index 8e7f3edb6..05a1b474c 100644
--- a/faq.md
+++ b/faq.md
@@ -1,6 +1,6 @@
# IOCCC FAQ Table of Contents
-This is FAQ version **28.2.5 2025-02-07**.
+This is FAQ version **28.2.6 2025-02-08**.
## 0. [Entering the IOCCC: the bare minimum you need to know](#enter_questions)
@@ -1283,10 +1283,11 @@ The `mkiocccentry(1)` tool performs the following steps:
1. Traverses the directory, gathering lists of ignored files and files to copy
to the submission directory.
* If the depth is too deep it is an error (see `MAX_PATH_DEPTH` in
-[limit_ioccc.h](https://github.com/ioccc-src/mkiocccentry/blob/master/soup/limit_ioccc.h)).
- * If a file is not a sane relative path it is an error (see the
- [Rules](next/rules.html#) and [Guidelines](next/guidelines.html) for more
- details).
+ [limit_ioccc.h](https://github.com/ioccc-src/mkiocccentry/blob/master/soup/limit_ioccc.h)).
+ * If a filename or directory name is not a sane relative path, not allowed
+ or will not be added for some reason, it will be added to a relevant list to show to
+ the user later, to let them know it is ignored (see the
+ [Rules](next/rules.html#) and [Guidelines](next/guidelines.html) for more details).
* If the path length (all components) are too long it is an error (see
`MAX_PATH_LEN` in
[limit_ioccc.h](https://github.com/ioccc-src/mkiocccentry/blob/master/soup/limit_ioccc.h)).
@@ -1298,42 +1299,58 @@ to the submission directory.
`try.sh`, `prog.alt.c` or `try.alt.sh` are found, it is an error (see
`MAX_EXTRA_FILE_COUNT` in
[limit_ioccc.h](https://github.com/ioccc-src/mkiocccentry/blob/master/soup/limit_ioccc.h)).
-2. The user is presented with lists of files (including symlinks) and
-directories that were ignored as well as files and directories to be added, both
-required and non-required files.
- * Symlinks are ignored and may not be included.
- * Certain filenames are forbidden and are not allowed. `mkiocccentry(1)`
- will warn let you know about this. If you do not confirm that this is okay
- it is an error.
- * Certain directories like `.git`, `CVS` and other RCS directories are not
+2. The user is presented with lists of files, symlinks and directories found.
+ * Symlinks are ignored and may not be included. You will be warned about
+ this.
+ * Certain filenames (such as `README.md`, `index.html` and various others)
+ are forbidden and are not allowed. `mkiocccentry(1)` will warn and let you
+ know about this.
+ * Certain directories like `.git`, `CVS` and other RCS related directories are not
allowed but are ignored (and not descended into). You will be presented with
- a list of these directories and be asked to confirm it as well.
+ a list of these directories.
+ * No file or directory starting with `.` will be allowed.
+ * List of directories that will be made.
+ * List of required and non-required files that will be added.
* The user is asked to verify each list, including the list of files to be
added, and if the user says it is not OK the program will abort.
3. The non-ignored files are copied under
-`workdir/submit.USERNAME-SLOT.TIMESTAMP`, in the correct subdirectories.
- * As it copies `prog.c` it runs `iocccsize(1)` and other tests on it,
- allowing you to override issues.
- * As it copies `Makefile` it runs tests on it, allowing you to override
- certain issues. `Makefile` may not be empty.
- * As it copies `remarks.m` it checks that it is not empty (if it is empty it
- is an error). `remarks.md` may not be empty.
- * Only `try.sh` and `try.alt.sh` may be executable (mode `0555`).
+`workdir/submit.USERNAME-SLOT.TIMESTAMP` (created prior to traversing the
+`topdir`), making sure to keep the files in the correct directory.
* Directories are made prior to the copying of the files.
- * Directories will be made with mode `0755`.
- * Other files are mode `0444`.
- * `txzchk(1)` verifies these.
+ * Directories **MUST** be (and will be made) with mode `0755`.
+ * `try.sh` and `try.alt.sh` **MUST** be (and will be copied as) executable (in
+ particular: mode `0555`).
+ * Other files MUST be (and will be copied as) mode `0444`.
+ * `txzchk(1)` verifies these modes (and much more).
4. `cd submit.USERNAME-SLOT.TIMESTAMP`.
5. `make -f Makefile clobber`.
- * If this fails it is not an error but you are warned about it; if the
- Makefile does not exist it is an error.
-6. Traverse the new tree from `.`, collecting files in the submission directory.
+ * If this fails it is not an error but you are warned about it (even so, see
+ [Rule 20](next/rules.html#rule20)).
+6. Traverse the new tree from `.`, collecting files in the submission directory.
* If an invalid file or directory is found it is an error.
* If the depth is too deep it is an error.
- * If `prog.c`, `Makefile` or `remarks.md` are missing it is an error.
+ * If `prog.c`, `Makefile` or `remarks.md` are missing (or not readable
+ regular files) it is an error.
+ * `iocccsize(1)` (via the `mkiocccentry(1)` function `check_prog_c()`) will
+ be run on your `prog.c`, allowing you to override any warnings; if you do not
+ override an issue flagged it is an error but if warnings from `check_prog_c()`
+ are ignored you risk violating the [Rules](next/rules.html), including [Rule
+ 2](next/rules.html#rule2).
+ * `check_Makefile()` will be run on `Makefile`; if it is a non-readable or
+ empty file it is an error but otherwise you may override any warnings
+ (risking violating the [Rules](next/rules.html), especially [Rule
+ 17](next/rules.html#rule17) and [Rule 20](next/rules.html#rule20)).
+ * `check_remarks_md()` will be run on your `remarks.m`; if it is not a
+ regular readable file or it is empty it is an error. Otherwise it will
+ proceed. Note it does not check that there is any text in the file, just
+ that the file size is not 0.
* If a file is not a sane relative path it is an error (see the
[Rules](next/rules.html#) and [Guidelines](next/guidelines.html) for more
- details).
+ details, and for even more details see the comments in the jparse function
+ `sane_relative_path()` in the
+ [jparse/util.c](https://github.com/ioccc-src/mkiocccentry/blob/master/jparse/util.c)
+ file at the [mkiocccentry repo](https://github.com/ioccc-src/mkiocccentry]) (this
+ comes from the [jparse repo](https://github.com/xexyl/jparse/)).
* If the path length (all components) are too long it is an error (see
`MAX_PATH_LEN` in
[limit_ioccc.h](https://github.com/ioccc-src/mkiocccentry/blob/master/soup/limit_ioccc.h)).
@@ -1344,7 +1361,8 @@ required and non-required files.
`try.sh`, `prog.alt.c` or `try.alt.sh` are found, it is an error (see
`MAX_EXTRA_FILE_COUNT` in
[limit_ioccc.h](https://github.com/ioccc-src/mkiocccentry/blob/master/soup/limit_ioccc.h)).
-7. Report on files that were copied in (3) but are now gone: asking the user to verify.
+7. Report on files that were copied in (3) and directories made in (3) but are
+now gone: asking the user to verify.
8. Present the list of non-dot files that remain and ask the user to confirm.
9. Create the `.info.json` and `.auth.json` files, running `chkenry(1)` on each.
10. List the submission directory contents, asking the user once again to verify
@@ -1374,7 +1392,8 @@ indirectly as part of the packaging process, especially if you wish to run one
or more of these tools manually.
See also the [Guidelines](next/guidelines.html) and the [Rules](next/rules.html)
-(and in particular [Rule 17](next/rules.html#rule17)).
+(especially [Rule 2](next/rules.html#rule2), [Rule
+17](next/rules.html#rule17), [Rule 20](next/rules.html#rule20)).
Jump to: [top](#)
diff --git a/next/rules.html b/next/rules.html
index 15cd07622..9e525a639 100644
--- a/next/rules.html
+++ b/next/rules.html
@@ -461,7 +461,7 @@ writing by
contacting the judges.
-These IOCCC rules are version 28.21 2025-02-03.
+These IOCCC rules are version 28.22 2025-02-08.
The markdown form of these rules
@@ -1043,7 +1043,9 @@ FAQ on “Makefile compatibility”
for help.
-The remarks.md MUST be a non-empty file in markdown form. See also
+The remarks.md MUST be a non-empty file in markdown form
+(mkiocccentry(1) only checks the file size but if you do not have any text in
+it you still risk violating this rule). See also
Rule 18 and our
FAQ on “remarks.md”
and our
diff --git a/next/rules.md b/next/rules.md
index fe0e6cf5a..13d7dacb6 100644
--- a/next/rules.md
+++ b/next/rules.md
@@ -53,7 +53,7 @@ Jump to: [top](#)
-These [IOCCC rules](rules.html) are version **28.21 2025-02-03**.
+These [IOCCC rules](rules.html) are version **28.22 2025-02-08**.
@@ -819,7 +819,9 @@ for help.
-The `remarks.md` **MUST** be a **non**-empty file in markdown form. See also
+The `remarks.md` **MUST** be a **non**-empty file in markdown form
+(`mkiocccentry(1)` only checks the file size but if you do not have any text in
+it you still risk violating this rule). See also
[Rule 18](#rule18) and our
FAQ on "[remarks.md](../faq.html#remarks_md)"
and our
From 949cdced670450a0265fbc98cc7efb5b79ff9282 Mon Sep 17 00:00:00 2001
From: Cody Boone Ferguson <53008573+xexyl@users.noreply.github.com>
Date: Sat, 8 Feb 2025 18:01:35 -0800
Subject: [PATCH 11/16] Typo fix in FAQ
---
faq.html | 2 +-
faq.md | 2 +-
2 files changed, 2 insertions(+), 2 deletions(-)
diff --git a/faq.html b/faq.html
index e8f66416b..21dd6854c 100644
--- a/faq.html
+++ b/faq.html
@@ -1552,7 +1552,7 @@ comes from the jparse repo).
Report on files that were copied in (3) and directories made in (3) but are
now gone: asking the user to verify.
Present the list of non-dot files that remain and ask the user to confirm.
-Create the .info.json and .auth.json files, running chkenry(1) on each.
+Create the .info.json and .auth.json files, running chkentry(1) on each.
List the submission directory contents, asking the user once again to verify
everything is okay.
Form the tarball and run txzchk(1) on it.
diff --git a/faq.md b/faq.md
index 05a1b474c..353b1e36f 100644
--- a/faq.md
+++ b/faq.md
@@ -1364,7 +1364,7 @@ to the submission directory.
7. Report on files that were copied in (3) and directories made in (3) but are
now gone: asking the user to verify.
8. Present the list of non-dot files that remain and ask the user to confirm.
-9. Create the `.info.json` and `.auth.json` files, running `chkenry(1)` on each.
+9. Create the `.info.json` and `.auth.json` files, running `chkentry(1)` on each.
10. List the submission directory contents, asking the user once again to verify
everything is okay.
11. Form the tarball and run `txzchk(1)` on it.
From a33a9048adb353afd3a5e724ac50b29fb4575e8b Mon Sep 17 00:00:00 2001
From: Cody Boone Ferguson <53008573+xexyl@users.noreply.github.com>
Date: Sat, 8 Feb 2025 18:14:19 -0800
Subject: [PATCH 12/16] Minor fix in mkiocccentry process in FAQ
---
faq.html | 3 ++-
faq.md | 3 ++-
2 files changed, 4 insertions(+), 2 deletions(-)
diff --git a/faq.html b/faq.html
index 21dd6854c..d3e70ba4c 100644
--- a/faq.html
+++ b/faq.html
@@ -1458,7 +1458,8 @@ not match the regexp ^[0-9A-Za-z][0-9A-Za-z._+-]*$.
The mkiocccentry(1) tool performs the following steps:
- Change to the
topdir.
-- Traverses the directory, gathering lists of ignored files and files to copy
+
- Traverses the directory, gathering lists of ignored
+files/directories/symlinks as well as directories to make and files to copy
to the submission directory.
- If the depth is too deep it is an error (see
MAX_PATH_DEPTH in
diff --git a/faq.md b/faq.md
index 353b1e36f..5a1cbdf3a 100644
--- a/faq.md
+++ b/faq.md
@@ -1280,7 +1280,8 @@ not match the regexp `^[0-9A-Za-z][0-9A-Za-z._+-]*$`.
The `mkiocccentry(1)` tool performs the following steps:
0. Change to the `topdir`.
-1. Traverses the directory, gathering lists of ignored files and files to copy
+1. Traverses the directory, gathering lists of ignored
+files/directories/symlinks as well as directories to make and files to copy
to the submission directory.
* If the depth is too deep it is an error (see `MAX_PATH_DEPTH` in
[limit_ioccc.h](https://github.com/ioccc-src/mkiocccentry/blob/master/soup/limit_ioccc.h)).
From 943e3077b9eebaaf35315bf812ca04cf867bd844 Mon Sep 17 00:00:00 2001
From: Cody Boone Ferguson <53008573+xexyl@users.noreply.github.com>
Date: Sat, 8 Feb 2025 18:19:14 -0800
Subject: [PATCH 13/16] Minor fix in FAQ about mkiocccentry process
---
faq.html | 2 +-
faq.md | 2 +-
2 files changed, 2 insertions(+), 2 deletions(-)
diff --git a/faq.html b/faq.html
index d3e70ba4c..3b1d88669 100644
--- a/faq.html
+++ b/faq.html
@@ -1498,7 +1498,7 @@ added, and if the user says it is not OK the program will abort.
- The non-ignored files are copied under
workdir/submit.USERNAME-SLOT.TIMESTAMP (created prior to traversing the
-topdir), making sure to keep the files in the correct directory.
+topdir), making sure to keep the files in their correct directory.
- Directories are made prior to the copying of the files.
- Directories MUST be (and will be made) with mode
0755.
diff --git a/faq.md b/faq.md
index 5a1cbdf3a..e197214f5 100644
--- a/faq.md
+++ b/faq.md
@@ -1316,7 +1316,7 @@ to the submission directory.
added, and if the user says it is not OK the program will abort.
3. The non-ignored files are copied under
`workdir/submit.USERNAME-SLOT.TIMESTAMP` (created prior to traversing the
-`topdir`), making sure to keep the files in the correct directory.
+`topdir`), making sure to keep the files in their correct directory.
* Directories are made prior to the copying of the files.
* Directories **MUST** be (and will be made) with mode `0755`.
* `try.sh` and `try.alt.sh` **MUST** be (and will be copied as) executable (in
From 2c3b47da5795cc4135429f197cf2dcf22dea1761 Mon Sep 17 00:00:00 2001
From: Cody Boone Ferguson <53008573+xexyl@users.noreply.github.com>
Date: Sun, 9 Feb 2025 13:49:02 -0800
Subject: [PATCH 14/16] More updates to FAQ about mkiocccentry process
The list now details every step taken and the question was also changed
to help make it easier to find (one need not read this but if they want
to it is now in the correct order).
---
faq.html | 239 +++++++++++++++++++++++++++++--------------------------
faq.md | 214 +++++++++++++++++++++++++------------------------
2 files changed, 233 insertions(+), 220 deletions(-)
diff --git a/faq.html b/faq.html
index 3b1d88669..be77a7e0b 100644
--- a/faq.html
+++ b/faq.html
@@ -425,7 +425,7 @@
IOCCC FAQ Table of Contents
-This is FAQ version 28.2.6 2025-02-08.
+This is FAQ version 28.2.7 2025-02-09.
-- Q 3.0: What sort of checks does the mkiocccentry tool perform?
+- Q 3.0: What is the
mkiocccentry(1) process and what sort of checks does it perform?
- Q 3.1: How can I validate my submission tarball?
- Q 3.2: What is the
fnamchk tool?
- Q 3.3: How can I validate my
.auth.json and/or .info.json files?
@@ -1389,12 +1389,130 @@ entries that do not win on their web page for everyone to see.
Section 3: The mkiocccentry toolkit: finer details
Jump to: top
-
-
Q 3.0: What sort of checks does the mkiocccentry tool perform?
+
+
Q 3.0: What is the mkiocccentry(1) process and what sort of checks does it perform?
-
In addition to the checks in the mkiocccentry process
-described below, mkiocccentry(1) will check and warn about the following
-conditions:
+
The mkiocccentry(1) tool performs the following steps:
+
+- Ask the user for a submission ID (see the quick-start
+guide for more details on how to obtain this).
+
+- If this is an invalid UUID (malformed), it is an error.
+
+- Ask the user for the submission slot (the submission number; see Rule
+17 for more details).
+
+- If this is out of range it is an error (see
MAX_SUBMIT_SLOT in
+limit_ioccc.h).
+
+- Change to the
topdir.
+- Traverses the directory, creating lists of ignored
+files/directories/symlinks as well as a list directories to make and a list of
+files to copy to the submission directory.
+
+- If the depth is too deep it is an error (see
MAX_PATH_DEPTH in
+limit_ioccc.h).
+- If there are too many directories it is an error (see
MAX_DIR_COUNT in
+limit_ioccc.h).
+- If a filename or directory name is not a sane relative path, not allowed
+or will not be added for some other reason, it will be added to a relevant list to show to
+the user later, to let them know it is ignored. By
relative we mean it
+must not start with / and by sane we mean that each component must match
+the regexp: ^[0-9A-Za-z]+[0-9A-Za-z_+.-]*$.
+- If the path length (i.e. the entire length of the path from the
topdir)
+is too long it is an error (see MAX_PATH_LEN in
+limit_ioccc.h).
+- If a filename is too long it is an error (see
MAX_FILENAME_LEN in
+limit_ioccc.h).
+- If there is an unknown error it is an error :-)
+- If a path is NULL it is an error.
+- If a path is an empty string it is an error.
+- If the max path length is <= 0 it is an error (and a bug).
+- If the max depth is <= 0 it is an error (and a bug).
+- If the max filename length is <= 0 it is an error (and a bug).
+- If a directory is not readable it is an error.
+- If
prog.c, Makefile or remarks.md is/are not found it is an error.
+- If too many files that are not
prog.c, Makefile, remarks.md,
+try.sh, prog.alt.c or try.alt.sh are found, it is an error (see
+MAX_EXTRA_FILE_COUNT in
+limit_ioccc.h).
+
+- Show each list to the user, asking if this is okay. The lists include:
+
+- Ignored directories (those like
.git, CVS, RCCS and .svn).
+- Unsafe directory names that will not be added (i.e. those that are not
+POSIX plus + safe chars only; see above step (4)). This includes directories
+starting with a
..
+- Forbidden files such as
index.html, README.md, prog, prog.alt.
+- Unsafe filenames that will not be added (i.e. those that are not POSIX
+plus + safe chars only; see above step (4)). This includes files starting
+with
..
+- Symlinks found (these are not allowed).
+- Directories to be made.
+- Required files (
prog.c, Makefile and remarks.md) to be copied.
+- Non-required files to be copied.
+- The user is asked to verify each list, including the list of files to be
+added, and if the user says it is not OK the program will abort.
+
+- Make any directories if necessary (under
+
workdir/submit.USERNAME-SLOT.TIMESTAMP i.e. the submission directory).
+
+- Directories MUST be and are made with mode
0755.
+- If any directory is not this mode
txzchk(1) will flag it.
+
+- The non-ignored files are copied to their respective directories under the
+submission directory.
+
+try.sh and try.alt.sh MUST be and are copied as mode 0555.- All other files MUST be and are copied as mode
0444.
+- Anything else is an error and
txzchk(1) will flag this.
+
+cd submit.USERNAME-SLOT.TIMESTAMP (i.e. switch to submission directory).make -f Makefile clobber.
+
+- If this fails it is not an error but you are warned about it (even so, see
+Rule 20).
+
- Traverse the new tree from
. with additional steps from (4).
+
+
+- If any file has an ignored directory name in it, it is an error.
+- If a symlink is found it is an error.
+- If a forbidden filename exists it is an error.
+- If any file or directory starts with
/ or is not POSIX plus + safe chars only it is an error.
+- If the depth is too deep it is an error.
+- If
prog.c, Makefile or remarks.md are missing (or not readable
+regular files) it is an error.
+iocccsize(1) (via the mkiocccentry(1) function check_prog_c()) will
+be run on your prog.c, allowing you to override any warnings; if you do not
+override an issue flagged it is an error but if warnings from check_prog_c()
+are ignored you risk violating the Rules, including Rule
+2.check_Makefile() will be run on Makefile; if it is a non-readable or
+empty file it is an error but otherwise you may override any warnings
+(risking violating the Rules, especially Rule
+17 and Rule 20).check_remarks_md() will be run on your remarks.m; if it is not a
+regular readable file or it is empty it is an error. Otherwise it will
+proceed. Note it does not check that there is any text in the file, just
+that the file size is not 0.- If any other error condition in step (4) occurs it is also an error.
+
+
+- Report on files that were copied in (3) and directories made in (3) but are
+now gone: asking the user to verify.
+- Present the list of non-dot files that remain and ask the user to confirm.
+- Ask the user for a submission title.
+- Ask the user for a one line abstract of the submission.
+- Ask the user for the number of authors and for each author ask a variety of
+questions (see below for more information on what kind of questions).
+- Show the output of
ls -lakR ., asking the user to confirm that the listing
+is okay.
+- Create the tarball.
+- Run
txzchk(1) on the tarball.
+
+
If any of the steps fail or if the user says something is not okay, it aborts.
+
Some of the checks that are made:
- If the files do not exist, are not regular files or cannot be read.
- If
prog.c violates Rule 2 (see
@@ -1452,113 +1570,6 @@ has more than one @ or is longer than MAX_GITHUB_LEN (
not match the regexp ^[0-9A-Za-z][0-9A-Za-z._+-]*$.
- An author handle is repeated.
-
-
mkiocccentry process
-
-
The mkiocccentry(1) tool performs the following steps:
-
-- Change to the
topdir.
-- Traverses the directory, gathering lists of ignored
-files/directories/symlinks as well as directories to make and files to copy
-to the submission directory.
-
-- If the depth is too deep it is an error (see
MAX_PATH_DEPTH in
-limit_ioccc.h).
-- If a filename or directory name is not a sane relative path, not allowed
-or will not be added for some reason, it will be added to a relevant list to show to
-the user later, to let them know it is ignored (see the
-Rules and Guidelines for more details).
-- If the path length (all components) are too long it is an error (see
-
MAX_PATH_LEN in
-limit_ioccc.h).
-- If a filename is too long it is an error (see
MAX_FILENAME_LEN in
-limit_ioccc.h).
-- If a directory is not readable it is an error.
-- If
prog.c, Makefile or remarks.md are not found it is an error.
-- If too many files that are not
prog.c, Makefile, remarks.md,
-try.sh, prog.alt.c or try.alt.sh are found, it is an error (see
-MAX_EXTRA_FILE_COUNT in
-limit_ioccc.h).
-
-- The user is presented with lists of files, symlinks and directories found.
-
-- Symlinks are ignored and may not be included. You will be warned about
-this.
-- Certain filenames (such as
README.md, index.html and various others)
-are forbidden and are not allowed. mkiocccentry(1) will warn and let you
-know about this.
-- Certain directories like
.git, CVS and other RCS related directories are not
-allowed but are ignored (and not descended into). You will be presented with
-a list of these directories.
-- No file or directory starting with
. will be allowed.
-- List of directories that will be made.
-- List of required and non-required files that will be added.
-- The user is asked to verify each list, including the list of files to be
-added, and if the user says it is not OK the program will abort.
-
-- The non-ignored files are copied under
-
workdir/submit.USERNAME-SLOT.TIMESTAMP (created prior to traversing the
-topdir), making sure to keep the files in their correct directory.
-
-- Directories are made prior to the copying of the files.
-- Directories MUST be (and will be made) with mode
0755.
-try.sh and try.alt.sh MUST be (and will be copied as) executable (in
-particular: mode 0555).- Other files MUST be (and will be copied as) mode
0444.
-txzchk(1) verifies these modes (and much more).
-cd submit.USERNAME-SLOT.TIMESTAMP.make -f Makefile clobber.
-
-- If this fails it is not an error but you are warned about it (even so, see
-Rule 20).
-
- Traverse the new tree from
., collecting files in the submission directory.
-
-- If an invalid file or directory is found it is an error.
-- If the depth is too deep it is an error.
-- If
prog.c, Makefile or remarks.md are missing (or not readable
-regular files) it is an error.
-iocccsize(1) (via the mkiocccentry(1) function check_prog_c()) will
-be run on your prog.c, allowing you to override any warnings; if you do not
-override an issue flagged it is an error but if warnings from check_prog_c()
-are ignored you risk violating the Rules, including Rule
-2.check_Makefile() will be run on Makefile; if it is a non-readable or
-empty file it is an error but otherwise you may override any warnings
-(risking violating the Rules, especially Rule
-17 and Rule 20).check_remarks_md() will be run on your remarks.m; if it is not a
-regular readable file or it is empty it is an error. Otherwise it will
-proceed. Note it does not check that there is any text in the file, just
-that the file size is not 0.- If a file is not a sane relative path it is an error (see the
-Rules and Guidelines for more
-details, and for even more details see the comments in the jparse function
-
sane_relative_path() in the
-jparse/util.c
-file at the mkiocccentry repo (this
-comes from the jparse repo).
-- If the path length (all components) are too long it is an error (see
-
MAX_PATH_LEN in
-limit_ioccc.h).
-- If a filename is too long it is an error (see
MAX_FILENAME_LEN in
-limit_ioccc.h).
-- If a directory is not readable it is an error.
-- If too many files that are not
prog.c, Makefile, remarks.md,
-try.sh, prog.alt.c or try.alt.sh are found, it is an error (see
-MAX_EXTRA_FILE_COUNT in
-limit_ioccc.h).
-
-- Report on files that were copied in (3) and directories made in (3) but are
-now gone: asking the user to verify.
-- Present the list of non-dot files that remain and ask the user to confirm.
-- Create the
.info.json and .auth.json files, running chkentry(1) on each.
-- List the submission directory contents, asking the user once again to verify
-everything is okay.
-- Form the tarball and run
txzchk(1) on it.
-
-
If any of the steps fail or if the user says something is not okay, it aborts.
Although the mkiocccentry(1) tool will verify everything for you, you may wish
to validate different parts individually with the different tools. As the
rules state, each of these tools has a -h option.
diff --git a/faq.md b/faq.md
index e197214f5..8b49a48df 100644
--- a/faq.md
+++ b/faq.md
@@ -1,6 +1,6 @@
# IOCCC FAQ Table of Contents
-This is FAQ version **28.2.6 2025-02-08**.
+This is FAQ version **28.2.7 2025-02-09**.
## 0. [Entering the IOCCC: the bare minimum you need to know](#enter_questions)
@@ -42,7 +42,7 @@ This is FAQ version **28.2.6 2025-02-08**.
## 3. [The mkiocccentry toolkit: finer details](#mkiocccentry_details)
-- **Q 3.0**:
What sort of checks does the mkiocccentry tool perform?
+- **Q 3.0**:
What is the `mkiocccentry(1)` process and what sort of checks does it perform?
- **Q 3.1**:
How can I validate my submission tarball?
- **Q 3.2**:
What is the `fnamchk` tool?
- **Q 3.3**:
How can I validate my `.auth.json` and/or `.info.json` files?
@@ -1208,13 +1208,114 @@ Jump to: [top](#)
Jump to: [top](#)
-
-### Q 3.0: What sort of checks does the mkiocccentry tool perform?
+
+### Q 3.0: What is the `mkiocccentry(1)` process and what sort of checks does it perform?
-In addition to the checks in the [mkiocccentry process](#mkiocccentry_process)
-described below, `mkiocccentry(1)` will check and warn about the following
-conditions:
+The `mkiocccentry(1)` tool performs the following steps:
+
+0. Ask the user for a submission ID (see the [quick-start
+guide](quick-start.html) for more details on how to obtain this).
+ * If this is an invalid UUID (malformed), it is an error.
+1. Ask the user for the submission slot (the submission number; see [Rule
+17](next/rules.html#rule17) for more details).
+ * If this is out of range it is an error (see `MAX_SUBMIT_SLOT` in
+ [limit_ioccc.h](https://github.com/ioccc-src/mkiocccentry/blob/master/soup/limit_ioccc.h)).
+3. Change to the `topdir`.
+4. Traverses the directory, creating lists of ignored
+files/directories/symlinks as well as a list directories to make and a list of
+files to copy to the submission directory.
+ * If the depth is too deep it is an error (see `MAX_PATH_DEPTH` in
+ [limit_ioccc.h](https://github.com/ioccc-src/mkiocccentry/blob/master/soup/limit_ioccc.h)).
+ * If there are too many directories it is an error (see `MAX_DIR_COUNT` in
+ [limit_ioccc.h](https://github.com/ioccc-src/mkiocccentry/blob/master/soup/limit_ioccc.h)).
+ * If a filename or directory name is not a sane relative path, not allowed
+ or will not be added for some other reason, it will be added to a relevant list to show to
+ the user later, to let them know it is ignored. By `relative` we mean it
+ must not start with `/` and by `sane` we mean that each component must match
+ the regexp: `^[0-9A-Za-z]+[0-9A-Za-z_+.-]*$`.
+ * If the path length (i.e. the entire length of the path from the `topdir`)
+ is too long it is an error (see `MAX_PATH_LEN` in
+ [limit_ioccc.h](https://github.com/ioccc-src/mkiocccentry/blob/master/soup/limit_ioccc.h)).
+ * If a filename is too long it is an error (see `MAX_FILENAME_LEN` in
+ [limit_ioccc.h](https://github.com/ioccc-src/mkiocccentry/blob/master/soup/limit_ioccc.h)).
+ * If there is an unknown error it is an error :-)
+ * If a path is NULL it is an error.
+ * If a path is an empty string it is an error.
+ * If the max path length is <= 0 it is an error (and a bug).
+ * If the max depth is <= 0 it is an error (and a bug).
+ * If the max filename length is <= 0 it is an error (and a bug).
+ * If a directory is not readable it is an error.
+ * If `prog.c`, `Makefile` or `remarks.md` is/are not found it is an error.
+ * If too many files that are not `prog.c`, `Makefile`, `remarks.md`,
+ `try.sh`, `prog.alt.c` or `try.alt.sh` are found, it is an error (see
+ `MAX_EXTRA_FILE_COUNT` in
+ [limit_ioccc.h](https://github.com/ioccc-src/mkiocccentry/blob/master/soup/limit_ioccc.h)).
+5. Show each list to the user, asking if this is okay. The lists include:
+ * Ignored directories (those like `.git`, `CVS`, `RCCS` and `.svn`).
+ * Unsafe directory names that will not be added (i.e. those that are not
+ POSIX plus + safe chars only; see above step (4)). This includes directories
+ starting with a `.`.
+ * Forbidden files such as `index.html`, `README.md`, `prog`, `prog.alt`.
+ * Unsafe filenames that will not be added (i.e. those that are not POSIX
+ plus + safe chars only; see above step (4)). This includes files starting
+ with `.`.
+ * Symlinks found (these are not allowed).
+ * Directories to be made.
+ * Required files (`prog.c`, `Makefile` and `remarks.md`) to be copied.
+ * Non-required files to be copied.
+ * The user is asked to verify each list, including the list of files to be
+ added, and if the user says it is not OK the program will abort.
+6. Make any directories if necessary (under
+`workdir/submit.USERNAME-SLOT.TIMESTAMP` i.e. the submission directory).
+ * Directories **MUST** be and are made with mode `0755`.
+ * If any directory is not this mode `txzchk(1)` will flag it.
+7. The non-ignored files are copied to their respective directories under the
+submission directory.
+ * `try.sh` and `try.alt.sh` MUST be and are copied as mode `0555`.
+ * All other files **MUST** be and are copied as mode `0444`.
+ * Anything else is an error and `txzchk(1)` will flag this.
+8. `cd submit.USERNAME-SLOT.TIMESTAMP` (i.e. switch to submission directory).
+9. `make -f Makefile clobber`.
+ * If this fails it is not an error but you are warned about it (even so, see
+ [Rule 20](next/rules.html#rule20)).
+10. Traverse the new tree from `.` with additional steps from (4).
+ * If any file has an ignored directory name in it, it is an error.
+ * If a symlink is found it is an error.
+ * If a forbidden filename exists it is an error.
+ * If any file or directory starts with `/` or is not POSIX plus + safe chars only it is an error.
+ * If the depth is too deep it is an error.
+ * If `prog.c`, `Makefile` or `remarks.md` are missing (or not readable
+ regular files) it is an error.
+ * `iocccsize(1)` (via the `mkiocccentry(1)` function `check_prog_c()`) will
+ be run on your `prog.c`, allowing you to override any warnings; if you do not
+ override an issue flagged it is an error but if warnings from `check_prog_c()`
+ are ignored you risk violating the [Rules](next/rules.html), including [Rule
+ 2](next/rules.html#rule2).
+ * `check_Makefile()` will be run on `Makefile`; if it is a non-readable or
+ empty file it is an error but otherwise you may override any warnings
+ (risking violating the [Rules](next/rules.html), especially [Rule
+ 17](next/rules.html#rule17) and [Rule 20](next/rules.html#rule20)).
+ * `check_remarks_md()` will be run on your `remarks.m`; if it is not a
+ regular readable file or it is empty it is an error. Otherwise it will
+ proceed. Note it does not check that there is any text in the file, just
+ that the file size is not 0.
+ * If any other error condition in step (4) occurs it is also an error.
+11. Report on files that were copied in (3) and directories made in (3) but are
+now gone: asking the user to verify.
+12. Present the list of non-dot files that remain and ask the user to confirm.
+13. Ask the user for a submission title.
+14. Ask the user for a one line abstract of the submission.
+15. Ask the user for the number of authors and for each author ask a variety of
+questions (see below for more information on what kind of questions).
+16. Show the output of `ls -lakR .`, asking the user to confirm that the listing
+is okay.
+17. Create the tarball.
+18. Run `txzchk(1)` on the tarball.
+
+If any of the steps fail or if the user says something is not okay, it aborts.
+
+Some of the checks that are made:
- If the files do not exist, are not regular files or cannot be read.
- If `prog.c` violates [Rule 2](next/rules.html#rule2) (see
@@ -1273,105 +1374,6 @@ has more than one `@` or is longer than `MAX_GITHUB_LEN` (see
not match the regexp `^[0-9A-Za-z][0-9A-Za-z._+-]*$`.
- An _author handle_ is repeated.
-
-#### `mkiocccentry` process
-
-
-The `mkiocccentry(1)` tool performs the following steps:
-
-0. Change to the `topdir`.
-1. Traverses the directory, gathering lists of ignored
-files/directories/symlinks as well as directories to make and files to copy
-to the submission directory.
- * If the depth is too deep it is an error (see `MAX_PATH_DEPTH` in
- [limit_ioccc.h](https://github.com/ioccc-src/mkiocccentry/blob/master/soup/limit_ioccc.h)).
- * If a filename or directory name is not a sane relative path, not allowed
- or will not be added for some reason, it will be added to a relevant list to show to
- the user later, to let them know it is ignored (see the
- [Rules](next/rules.html#) and [Guidelines](next/guidelines.html) for more details).
- * If the path length (all components) are too long it is an error (see
- `MAX_PATH_LEN` in
- [limit_ioccc.h](https://github.com/ioccc-src/mkiocccentry/blob/master/soup/limit_ioccc.h)).
- * If a filename is too long it is an error (see `MAX_FILENAME_LEN` in
- [limit_ioccc.h](https://github.com/ioccc-src/mkiocccentry/blob/master/soup/limit_ioccc.h)).
- * If a directory is not readable it is an error.
- * If `prog.c`, `Makefile` or `remarks.md` are not found it is an error.
- * If too many files that are not `prog.c`, `Makefile`, `remarks.md`,
- `try.sh`, `prog.alt.c` or `try.alt.sh` are found, it is an error (see
- `MAX_EXTRA_FILE_COUNT` in
- [limit_ioccc.h](https://github.com/ioccc-src/mkiocccentry/blob/master/soup/limit_ioccc.h)).
-2. The user is presented with lists of files, symlinks and directories found.
- * Symlinks are ignored and may not be included. You will be warned about
- this.
- * Certain filenames (such as `README.md`, `index.html` and various others)
- are forbidden and are not allowed. `mkiocccentry(1)` will warn and let you
- know about this.
- * Certain directories like `.git`, `CVS` and other RCS related directories are not
- allowed but are ignored (and not descended into). You will be presented with
- a list of these directories.
- * No file or directory starting with `.` will be allowed.
- * List of directories that will be made.
- * List of required and non-required files that will be added.
- * The user is asked to verify each list, including the list of files to be
- added, and if the user says it is not OK the program will abort.
-3. The non-ignored files are copied under
-`workdir/submit.USERNAME-SLOT.TIMESTAMP` (created prior to traversing the
-`topdir`), making sure to keep the files in their correct directory.
- * Directories are made prior to the copying of the files.
- * Directories **MUST** be (and will be made) with mode `0755`.
- * `try.sh` and `try.alt.sh` **MUST** be (and will be copied as) executable (in
- particular: mode `0555`).
- * Other files MUST be (and will be copied as) mode `0444`.
- * `txzchk(1)` verifies these modes (and much more).
-4. `cd submit.USERNAME-SLOT.TIMESTAMP`.
-5. `make -f Makefile clobber`.
- * If this fails it is not an error but you are warned about it (even so, see
- [Rule 20](next/rules.html#rule20)).
-6. Traverse the new tree from `.`, collecting files in the submission directory.
- * If an invalid file or directory is found it is an error.
- * If the depth is too deep it is an error.
- * If `prog.c`, `Makefile` or `remarks.md` are missing (or not readable
- regular files) it is an error.
- * `iocccsize(1)` (via the `mkiocccentry(1)` function `check_prog_c()`) will
- be run on your `prog.c`, allowing you to override any warnings; if you do not
- override an issue flagged it is an error but if warnings from `check_prog_c()`
- are ignored you risk violating the [Rules](next/rules.html), including [Rule
- 2](next/rules.html#rule2).
- * `check_Makefile()` will be run on `Makefile`; if it is a non-readable or
- empty file it is an error but otherwise you may override any warnings
- (risking violating the [Rules](next/rules.html), especially [Rule
- 17](next/rules.html#rule17) and [Rule 20](next/rules.html#rule20)).
- * `check_remarks_md()` will be run on your `remarks.m`; if it is not a
- regular readable file or it is empty it is an error. Otherwise it will
- proceed. Note it does not check that there is any text in the file, just
- that the file size is not 0.
- * If a file is not a sane relative path it is an error (see the
- [Rules](next/rules.html#) and [Guidelines](next/guidelines.html) for more
- details, and for even more details see the comments in the jparse function
- `sane_relative_path()` in the
- [jparse/util.c](https://github.com/ioccc-src/mkiocccentry/blob/master/jparse/util.c)
- file at the [mkiocccentry repo](https://github.com/ioccc-src/mkiocccentry]) (this
- comes from the [jparse repo](https://github.com/xexyl/jparse/)).
- * If the path length (all components) are too long it is an error (see
- `MAX_PATH_LEN` in
- [limit_ioccc.h](https://github.com/ioccc-src/mkiocccentry/blob/master/soup/limit_ioccc.h)).
- * If a filename is too long it is an error (see `MAX_FILENAME_LEN` in
- [limit_ioccc.h](https://github.com/ioccc-src/mkiocccentry/blob/master/soup/limit_ioccc.h)).
- * If a directory is not readable it is an error.
- * If too many files that are not `prog.c`, `Makefile`, `remarks.md`,
- `try.sh`, `prog.alt.c` or `try.alt.sh` are found, it is an error (see
- `MAX_EXTRA_FILE_COUNT` in
- [limit_ioccc.h](https://github.com/ioccc-src/mkiocccentry/blob/master/soup/limit_ioccc.h)).
-7. Report on files that were copied in (3) and directories made in (3) but are
-now gone: asking the user to verify.
-8. Present the list of non-dot files that remain and ask the user to confirm.
-9. Create the `.info.json` and `.auth.json` files, running `chkentry(1)` on each.
-10. List the submission directory contents, asking the user once again to verify
-everything is okay.
-11. Form the tarball and run `txzchk(1)` on it.
-
-If any of the steps fail or if the user says something is not okay, it aborts.
-
Although the `mkiocccentry(1)` tool will verify everything for you, you may wish
to validate different parts individually with the different tools. As the
[rules](next/rules.html) state, each of these tools has a `-h` option.
From f57acf1df6fb41e3be72c517a9a8c6c2e244c410 Mon Sep 17 00:00:00 2001
From: Cody Boone Ferguson <53008573+xexyl@users.noreply.github.com>
Date: Sun, 9 Feb 2025 13:54:06 -0800
Subject: [PATCH 15/16] Format fix in FAQ
---
faq.html | 9 +++------
faq.md | 5 ++---
2 files changed, 5 insertions(+), 9 deletions(-)
diff --git a/faq.html b/faq.html
index be77a7e0b..6f12bcabc 100644
--- a/faq.html
+++ b/faq.html
@@ -1470,11 +1470,9 @@ submission directory.
cd submit.USERNAME-SLOT.TIMESTAMP (i.e. switch to submission directory).make -f Makefile clobber.
-- If this fails it is not an error but you are warned about it (even so, see
-Rule 20).
+- If this fails it is not an error but you are warned about it (even so, see Rule 20).
-
- Traverse the new tree from
. with additional steps from (4).
-
+
- Traverse the new tree from
. with additional steps from (4).
- If any file has an ignored directory name in it, it is an error.
- If a symlink is found it is an error.
@@ -1497,8 +1495,7 @@ regular readable file or it is empty it is an error. Otherwise it will
proceed. Note it does not check that there is any text in the file, just
that the file size is not 0.
- If any other error condition in step (4) occurs it is also an error.
-
-
+
- Report on files that were copied in (3) and directories made in (3) but are
now gone: asking the user to verify.
- Present the list of non-dot files that remain and ask the user to confirm.
diff --git a/faq.md b/faq.md
index 8b49a48df..35ad3d7c6 100644
--- a/faq.md
+++ b/faq.md
@@ -1277,9 +1277,8 @@ submission directory.
* Anything else is an error and `txzchk(1)` will flag this.
8. `cd submit.USERNAME-SLOT.TIMESTAMP` (i.e. switch to submission directory).
9. `make -f Makefile clobber`.
- * If this fails it is not an error but you are warned about it (even so, see
- [Rule 20](next/rules.html#rule20)).
-10. Traverse the new tree from `.` with additional steps from (4).
+ * If this fails it is not an error but you are warned about it (even so, see [Rule 20](next/rules.html#rule20)).
+10. Traverse the new tree from `.` with additional steps from (4).
* If any file has an ignored directory name in it, it is an error.
* If a symlink is found it is an error.
* If a forbidden filename exists it is an error.
From 1c5f14f3e065cb79ac6ffd03a192c9aa89201d7d Mon Sep 17 00:00:00 2001
From: Cody Boone Ferguson <53008573+xexyl@users.noreply.github.com>
Date: Mon, 10 Feb 2025 13:28:41 -0800
Subject: [PATCH 16/16] More updates to FAQ for mkiocccentry process
Missing steps were added and other things which have changed (fixed)
have also bee noted.
There was also a typo fix in the rules.
---
faq.html | 154 ++++++++++++++++++++++++++++++-----------------
faq.md | 155 ++++++++++++++++++++++++++++++------------------
next/rules.html | 4 +-
next/rules.md | 4 +-
4 files changed, 198 insertions(+), 119 deletions(-)
diff --git a/faq.html b/faq.html
index 6f12bcabc..689213674 100644
--- a/faq.html
+++ b/faq.html
@@ -425,7 +425,7 @@
IOCCC FAQ Table of Contents
-This is FAQ version 28.2.7 2025-02-09.
+This is FAQ version 28.2.8 2025-02-10.
- Q 0.0: How can I enter the IOCCC?
@@ -1392,50 +1392,68 @@ Jump to: top
Q 3.0: What is the mkiocccentry(1) process and what sort of checks does it perform?
-The mkiocccentry(1) tool performs the following steps:
+In full, the mkiocccentry(1) tool performs the following steps:
-- Ask the user for a submission ID (see the quick-start
-guide for more details on how to obtain this).
+
- Ask the user for a submission ID (see the how to register
+for more details on how to obtain this and Rule 17 for
+the importance of this).
-- If this is an invalid UUID (malformed), it is an error.
+- If this is an invalid UUID (malformed), you will be asked to correct it
+until it is.
-- Ask the user for the submission slot (the submission number; see Rule
-17 for more details).
+
- Ask the user for the submission slot (the submission number; see how to
+register and Rule 17 for more details).
-- If this is out of range it is an error (see
MAX_SUBMIT_SLOT in
-limit_ioccc.h).
+- If this is out of range (see
MAX_SUBMIT_SLOT in
+limit_ioccc.h)
+and you will be asked to correct it until it is.
+
+- Make the submission directory under
topdir in the form of
+workdir/submit.USERNAME-SLOT.TIMESTAMP (the timestamp is calculated by
+mkiocccentry(1) so you do not have to worry about this).
+
+- If this directory already exists it is an error.
- Change to the
topdir.
-- Traverses the directory, creating lists of ignored
+
- Traverse the directory, creating lists of ignored/forbidden
files/directories/symlinks as well as a list directories to make and a list of
-files to copy to the submission directory.
+files to copy to the submission directory (and if (sub)directories are found
+with files, copy those files to their respective directory). Note the following:
- If the depth is too deep it is an error (see
MAX_PATH_DEPTH in
limit_ioccc.h).
-- If there are too many directories it is an error (see
MAX_DIR_COUNT in
+ - If there are too many extra directories (total count not including the
+submission directory itself, unrelated to
MAX_PATH_DEPTH above) it is an
+error (see MAX_EXTRA_DIR_COUNT in
limit_ioccc.h).
-- If a filename or directory name is not a sane relative path, not allowed
-or will not be added for some other reason, it will be added to a relevant list to show to
-the user later, to let them know it is ignored. By
relative we mean it
-must not start with / and by sane we mean that each component must match
-the regexp: ^[0-9A-Za-z]+[0-9A-Za-z_+.-]*$.
-- If the path length (i.e. the entire length of the path from the
topdir)
-is too long it is an error (see MAX_PATH_LEN in
-limit_ioccc.h).
-- If a filename is too long it is an error (see
MAX_FILENAME_LEN in
-limit_ioccc.h).
-- If there is an unknown error it is an error :-)
-- If a path is NULL it is an error.
-- If a path is an empty string it is an error.
- If the max path length is <= 0 it is an error (and a bug).
- If the max depth is <= 0 it is an error (and a bug).
- If the max filename length is <= 0 it is an error (and a bug).
-- If a directory is not readable it is an error.
+- If a path is NULL it is an error.
+- If a path is an empty string it is an error.
+- If the path length (i.e.
strlen(path) where path starts after the
+initial ./ of the path in the topdir) is too long it is an error (see MAX_PATH_LEN in
+limit_ioccc.h).
+- If a filename (last component of the path) is too long it is an error (see
MAX_FILENAME_LEN in
+limit_ioccc.h).
+- If a filename or directory name is not a sane relative path, not allowed
+or will not be added for some other reason, it will be added to a relevant list to show to
+the user later, to let them know it will not be added to the submission. By
relative we mean it
+must not start with / (which shouldn’t happen even if you give an absolute
+path) and by sane we mean that each component must match the regexp: ^[0-9A-Za-z]+[0-9A-Za-z_+.-]*$.
+- If a directory is unreadable it is an error.
+- If a directory causes a cycle in the tree it is an error.
+- If
stat(2) on the path fails it is an error.
- If
prog.c, Makefile or remarks.md is/are not found it is an error.
- If too many files that are not
prog.c, Makefile, remarks.md,
try.sh, prog.alt.c or try.alt.sh are found, it is an error (see
MAX_EXTRA_FILE_COUNT in
limit_ioccc.h).
+- Symlinks are not allowed but it is not an error (they will be added to a
+list and ignored).
+- If any file type other than a regular file, a directory or a symlink is
+encountered it is an error.
+- If there is an unknown error it is an error :-)
- Show each list to the user, asking if this is okay. The lists include:
@@ -1451,8 +1469,8 @@ with ..
- Directories to be made.
- Required files (
prog.c, Makefile and remarks.md) to be copied.
- Non-required files to be copied.
-- The user is asked to verify each list, including the list of files to be
-added, and if the user says it is not OK the program will abort.
+- The user is asked to verify each list, including the lists of directories
+and files to be made/copied, and if the user says it is not OK the program will abort.
- Make any directories if necessary (under
workdir/submit.USERNAME-SLOT.TIMESTAMP i.e. the submission directory).
@@ -1463,21 +1481,25 @@ added, and if the user says it is not OK the program will abort.
- The non-ignored files are copied to their respective directories under the
submission directory.
-try.sh and try.alt.sh MUST be and are copied as mode 0555.try.sh and try.alt.sh MUST be and are copied as mode 0555.- All other files MUST be and are copied as mode
0444.
-- Anything else is an error and
txzchk(1) will flag this.
+- Anything else will be flagged by
txzchk(1).
cd submit.USERNAME-SLOT.TIMESTAMP (i.e. switch to submission directory).make -f Makefile clobber.
-- If this fails it is not an error but you are warned about it (even so, see Rule 20).
+- If this fails it is not an error but you are warned about it (it is an error only if the
Makefile
+does not exist); even so, see Rule 20.
- Traverse the new tree from
. with additional steps from (4).
- If any file has an ignored directory name in it, it is an error.
- If a symlink is found it is an error.
+- If any file type other than a directory or regular file exists it is an
+error.
- If a forbidden filename exists it is an error.
-- If any file or directory starts with
/ or is not POSIX plus + safe chars only it is an error.
+- If any file or directory starts with
/ or is not POSIX plus + safe chars
+only (see (4) above) it is an error.
- If the depth is too deep it is an error.
- If
prog.c, Makefile or remarks.md are missing (or not readable
regular files) it is an error.
@@ -1493,11 +1515,13 @@ empty file it is an error but otherwise you may override any warnings
check_remarks_md() will be run on your remarks.m; if it is not a
regular readable file or it is empty it is an error. Otherwise it will
proceed. Note it does not check that there is any text in the file, just
-that the file size is not 0.- If any other error condition in step (4) occurs it is also an error.
+that the file size is not 0, and having a remarks.md that is not size 0
+but has no content is violating Rule 17 and Rule
+19.
+- If any other error condition from step (4) occurs it is also an error.
-- Report on files that were copied in (3) and directories made in (3) but are
-now gone: asking the user to verify.
+- Report on any directories that were made and files that were copied in (7)
+but are now gone: asking the user to verify.
- Present the list of non-dot files that remain and ask the user to confirm.
- Ask the user for a submission title.
- Ask the user for a one line abstract of the submission.
@@ -1505,36 +1529,49 @@ now gone: asking the user to verify.
questions (see below for more information on what kind of questions).
- Show the output of
ls -lakR ., asking the user to confirm that the listing
is okay.
+- Create
.info.json and run chkentry(1) on it.
+
+- If
chkentry(1) fails to validate the file make sure that you have
+obtained and compiled the latest version of all the tools and you either are
+in the repo’s directory, you pass the options to give the path to the tools
+or you have installed the latest tools!
+
+- Create
.auth.json and run chkentry(1) on it.
+
+- If
chkentry(1) fails to validate the file make sure that you have
+obtained and compiled the latest version of all the tools and you either are
+in the repo’s directory, you pass the options to give the path to the tools
+or you have installed the latest tools!
+
- Create the tarball.
- Run
txzchk(1) on the tarball.
-
If any of the steps fail or if the user says something is not okay, it aborts.
-
Some of the checks that are made:
+
If any of the steps fail or if the user says something is not okay, it aborts.
+Some of the other checks that are made:
-- If the files do not exist, are not regular files or cannot be read.
- If
prog.c violates Rule 2 (see
iocccsize.c).
-- If
prog.c is empty.
-- If
prog.c has any high bit char (see
-iocccsize.c).
-- If
prog.c has any NUL char (see
-iocccsize.c).
+- If
prog.c is empty (see Rule 1 and the
+Guidelines).
+- If
prog.c has any NUL (\0) char (see
+rule_count.c).
- If
prog.c has any unknown or invalid trigraph (see
-iocccsize.c).
+rule_count.c).
- If
prog.c triggers a word buffer overflow (see
-iocccsize.c).
+rule_count.c).
- If
prog.c triggers an ungetc(3) error (see
-iocccsize.c).
+rule_count.c).
- If the first rule in the
Makefile is not all.
- If the
Makefile does not have a clean rule.
- If the
Makefile does not have a clobber rule.
- If the
Makefile does not have a try rule.
-
If your Makefile is empty or remarks.md is empty it is an error and you will
-have to fix it.
-
Conditions that one must correct, and which mkiocccentry(1) will prompt until
+
Conditions that one MUST correct, and which mkiocccentry(1) will prompt until
they are correct, are:
+- Your contest ID is invalidly formed.
+- Your submit slot is < 0 or >
MAX_SUBMIT_SLOT (see
+limit_ioccc.h).
- Your title is not in the range of 1 through
MAX_TITLE_LEN chars (see
limit_ioccc.h).
- Your title does not match the regexp
^[0-9a-z][0-9a-z._+-]*$.
@@ -1545,8 +1582,7 @@ they are correct, are:
- An author name is not 1 through
MAX_NAME_LEN chars (see
limit_ioccc.h).
- Duplicate author name.
-- Country code is invalid (not ISO 3166-1 2 character
-codes).
+- Country code is invalid (i.e. it is not a ISO 3166-1 2 character code).
- An email, if provided, is not in the format of
x@y or
if x or y contain a @, are empty or if the total length is longer than
MAX_EMAIL_LEN (see limit_ioccc.h).
@@ -1556,10 +1592,10 @@ or https:// or is longer than MAX_URL_LEN chars (see
or does not have anything after the http:// or https://.
- A mastodon handle, if provided, is not in the form of
@user@site (i.e. starts with an @, has text following it and then another
-@ followed by more text and has no other @) or is longer than MAX_MASTODON_LEN (see
+@ followed by more text and has no other @), or if it is longer than MAX_MASTODON_LEN (see
limit_ioccc.h).
- A GitHub account, if provided, does not start with an
@,
-has more than one @ or is longer than MAX_GITHUB_LEN (see
+has more than one @, does not have any text after the @ or is longer than MAX_GITHUB_LEN (see
limit_ioccc.h).
- An affiliation, if provided, is longer than
MAX_AFFILIATION_LEN (see limit_ioccc.h).
@@ -1567,6 +1603,9 @@ has more than one @ or is longer than MAX_GITHUB_LEN (
not match the regexp ^[0-9A-Za-z][0-9A-Za-z._+-]*$.
- An author handle is repeated.
+
The program does confirm that the information for each author is correct,
+allowing you to correct the information without having to start the program
+over.
Although the mkiocccentry(1) tool will verify everything for you, you may wish
to validate different parts individually with the different tools. As the
rules state, each of these tools has a -h option.
@@ -1585,9 +1624,12 @@ FAQ on “
fnamchk”
for more details on the tools that
mkiocccentry either executes directly or
indirectly as part of the packaging process, especially if you wish to run one
or more of these tools manually.
+
See also the
+FAQ on “how to test everything at once without having to answer
+questions”.
See also the Guidelines and the Rules
-(especially Rule 2, Rule
-17, Rule 20).
+(especially
Rule 1,
Rule 2,
Rule
+17,
Rule 19 and
Rule 20).
Jump to: top
diff --git a/faq.md b/faq.md
index 35ad3d7c6..b23bb52fc 100644
--- a/faq.md
+++ b/faq.md
@@ -1,6 +1,6 @@
# IOCCC FAQ Table of Contents
-This is FAQ version **28.2.7 2025-02-09**.
+This is FAQ version **28.2.8 2025-02-10**.
## 0. [Entering the IOCCC: the bare minimum you need to know](#enter_questions)
@@ -1212,45 +1212,61 @@ Jump to: [top](#)
### Q 3.0: What is the `mkiocccentry(1)` process and what sort of checks does it perform?
-The `mkiocccentry(1)` tool performs the following steps:
+In full, the `mkiocccentry(1)` tool performs the following steps:
-0. Ask the user for a submission ID (see the [quick-start
-guide](quick-start.html) for more details on how to obtain this).
- * If this is an invalid UUID (malformed), it is an error.
-1. Ask the user for the submission slot (the submission number; see [Rule
-17](next/rules.html#rule17) for more details).
- * If this is out of range it is an error (see `MAX_SUBMIT_SLOT` in
- [limit_ioccc.h](https://github.com/ioccc-src/mkiocccentry/blob/master/soup/limit_ioccc.h)).
+0. Ask the user for a submission ID (see the [how to register](next/register.html)
+for more details on how to obtain this and [Rule 17](next/rules.html#rule17) for
+the importance of this).
+ * If this is an invalid UUID (malformed), you will be asked to correct it
+ until it is.
+1. Ask the user for the submission slot (the submission number; see [how to
+register](next/register.html) and [Rule 17](next/rules.html#rule17) for more details).
+ * If this is out of range (see `MAX_SUBMIT_SLOT` in
+ [limit_ioccc.h](https://github.com/ioccc-src/mkiocccentry/blob/master/soup/limit_ioccc.h))
+ and you will be asked to correct it until it is.
+2. Make the submission directory under `topdir` in the form of
+`workdir/submit.USERNAME-SLOT.TIMESTAMP` (the timestamp is calculated by
+`mkiocccentry(1)` so you do not have to worry about this).
+ * If this directory already exists it is an error.
3. Change to the `topdir`.
-4. Traverses the directory, creating lists of ignored
+4. Traverse the directory, creating lists of ignored/forbidden
files/directories/symlinks as well as a list directories to make and a list of
-files to copy to the submission directory.
+files to copy to the submission directory (and if (sub)directories are found
+with files, copy those files to their respective directory). Note the following:
* If the depth is too deep it is an error (see `MAX_PATH_DEPTH` in
[limit_ioccc.h](https://github.com/ioccc-src/mkiocccentry/blob/master/soup/limit_ioccc.h)).
- * If there are too many directories it is an error (see `MAX_DIR_COUNT` in
+ * If there are too many extra directories (total count not including the
+ submission directory itself, unrelated to `MAX_PATH_DEPTH` above) it is an
+ error (see `MAX_EXTRA_DIR_COUNT` in
+ [limit_ioccc.h](https://github.com/ioccc-src/mkiocccentry/blob/master/soup/limit_ioccc.h)).
+ * If the max path length is <= 0 it is an error (and a bug).
+ * If the max depth is <= 0 it is an error (and a bug).
+ * If the max filename length is <= 0 it is an error (and a bug).
+ * If a path is NULL it is an error.
+ * If a path is an empty string it is an error.
+ * If the path length (i.e. `strlen(path)` where path starts after the
+ initial `./` of the path in the `topdir`) is too long it is an error (see `MAX_PATH_LEN` in
+ [limit_ioccc.h](https://github.com/ioccc-src/mkiocccentry/blob/master/soup/limit_ioccc.h)).
+ * If a filename (last component of the path) is too long it is an error (see `MAX_FILENAME_LEN` in
[limit_ioccc.h](https://github.com/ioccc-src/mkiocccentry/blob/master/soup/limit_ioccc.h)).
* If a filename or directory name is not a sane relative path, not allowed
or will not be added for some other reason, it will be added to a relevant list to show to
- the user later, to let them know it is ignored. By `relative` we mean it
- must not start with `/` and by `sane` we mean that each component must match
- the regexp: `^[0-9A-Za-z]+[0-9A-Za-z_+.-]*$`.
- * If the path length (i.e. the entire length of the path from the `topdir`)
- is too long it is an error (see `MAX_PATH_LEN` in
- [limit_ioccc.h](https://github.com/ioccc-src/mkiocccentry/blob/master/soup/limit_ioccc.h)).
- * If a filename is too long it is an error (see `MAX_FILENAME_LEN` in
- [limit_ioccc.h](https://github.com/ioccc-src/mkiocccentry/blob/master/soup/limit_ioccc.h)).
- * If there is an unknown error it is an error :-)
- * If a path is NULL it is an error.
- * If a path is an empty string it is an error.
- * If the max path length is <= 0 it is an error (and a bug).
- * If the max depth is <= 0 it is an error (and a bug).
- * If the max filename length is <= 0 it is an error (and a bug).
- * If a directory is not readable it is an error.
+ the user later, to let them know it will not be added to the submission. By `relative` we mean it
+ must not start with `/` (which shouldn't happen even if you give an absolute
+ path) and by `sane` we mean that each component must match the regexp: `^[0-9A-Za-z]+[0-9A-Za-z_+.-]*$`.
+ * If a directory is unreadable it is an error.
+ * If a directory causes a cycle in the tree it is an error.
+ * If `stat(2)` on the path fails it is an error.
* If `prog.c`, `Makefile` or `remarks.md` is/are not found it is an error.
* If too many files that are not `prog.c`, `Makefile`, `remarks.md`,
`try.sh`, `prog.alt.c` or `try.alt.sh` are found, it is an error (see
`MAX_EXTRA_FILE_COUNT` in
[limit_ioccc.h](https://github.com/ioccc-src/mkiocccentry/blob/master/soup/limit_ioccc.h)).
+ * Symlinks are not allowed but it is not an error (they will be added to a
+ list and ignored).
+ * If any file type other than a regular file, a directory or a symlink is
+ encountered it is an error.
+ * If there is an unknown error it is an error :-)
5. Show each list to the user, asking if this is okay. The lists include:
* Ignored directories (those like `.git`, `CVS`, `RCCS` and `.svn`).
* Unsafe directory names that will not be added (i.e. those that are not
@@ -1264,25 +1280,29 @@ files to copy to the submission directory.
* Directories to be made.
* Required files (`prog.c`, `Makefile` and `remarks.md`) to be copied.
* Non-required files to be copied.
- * The user is asked to verify each list, including the list of files to be
- added, and if the user says it is not OK the program will abort.
+ * The user is asked to verify each list, including the lists of directories
+ and files to be made/copied, and if the user says it is not OK the program will abort.
6. Make any directories if necessary (under
`workdir/submit.USERNAME-SLOT.TIMESTAMP` i.e. the submission directory).
* Directories **MUST** be and are made with mode `0755`.
* If any directory is not this mode `txzchk(1)` will flag it.
7. The non-ignored files are copied to their respective directories under the
submission directory.
- * `try.sh` and `try.alt.sh` MUST be and are copied as mode `0555`.
+ * `try.sh` and `try.alt.sh` **MUST** be and are copied as mode `0555`.
* All other files **MUST** be and are copied as mode `0444`.
- * Anything else is an error and `txzchk(1)` will flag this.
+ * Anything else will be flagged by `txzchk(1)`.
8. `cd submit.USERNAME-SLOT.TIMESTAMP` (i.e. switch to submission directory).
9. `make -f Makefile clobber`.
- * If this fails it is not an error but you are warned about it (even so, see [Rule 20](next/rules.html#rule20)).
+ * If this fails it is not an error but you are warned about it (it is an error only if the `Makefile`
+ does not exist); even so, see [Rule 20](next/rules.html#rule20).
10. Traverse the new tree from `.` with additional steps from (4).
* If any file has an ignored directory name in it, it is an error.
* If a symlink is found it is an error.
+ * If any file type other than a directory or regular file exists it is an
+ error.
* If a forbidden filename exists it is an error.
- * If any file or directory starts with `/` or is not POSIX plus + safe chars only it is an error.
+ * If any file or directory starts with `/` or is not POSIX plus + safe chars
+ only (see (4) above) it is an error.
* If the depth is too deep it is an error.
* If `prog.c`, `Makefile` or `remarks.md` are missing (or not readable
regular files) it is an error.
@@ -1298,10 +1318,12 @@ submission directory.
* `check_remarks_md()` will be run on your `remarks.m`; if it is not a
regular readable file or it is empty it is an error. Otherwise it will
proceed. Note it does not check that there is any text in the file, just
- that the file size is not 0.
- * If any other error condition in step (4) occurs it is also an error.
-11. Report on files that were copied in (3) and directories made in (3) but are
-now gone: asking the user to verify.
+ that the file size is not 0, and having a `remarks.md` that is not size 0
+ but has no content is violating [Rule 17](next/rules.html#rule17) and [Rule
+ 19](next/rules.html#rule19).
+ * If any other error condition from step (4) occurs it is also an error.
+11. Report on any directories that were made and files that were copied in (7)
+but are now gone: asking the user to verify.
12. Present the list of non-dot files that remain and ask the user to confirm.
13. Ask the user for a submission title.
14. Ask the user for a one line abstract of the submission.
@@ -1309,38 +1331,46 @@ now gone: asking the user to verify.
questions (see below for more information on what kind of questions).
16. Show the output of `ls -lakR .`, asking the user to confirm that the listing
is okay.
-17. Create the tarball.
-18. Run `txzchk(1)` on the tarball.
+17. Create `.info.json` and run `chkentry(1)` on it.
+ * If `chkentry(1)` fails to validate the file make sure that you have
+ obtained and compiled the latest version of all the tools and you either are
+ in the repo's directory, you pass the options to give the path to the tools
+ or you have installed the latest tools!
+18. Create `.auth.json` and run `chkentry(1)` on it.
+ * If `chkentry(1)` fails to validate the file make sure that you have
+ obtained and compiled the latest version of all the tools and you either are
+ in the repo's directory, you pass the options to give the path to the tools
+ or you have installed the latest tools!
+19. Create the tarball.
+20. Run `txzchk(1)` on the tarball.
If any of the steps fail or if the user says something is not okay, it aborts.
+Some of the other checks that are made:
-Some of the checks that are made:
-
-- If the files do not exist, are not regular files or cannot be read.
- If `prog.c` violates [Rule 2](next/rules.html#rule2) (see
[iocccsize.c](https://github.com/ioccc-src/mkiocccentry/blob/master/iocccsize.c)).
-- If `prog.c` is empty.
-- If `prog.c` has any high bit char (see
-[iocccsize.c](https://github.com/ioccc-src/mkiocccentry/blob/master/iocccsize.c)).
-- If `prog.c` has any NUL char (see
-[iocccsize.c](https://github.com/ioccc-src/mkiocccentry/blob/master/iocccsize.c)).
+- If `prog.c` is empty (see [Rule 1](next/rules.html#rule1) and the
+[Guidelines](next/guidelines.html)).
+- If `prog.c` has any NUL (`\0`) char (see
+[rule_count.c](https://github.com/ioccc-src/mkiocccentry/blob/master/soup/rule_count.c)).
- If `prog.c` has any unknown or invalid trigraph (see
-[iocccsize.c](https://github.com/ioccc-src/mkiocccentry/blob/master/iocccsize.c)).
+[rule_count.c](https://github.com/ioccc-src/mkiocccentry/blob/master/soup/rule_count.c)).
- If `prog.c` triggers a word buffer overflow (see
-[iocccsize.c](https://github.com/ioccc-src/mkiocccentry/blob/master/iocccsize.c)).
+[rule_count.c](https://github.com/ioccc-src/mkiocccentry/blob/master/soup/rule_count.c)).
- If `prog.c` triggers an `ungetc(3)` error (see
-[iocccsize.c](https://github.com/ioccc-src/mkiocccentry/blob/master/iocccsize.c)).
+[rule_count.c](https://github.com/ioccc-src/mkiocccentry/blob/master/soup/rule_count.c)).
- If the first rule in the `Makefile` is not `all`.
- If the `Makefile` does not have a `clean` rule.
- If the `Makefile` does not have a `clobber` rule.
- If the `Makefile` does not have a `try` rule.
-If your `Makefile` is empty or `remarks.md` is empty it is an error and you will
-have to fix it.
-Conditions that one must correct, and which `mkiocccentry(1)` will prompt until
+Conditions that one **MUST** correct, and which `mkiocccentry(1)` will prompt until
they are correct, are:
+- Your _contest ID_ is invalidly formed.
+- Your _submit slot_ is < 0 or > `MAX_SUBMIT_SLOT` (see
+[limit_ioccc.h](https://github.com/ioccc-src/mkiocccentry/blob/master/soup/limit_ioccc.h)).
- Your _title_ is not in the range of 1 through `MAX_TITLE_LEN` chars (see
[limit_ioccc.h](https://github.com/ioccc-src/mkiocccentry/blob/master/soup/limit_ioccc.h)).
- Your _title_ does not match the regexp `^[0-9a-z][0-9a-z._+-]*$`.
@@ -1351,8 +1381,7 @@ they are correct, are:
- An author _name_ is not 1 through `MAX_NAME_LEN` chars (see
[limit_ioccc.h](https://github.com/ioccc-src/mkiocccentry/blob/master/soup/limit_ioccc.h)).
- Duplicate author _name_.
-- _Country code_ is invalid (not ISO 3166-1 2 character
-codes).
+- _Country code_ is invalid (i.e. it is not a ISO 3166-1 2 character code).
- An _email_, if provided, is not in the format of `x@y` or
if `x` or `y` contain a `@`, are empty or if the total length is longer than
`MAX_EMAIL_LEN` (see [limit_ioccc.h](https://github.com/ioccc-src/mkiocccentry/blob/master/soup/limit_ioccc.h)).
@@ -1362,10 +1391,10 @@ or `https://` or is longer than `MAX_URL_LEN` chars (see
or does not have anything after the `http://` or `https://`.
- A _mastodon handle_, if provided, is not in the form of
`@user@site` (i.e. starts with an `@`, has text following it and then another
-`@` followed by more text and has no other `@`) or is longer than `MAX_MASTODON_LEN` (see
+`@` followed by more text and has no other `@`), or if it is longer than `MAX_MASTODON_LEN` (see
[limit_ioccc.h](https://github.com/ioccc-src/mkiocccentry/blob/master/soup/limit_ioccc.h)).
- A _GitHub account_, if provided, does not start with an `@`,
-has more than one `@` or is longer than `MAX_GITHUB_LEN` (see
+has more than one `@`, does not have any text after the `@` or is longer than `MAX_GITHUB_LEN` (see
[limit_ioccc.h](https://github.com/ioccc-src/mkiocccentry/blob/master/soup/limit_ioccc.h)).
- An _affiliation_, if provided, is longer than
`MAX_AFFILIATION_LEN` (see [limit_ioccc.h](https://github.com/ioccc-src/mkiocccentry/blob/master/soup/limit_ioccc.h)).
@@ -1373,6 +1402,10 @@ has more than one `@` or is longer than `MAX_GITHUB_LEN` (see
not match the regexp `^[0-9A-Za-z][0-9A-Za-z._+-]*$`.
- An _author handle_ is repeated.
+The program does confirm that the information for each author is correct,
+allowing you to correct the information without having to start the program
+over.
+
Although the `mkiocccentry(1)` tool will verify everything for you, you may wish
to validate different parts individually with the different tools. As the
[rules](next/rules.html) state, each of these tools has a `-h` option.
@@ -1393,9 +1426,13 @@ for more details on the tools that `mkiocccentry` either executes directly or
indirectly as part of the packaging process, especially if you wish to run one
or more of these tools manually.
+See also the
+FAQ on "[how to test everything at once without having to answer
+questions](#mkiocccentry_test)".
+
See also the [Guidelines](next/guidelines.html) and the [Rules](next/rules.html)
-(especially [Rule 2](next/rules.html#rule2), [Rule
-17](next/rules.html#rule17), [Rule 20](next/rules.html#rule20)).
+(especially [Rule 1](next/rules.html#rule1), [Rule 2](next/rules.html#rule2), [Rule
+17](next/rules.html#rule17), [Rule 19](next/rules.html#rule19) and [Rule 20](next/rules.html#rule20)).
Jump to: [top](#)
diff --git a/next/rules.html b/next/rules.html
index 9e525a639..eac4b8e46 100644
--- a/next/rules.html
+++ b/next/rules.html
@@ -461,7 +461,7 @@ writing by
contacting the judges.
-These IOCCC rules are version 28.22 2025-02-08.
+These IOCCC rules are version 28.23 2025-02-10.
The markdown form of these rules
@@ -1295,7 +1295,7 @@ guidelines for additional markdown guidance.
make(1) compatibility the IOCCC
supports for more details.
-You are ENCOURAGED to use
+You are ENCOURAGED to use the
Makefile example, renamed as Makefile of course, for help in constructing your
Makefile. See the Makefile section in the
guidelines for more details.
diff --git a/next/rules.md b/next/rules.md
index 13d7dacb6..8dfc688f8 100644
--- a/next/rules.md
+++ b/next/rules.md
@@ -53,7 +53,7 @@ Jump to: [top](#)
-These [IOCCC rules](rules.html) are version **28.22 2025-02-08**.
+These [IOCCC rules](rules.html) are version **28.23 2025-02-10**.
@@ -1105,7 +1105,7 @@ make(1) compatibility the IOCCC
supports](../faq.html#make_compatibility) for more details.
-You are **ENCOURAGED** to use
+You are **ENCOURAGED** to use the
Makefile example, renamed as `Makefile` of course, for help in constructing your
`Makefile`. See the [Makefile section](guidelines.html#makefile) in the
guidelines for more details.