Final edits before IOCCC28 (I hope :-) )

Renamed some FAQs (typos and/or other things). Fix a number of typos in various files (including markdown format errors). Rules and guidelines should be relatively good although as there is a lot to get through and not much time left maybe I missed something (I also kind of cheated doing the final checks with the guidelines rather than going through them all again). The next/try.sh and next/try.alt.sh scripts have had updates as well and the next/Makefile.example was modified too. The index.html page now has an anchor for goals of the contest so that the goals in the rules could simply link to it in index.html. Although some text had to be added (and some corrected) a reasonable amount of text was also removed as it was elsewhere or was extraneous in some way.
2025-03-04 12:11:08 -08:00
1 parent 4975257fa4
commit 49609b0ead
@@ -25,7 +25,7 @@ This is FAQ version **28.2.13 2025-03-01**.
 - **Q 1.3**: <a class="normal" href="#mkiocccentry_bugs">How do I report bugs in an `mkiocccentry` tool?</a>
 - **Q 1.4**: <a class="normal" href="#subdirectories">How may I use subdirectories in my submission if Rule 17 disallows them?</a>
 - **Q 1.5**: <a class="normal" href="#mkiocccentry_test">How can I check if my submission passes tests without having to answer questions?</a>
- **Q 1.6**: <a class="normal" href="#extra-files">How may I include additional files beyond the max allowed?</a>
+- **Q 1.6**: <a class="normal" href="#extra-files">What are extra files and how may I include additional files beyond the max allowed?</a>
 - **Q 1.7**: <a class="normal" href="#ai">May I use AI, Virtual coding assistants, or similar tools to write my submission?</a>
 - **Q 1.8**: <a class="normal" href="#rule17">What are the details behind Rule 17?</a>

@@ -129,7 +129,7 @@ This is FAQ version **28.2.13 2025-03-01**.
 - **Q 10.3**: <a class="normal" href="#dot_files"> What is the purpose of the `.top`, `.allyear`, `.year` and `.path` files?</a>
 - **Q 10.4**: <a class="normal" href="#terms"> What is the current meaning of the IOCCC terms Author, Entry, and Submission?</a>
 - **Q 10.5**: <a class="normal" href="#licence">Am I allowed to use IOCCC content?</a>
- **Q 10.6**: <a class="normal" href="#try_mastodon">What is Mastodon and why does IOCCC use it?</a>
+- **Q 10.6**: <a class="normal" href="#try_mastodon">What is Mastodon and why does the IOCCC use it?</a>
 - **Q 10.7**: <a class="normal" href="#tabstops">How do I set certain tabstops for viewing source code in vi&lpar;m&rpar;?</a>
 - **Q 10.8**: <a class="normal" href="#menus">How do the menus on the website work and what can I do if they don't work?</a>
 - **Q 10.9**: <a class="normal" href="#author-information">How do I find more information about a winning author of an entry?</a>
@@ -345,7 +345,7 @@ Jump to: [top](#)
 #### Q 0.1.5: How do I use mkiocccentry?
 </div>

-Once you have registered, you will need to package your entry with the
+Once you have registered, you will need to package your submission with the
 `mkiocccentry` tool. If you have not already obtained the toolkit, see the
 FAQ on "[obtaining the most recent mkiocccentry
 toolkit](#obtaining_mkiocccentry)",
@@ -585,7 +585,7 @@ If you have alternate code that you are including, then you can use the

 We recommend that you include the use of these scripts in the `try` rule in the
 example Makefile that you modify for your submission. See the
-FAQ on "[submission Makefiles](#makefile).
+FAQ on "[submission Makefiles](#makefile)".


 Jump to: [top](#)
@@ -759,12 +759,18 @@ Jump to: [top](#)
 </div>

 In order to submit a subdirectory, you may simply include a tarball. As long as
-the total size of your submission does not exceed the size limit, defined in
-[limit_ioccc.h](https://github.com/ioccc-src/mkiocccentry/blob/master/soup/limit_ioccc.h)
-as `MAX_TARBALL_LEN` and your total number of files in your xz compressed
-tarball does not exceed the limit, defined as `MAX_FILE_COUNT` in
-[limit_ioccc.h](https://github.com/ioccc-src/mkiocccentry/blob/master/soup/limit_ioccc.h),
-you can include tarballs with subdirectories or other files.
+the maximum depth of all files does not exceed the maximum, defined as
+`MAX_PATH_DEPTH`, the maximum filename length (a single component not counting
+the `/`) of all files does not exceed `MAX_FILENAME_LEN` and
+the maximum path length (all components) of all files does not exceed
+`MAX_PATH_LEN`. These macros are defined in
+[limit_ioccc.h](https://github.com/ioccc-src/mkiocccentry/blob/master/soup/limit_ioccc.h).
+
+
+See also the
+FAQ on "[Rule 17](#rule17)",
+the [guidelines](next/guidelines.html) and [Rule 17](next/rules.html#rule17)
+itself.

 <div id="mkiocccentry_test">
 #### Q 1.5: How can I check if my submission passes tests without having to answer questions?
@@ -782,7 +788,7 @@ do have to try again you'll have to remove it.
 An example use of this option is:

 ``` <!---sh-->
-    mkiocccentry -d test_work prog.c Makefile remarks.md
+    mkiocccentry -d workdir topdir
 ```

 This will run the tests that `mkiocccentry(1)`, write the JSON files, use
@@ -806,20 +812,27 @@ for more details.


 <div id="extra-files">
-# How may I include additional files beyond the max allowed?
+# What are extra files and how may I include additional files beyond the max allowed?
 </div>

-The rules state:
+<p class="leftbar">
+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 files that are also not the optional files (`try.sh`,
+`prog.alt.c` and `try.alt.sh`).
+</p>

-> 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.
-
-If you need to include more files than this, you may include a tarball as an
-**EXTRA** file.
+<p class="leftbar">
+**NOTE**: optional filenames are only optional if they are in the submission top
+level directory.
+</p>

+<p class="leftbar">
+If you need to include more files than this, you may include a tarball that
+itself is an extra file, meaning it counts **AS** an extra file.
 This file does **NOT** need to pass the `txzchk(1)` tests; only your submission
 tarball needs to pass these tests.
+</p>

 Please pay careful attention to [Rule 17](next/rules.html#rule17) and in
 particular the part about the [maximum number of files per
@@ -845,18 +858,20 @@ Jump to: [top](#)


 <div id="ai">
-### Q 1.7: May I use AI, Virtual coding assistants, or similar tools to write my submission?
+<div id="llm">
+### Q 1.7: May I use AI, LLM, Virtual coding assistants, or similar tools to write my submission?
+</div>
 </div>

 You are free to use whatever tools you wish to write your code.
-This includes tools that are AI based, Virtual coding assistants, code
-generators, or similar tools, as well as your own tools.  The [IOCCC
-judges](https://www.ioccc.org/judges.html) do not discriminate on the
-basis of the tools used to write obfuscated C code so long as you are
-the ultimate author of the code you submit.
+This includes tools that are AI based, LLM (large language model), Virtual
+coding assistants, code generators, or similar tools, as well as your own tools.
+The [IOCCC judges](https://www.ioccc.org/judges.html) do not discriminate on the
+basis of the tools used to write obfuscated C code so long as you are the
+ultimate author of the code you submit.

-If you do use such tools, **PLEASE mention** which tools you used as well
-as how you them to help write you submission in your `remarks.md` file.
+If you do use such tools, **PLEASE mention** in your `remarks.md` which tools
+you used as well as how you used them to help write your submission.

 Jump to: [top](#)

@@ -865,9 +880,6 @@ Jump to: [top](#)
 ### Q 1.8: What are details behind Rule 17?
 </div>

-The following are the details behind [Rule 17](next/rules.html#rule17).
-
-
 ### TL;DR Rule 17 - Use `mkiocccentry(1)`

 <p class="leftbar">
@@ -883,41 +895,25 @@ The [mkiocccentry repo](https://github.com/ioccc-src/mkiocccentry)
 contains **IMPORTANT** tools and libraries such as:
 </p>

-* <p class="leftbar">`chkentry(1)`</p>
-* <p class="leftbar">`iocccsize(1)`</p>
 * <p class="leftbar">`mkiocccentry(1)`</p>
+* <p class="leftbar">`iocccsize(1)`</p>
 * <p class="leftbar">`txzchk(1)`</p>
 * <p class="leftbar">`fnamchk(1)`</p>
-* <p class="leftbar">`jparse(1)` (and other tools) and `jparse(3)` (which `chkentry(1)` uses)</p>
+* <p class="leftbar">`jparse(3)`</p>
+* <p class="leftbar">`chkentry(1)` (which uses `jparse(3)`)</p>

 <p class="leftbar">
 The above mentioned tools will help you verify that your submission
-conforms to [Rule 17](next/rules.html#rule17).
-</p>
-
-<p class="leftbar">
-Each above mentioned tool has a `-h` option that provides command line help. For
-additional details of each tool, see its man page, and in some cases, the [IOCCC
-guidelines](next/guidelines.html).
+conforms to [Rule 17](next/rules.html#rule17).  Each of these tool has a `-h`
+option that provides command line help. For additional details of each tool, see
+its man page, and in some cases, the [IOCCC guidelines](next/guidelines.html).
 </p>

 <p class="leftbar">
 The maximum number of **extra files** is 31. See the [maximum number of extra
 files section](#max-files) below for finer details and the
-FAQ on "[including additional files](#extra-files)"
-if you need to include more files than this maximum.
-</p>
-
-<p class="leftbar">
-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 files that are also not the optional files (`try.sh`,
-`prog.alt.c` and `try.alt.sh`).
-</p>
-
-<p class="leftbar">
-**NOTE**: optional filenames are only optional if they are in the submission top
-level directory.
+FAQ on "[what extra files are and how to include additional files](#extra-files)",
+should you need to include more files than this maximum.
 </p>

 Jump to: [top](#)
@@ -926,8 +922,8 @@ Jump to: [top](#)
 ### Rule 17 - The COMPLEX details

 <p class="leftbar">
-Each submission **MUST** be in the form of a xz compressed tarball.
-The xz compressed tarball filename must be of the form:
+Each submission **MUST** be in the form of an xz compressed tarball.
+The xz compressed tarball filename **MUST** be of the form:
 `^submit.username-slot_num.[1-9][0-9]{9,}.txz$`.

 <p class="leftbar">
@@ -942,12 +938,11 @@ details), and where _`slot_num`_ is a single decimal digit integer
 In particular, `username` is in the form of:
 `xxxxxxxx-xxxx-4xxx-Nxxx-xxxxxxxxxxxx` where `'x'` is a hex digit in the range
 of `[0-9a-f]`, 4 is the UUID version, and `N` is one of `8`, `9`, `a`, or `b`.
-And yes, there is a 4 (UUID version 4) and the variants `0x8`, `0x9`, `0xa` and
-`0xb` in there.
 </p>

 <p class="leftbar">
-Your xz compressed tarball **MUST** contain, **at a minimum**, the following files:
+Your xz compressed tarball **MUST** contain, **at a minimum**, the following
+files, in the **TOP LEVEL** directory:
 </p>

 * <p class="leftbar">`prog.c`</p>
@@ -965,9 +960,9 @@ The `Makefile` **MUST** be a **non**-empty file in **[GNU
 Makefile](https://www.gnu.org/software/make/manual/make.html)** format. See the
 [Makefile section in the guidelines](next/guidelines.html#makefile),
 the
-FAQ on "[submission Makefile](#submission_makefiles)"
+FAQ on "[submission Makefiles](#submission_makefile)"
 and the
-FAQ on "[Makefile compatibility](#make_compatibility)"
+FAQ on "[IOCCC make&lpar;1&rpar; compatibility](#make_compatibility)"
 for help.
 </p>

@@ -976,8 +971,8 @@ The `remarks.md` **MUST** be a **non**-empty file in markdown format
 (`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](next/rules.html#rule18) and our
-FAQ on "[remarks.md](#remarks_md)"
-and our
+FAQ on "[remarks.md](#remarks_md)",
+our
 FAQ on "[markdown](#markdown)"
 and our [markdown guidelines](markdown.html).
 </p>
@@ -1003,7 +998,7 @@ about the submission itself. It also **MUST** be valid according to **BOTH**

 <p class="leftbar">
 For the complete `mkiocccentry(1)` process, see the
-FAQ on the "[mkiocccentry process](#mkiocccentry_process).
+FAQ on the "[mkiocccentry process](#mkiocccentry_process)".
 </p>

 <p class="leftbar">
@@ -1013,7 +1008,7 @@ and try again.
 </p>

 <p class="leftbar">
-On the other hand, some issues are errors and you **MUST** fix those).
+On the other hand, some issues are errors and you **MUST** fix those.
 </p>

 <p class="leftbar">
@@ -1043,31 +1038,32 @@ rule.
 </p>

 <p class="leftbar">
-Your submission's xz compressed tarball **MUST** pass the `txzchk(1)` test. See
-the [guidelines](next/guidelines.html) for more details on this tool.
+Your submission's xz compressed tarball **MUST** pass the `txzchk(1)` tests. See
+the [guidelines on txzchk&lpar;1&rpar;](next/guidelines.html#txzchk) for more details on this tool.
 </p>

 <p class="leftbar">
 **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
 this rule! See the
-FAQ on "[obtaining the mkiocccentry toolkit](#mkiocccentry)"
+FAQs on "[obtaining, compiling, installing and using the mkiocccentry toolkit](#mkiocccentry)"
 for more details.
 </p>


 <p class="leftbar">
 You are **HIGHLY ENCOURAGED** to use the `mkiocccentry(1)` tool to form your
-submission's xz compressed tarball. See the [guidelines](next/guidelines.html) for
-more details on this tool and the [mkiocccentry
-repo](https://github.com/ioccc-src/mkiocccentry).
+submission's xz compressed tarball. See the [guidelines on
+mkiocccentry&lpar;1&rpar;](next/guidelines.html#mkiocccentry) for
+more details on this tool and see the [mkiocccentry
+repo](https://github.com/ioccc-src/mkiocccentry) for the toolkit itself.
 </p>

 <p class="leftbar">
 Your entry **MAY** have subdirectories, depending on the depth and total length of
 the filenames. Certain directories like `.git`, `RCCS`, `CVS` and `.svn`
 (amongst others) are skipped. For more information, see the
-[guidelines](next/guidelines.html).
+FAQ on "[subdirectories](#subdirectories)".
 </p>

 <p class="leftbar">
@@ -1081,11 +1077,11 @@ it or any other tool invokes, files in your submission **MUST**:
 the exception of files generated by `mkiocccentry(1)` itself, it must have
 **NO** dot file including `.` itself).</p>
 * <p class="leftbar">**NOT** contain a path component of: **`..`** (that is,
-**NO** **`..`**).</p>
+**NO** path component that matches the regular expression **`^..$`**).</p>
 * <p class="leftbar">Match the regular expression
 `^[0-9A-Za-z]+[0-9A-Za-z_+.-]*$` (again, excluding files generated by
 `mkiocccentry(1)`).</p>
-* <p class="leftbar">**NOT** have a directory depth > 4.</p>
+* <p class="leftbar">**NOT** have a directory/file depth > 4.</p>
 * <p class="leftbar">**NOT** have a total **path** length > 99 characters.</p>

 <p class="leftbar">
@@ -1107,12 +1103,15 @@ tarball.
 <p class="leftbar">
 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, not counting
+**MUST** be `drwxr-xr-x` (i.e. `0755`); the optional files, not counting
 `prog.alt.c` (i.e. `try.sh` and `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](next/rules.html#rule17)! In addition to
-`mkiocccentry(1)` creating and copying the directories and files with these
+`-r-xr-xr-x` (i.e. `0555`); and all other files **MUST** be `-r--r--r--` (i.e.
+`0444`).  If any file or directory does not have the correct permissions, your submission **WILL**
+be rejected for violating [Rule 17](next/rules.html#rule17)!
+</p>
+
+<p class="leftbar">
+After `mkiocccentry(1)` creates the directories and copies the files with these
 modes, it also verifies them after the fact and if they are not correct it is an
 **error**.
 </p>
@@ -1166,7 +1165,7 @@ 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
-FAQ on "[how to include additional files](#extra-files)"
+FAQ on "[what extra files are and how to include more](#extra-files)"
 if you need to include more files.
 </p>

@@ -7085,7 +7084,7 @@ and this may help clarify some aspects of the

 The [Copyright and CC BY-SA 4.0 License](#copyright) applies to all
 IOCCC content.  We use this to help ensure that we can all
-enjoy hat those working on the IOCCC have proper Attribution
+enjoy that those working on the IOCCC have proper Attribution
 including, of course, the IOCCC winners themselves!  It is designed
 to help ensure that everyone may enjoy the IOCCC.

@@ -7093,7 +7092,7 @@ Jump to: [top](#)


 <div id="try_mastodon">
-### Q 10.6: What is Mastodon and why does IOCCC use it?
+### Q 10.6: What is Mastodon and why does the IOCCC use it?
 </div>

 The [IOCCC uses Mastodon](https://fosstodon.org/@ioccc) for news updates,