From d6f487224a224d7ae34f7db705706c0c1c86ee0c Mon Sep 17 00:00:00 2001 From: Landon Curt Noll Date: Wed, 21 Aug 2024 21:04:40 -0700 Subject: [PATCH] add Jump to: top below FAQ entries We add links to jump to the top of the file at the bottom of FAQ sections. Improved Makefile samples for FAQ 0.3. Performed `make faq` to accomplish the above and to test under macOS. --- faq.html | 114 ++++++++++++++++++++++++++++++-- faq.md | 197 +++++++++++++++++++++++++++++++++++++++++++++++++++++-- 2 files changed, 302 insertions(+), 9 deletions(-) diff --git a/faq.html b/faq.html index 906ef616e..b4c345b16 100644 --- a/faq.html +++ b/faq.html @@ -499,10 +499,12 @@ other inconsistencies with the original entry?
  • 6.16 - How do I find more information about a winning author of an entry?
  • 6.17 - What is a .entry.json file and how is it used?
    • +

    Jump to: top

    The IOCCC FAQ

    Section 0: Submitting entries to a new IOCCC

    +

    Jump to: top

    @@ -511,6 +513,7 @@ other inconsistencies with the original entry?

    To submit your code to the IOCCC, you MUST follow these steps:

    +

    Jump to: top

    0. Verify that the IOCCC is open for submissions

    Check the current status of the IOCCC see of the IOCCC is open.

    You may only register for the IOCCC when the IOCCC is OPEN.

    @@ -578,6 +581,7 @@ on how upload your entry to the IOCCC submit server. Once IOCCC submit server is ready, we will update this section with the proper instructions. Watch the IOCCC news for an announcement of the availability of the IOCCC submit server.

    +

    Jump to: top

    FAQ 0.1: What types of entries have been frequently submitted to the IOCCC?

    @@ -683,6 +687,7 @@ FAQ on “remarks.md”, why you are submitting a entry based on a frequently submitted theme and how compares with previous IOCCC winners of the same theme.

    +

    Jump to: top

    @@ -709,6 +714,7 @@ your Makefile should copy prog.c into the desired file

    For the make(1) connoisseur: As of 2023, IOCCC judges use GNU make compatible make(1) command that is compatible with GNU Make version 3.81.

    +

    Jump to: top

    FAQ 0.3: May I use a different source or compiled filename than prog.c or prog?

    @@ -716,24 +722,44 @@ command that is compatible with GNU Make version 3.81.

    While your entry’s source filename, as submitted, must be prog.c, your entry’s Makefile may copy prog.c to a different filename as part of the compiling/building process. For example:

    -
        all: desired_name
+
        ... Makefile continues above ...
+
+    all: desired_name
 
     desired_name: desired_name.c
+            rm -f $@
             cc desired_name.c -o $@
 
     desired_name.c: prog.c
             rm -f $@
             cp -f prog.c $@
 
-    clobber:
-            rm -f desired_name.c desired_name
    
+    clean:
+            rm -f desired_name.o
+
+    clobber: clobber
+            rm -f desired_name.c desired_name
+
+    ... Makefile continues below ...

    We recommend that the make clobber rule remove files that your entry creates as part of the compiling/building process.

    You may also copy the compiled prog into a different file as part of compiling process. For example:

    -
        different_name: prog
+
        ... Makefile continues above ...
+
+    all: desired_name
+
+    different_name: prog
             rm -f $@
-            cp -f prog $@
    
+            cp -f prog $@
+
+    clean:
+
+    clobber: clobber
+            rm -f desired_name
+
+    ... Makefile continues below ...
    +

    Jump to: top

    @@ -747,6 +773,7 @@ For example:

    system that conforms to the SUS, otherwise known as the The Single UNIX Specification Version 4 or later SUS.

    +

    Jump to: top

    @@ -770,6 +797,7 @@ If there is an on-going discussion that seems relevant to what you have to say, consider adding comments to that particular discussion. Otherwise consider opening a new mkiocccentry discussion.

    +

    Jump to: top

    @@ -817,6 +845,7 @@ information, they will ask (either in public or suggest a private conversation). others are wondering about as well!

    See also the FAQ on “rules, guidelines, tools feedback”.

    +

    Jump to: top

    @@ -835,6 +864,7 @@ start with some markdown content.

    as it lists things you should not use in markdown files.

    See the markdown syntax guide. See also CommonMark Spec.

    +

    Jump to: top

    FAQ 0.8: How do I report bugs in a mkiocccentry tool?

    @@ -848,6 +878,7 @@ page.

    Please see the FAQ on “reporting bugs and other issues in the mkiocccentry repo” in the mkiocccentry repo.

    +

    Jump to: top

    FAQ 0.9: What is a .auth.json file?

    @@ -1119,6 +1150,7 @@ valid by chkentry) your submission would be rejected for violating validate the .auth.json file.

    If you wish to verify that your .auth.json file is valid JSON then see the FAQ on “validating JSON documents”.

    +

    Jump to: top

    FAQ 0.10: What is a .info.json file?

    @@ -1554,6 +1586,7 @@ valid by chkentry) your submission would be rejected for violating validate the .info.json file.

    If you wish to verify that your .info.json file is valid JSON then see the FAQ on “validating JSON documents”.

    +

    Jump to: top

    @@ -1582,6 +1615,7 @@ verbosity with the -v option. For instance:

        jparse -v 3 foo.json

    If the tool is not installed then you will obviously have to specify the path of the tool.

    +

    Jump to: top

    @@ -1625,6 +1659,7 @@ JSON) but there is an issue in one or both of the it will report this as an error. Thus, if you were to package your submission manually then you would be violating Rule 17.

    +

    Jump to: top

    @@ -1652,6 +1687,7 @@ could do:

    of this document to discuss the many tests that txzchk(1) runs; if you must know we refer you to the source code.

    +

    Jump to: top

    @@ -1673,6 +1709,7 @@ you can do so. For instance:

    See also the FAQ on “validating your submission tarball” for more information.

    +

    Jump to: top

    FAQ 0.15 - What is the mkiocccentry tool and how do I use it?

    @@ -1811,6 +1848,7 @@ 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).

    +

    Jump to: top

    @@ -1832,9 +1870,11 @@ or more of these tools manually.

    See the mkiocccentry repo FAQ for more up to date information on downloading, compiling, and related FAQ information.

    +

    Jump to: top

    Section 1: History of the IOCCC

    +

    Jump to: top

    @@ -1899,6 +1939,7 @@ posting was International Obfuscated C and the tradition continues as the longest running contest on the Internet.

    P.S. Part of the inspiration for making the IOCCC a contest goes to the Bulwer-Lytton fiction contest.

    +

    Jump to: top

    FAQ 1.1: Why are some years missing IOCCC entries?

    @@ -1909,6 +1950,7 @@ and the tradition continues as the longest running contest on the Internet.

    do not permit us to hold a new IOCCC.

    The pause during the 2021-2023 period was due to the IOCCC judges developing tools to make is much more likely for the IOCCC to be held in a yearly basis later on.

    +

    Jump to: top

    @@ -2068,6 +2110,7 @@ of the IOCCC winner repo.

    On 202y mm dd, the temporary repo was merged back into the IOCCC winner repo resulting in many, many substantial improvements to the official IOCCC website.

    +

    Jump to: top

    @@ -2133,15 +2176,18 @@ to the official IOCCC website.

  • Rule 2a: 4993
  • Rule 2b: 2503
    • +

    Jump to: top

    Section 2: IOCCC Judging process

    +

    Jump to: top

    FAQ 2.0: How many entries do the judges receive for a given IOCCC?

    By tradition, we do not say.

    +

    Jump to: top

    @@ -2185,6 +2231,7 @@ rounds; we look at the author name only if an entry wins. See the guidelines if this is not clear!
  • leaving the remark section empty.
    • +

    Jump to: top

    FAQ 2.2: Why don’t you publish submissions that do not win?

    @@ -2193,6 +2240,7 @@ this is not clear!

    Because the publication on the IOCCC site IS the award! Anyone is free to put their IOCCC hopefuls, lookalikes and/or entries that do not win on their web page for everyone to see.

    +

    Jump to: top

    FAQ 2.3: How much time does it take to judge the contest?

    @@ -2210,6 +2258,7 @@ work as advertised, we might attempt to fix obvious compilation problems or incompatibilities, but no more than that - so be sure that your entry does work on at least a couple different platforms, at least one of them being UNIX or POSIX-conforming.

    +

    Jump to: top

    @@ -2224,6 +2273,7 @@ report when the IOCCC judges start near final judging rounds, and sometimes we also report when we enter what we believe is the final judging round, so you may guess that we have at least 3 rounds. :-) The actual number of rounds is certainly more than 3.

    +

    Jump to: top

    @@ -2267,6 +2317,7 @@ from the judges, they used the following awards:

    These could be considered the ‘best entry’ for those years with 1 or more other entries that came in close behind.

    +

    Jump to: top

    @@ -2290,9 +2341,11 @@ display this year’s winning IOCCC entries at the top of the IOCCC news page.

    +

    Jump to: top

    Section 3: Compiling and running IOCCC entries

    +

    Jump to: top

    @@ -2335,6 +2388,7 @@ enable or disable additional warnings or flags. Even so different versions or compilers might do different things, have different defects or other issues. Note that the Makefiles check the CC variable by substrings so that if you were to do something like make CC=gcc=mp-12 it would register as gcc.

    +

    Jump to: top

    @@ -2369,6 +2423,7 @@ for more information.

    It might also be worth noting that almost all entries, have been fixed so that they can compile in modern systems though just because an entry compiles does not mean it will run on your specific system.

    +

    Jump to: top

    @@ -2401,6 +2456,7 @@ FAQ on “fixing an entry” for details. See also the FAQ on “GitHub pull request” for more information about pull requests.

    +

    Jump to: top

    @@ -2420,6 +2476,7 @@ encourage you to submit a pull request with your ported code. Please see the FAQ on “fixing an entry” for details.

    +

    Jump to: top

    @@ -2446,6 +2503,7 @@ FAQ on “fixing an entry”. See also the FAQ on “GitHub pull request” for more information about pull requests.

    +

    Jump to: top

    FAQ 3.5: What is this cb tool that is mentioned in the IOCCC?

    @@ -2455,6 +2513,7 @@ for more information about pull requests.

    longer be available, code wise, except for Plan 9, but Plan 9 was never used for judging the IOCCC. A Unix man page for cb still exists.

    +

    Jump to: top

    @@ -2470,6 +2529,7 @@ judging the IOCCC. A Unix man page for cb usually away with stty echo. Sometimes you can also get away with stty sane. reset does the most but note that it will clear the screen (obviously clear will too but it won’t reset the terminal).

    +

    Jump to: top

    @@ -2622,6 +2682,7 @@ FAQ on “general X11”.

    See the FAQ on “X.org deprecated” for more information.

    +

    Jump to: top

    FAQ 3.8: How do I compile an IOCCC entry that requires SDL1 or SDL2?

    @@ -2684,6 +2745,7 @@ fix it and make a pull request.

    See the FAQ on “GitHub pull request” for more information about pull requests.

    +

    Jump to: top

    FAQ 3.9: How do I compile an IOCCC entry that requires (n)curses?

    @@ -2715,6 +2777,7 @@ packages: one for compiling and one for linking / running.

    Go to the ncurses website and follow their instructions for downloading, installing and using ncurses.

    We recommend trying a method suitable for your environment first, if possible.

    +

    Jump to: top

    @@ -2747,6 +2810,7 @@ include this here, at least for now.

    Other Linux distributions

    Usually the index.html file will explain how to use it under Linux so we do not include this here, at least for now.

    +

    Jump to: top

    FAQ 3.11: Why do Makefiles use -Weverything with clang?

    @@ -2820,6 +2884,7 @@ differences, try from 1989/westley:

    As you can see, using clang has some additional problems to work out but if you can get your entry to work well in clang it might very well be considered better than other entries.

    +

    Jump to: top

    @@ -2849,6 +2914,7 @@ to find what the intr is set to:

    … assuming of course that it’s a ctrl combination :-) If for some strange reason it’s not you might have to do something else including just piping it to just grep intr or whatever.

    +

    Jump to: top

    FAQ 3.13: Why does an IOCCC entry fail to compile and/or fail to run?

    @@ -2884,6 +2950,7 @@ request. Please see the FAQ on “fixing an entry” for how to submit a fix to an IOCCC entry.

    +

    Jump to: top

    FAQ 3.14 - How do I compile and install tcpserver for entries that require it?

    @@ -3183,9 +3250,11 @@ manually, sometimes the scripts will do additional things that you might miss and there are some other benefits as well which you would miss if you did not use them. Nevertheless, if you prefer to do it manually, whether to help you process or appreciate the entry more, then please do so.

    +

    Jump to: top

    Section 4: Changes made to IOCCC entries

    +

    Jump to: top

    FAQ 4.0: Why are some winning entry remarks incongruent with the winning IOCCC code?

    @@ -3202,6 +3271,7 @@ the original code when reading the author’s (and sometimes authors’) remarks

    See the FAQ on “original source code” for more information.

    +

    Jump to: top

    @@ -3238,6 +3308,7 @@ newline and gets() does not. As the Unix version 7 man page used to

    We’re not sure how this is compatibility but either way it can cause a problem and it is this that has complicated most of the fixes though again some can look almost identical.

    +

    Jump to: top

    FAQ 4.2: What was changed in an IOCCC entry source code?

    @@ -3342,6 +3413,7 @@ as no changes were made (there is an alt version for systems that are not VAX-11/PDP-11, however).

    See also the FAQ on “entry source code changes”

    +

    Jump to: top

    FAQ 4.4: What is the meaning of the file ending in .orig.c in IOCCC entries?

    @@ -3350,6 +3422,7 @@ FAQ on “entry source code changes”

    Due to the fact that the original code has sometimes had to change these files are the original winning entry or as close to as possible to the original that we can find.

    +

    Jump to: top

    @@ -3369,6 +3442,7 @@ judgement call.

    See the FAQ on “original source code” for more information.

    +

    Jump to: top

    @@ -3388,6 +3462,7 @@ changed to two.

    could no longer be so: main() instead had to call another function that has the body of the old main() and that function would call itself again. In some cases, however, this had to be done even without clang objections.

    +

    Jump to: top

    FAQ 4.7: Why were some filenames changed?

    @@ -3411,6 +3486,7 @@ method of how to display files was devised).

    Another example is for more consistency, sometimes to do with alternate code and other times something else.

    There were certainly other reasons as well.

    +

    Jump to: top

    @@ -3437,6 +3513,7 @@ back.

    In a few cases files were removed and there are multiple reasons for this too.

    The end result is to help improve the presentation of the entries in some way or ways.

    +

    Jump to: top

    FAQ 4.9:- What is the original source file?

    @@ -3474,9 +3551,11 @@ the source code as it is now now, try:

    See the FAQ on “what changed” for more information and make rules relating to “original source file” differences.

    +

    Jump to: top

    Section 5: Updating or correcting IOCCC website content

    +

    Jump to: top

    @@ -3498,6 +3577,7 @@ while a (mis)feature is not considered a bug and should not be fixedknown bugs file section may offer you important fixing clues.

    We welcome your help on fixing the IOCCC website

    +

    Jump to: top

    @@ -3522,6 +3602,7 @@ for information on how to submit a fix to an IOCCC entry. See also the FAQ on “GitHub pull request” for more information about pull requests.

    +

    Jump to: top

    @@ -3562,6 +3643,7 @@ FAQ on “GitHub pull request” for more information about pull requests.

    Note that we’re much more inclined to accept an author’s fixes but the judges have the final say in the matter.

    +

    Jump to: top

    @@ -3588,6 +3670,7 @@ issues to see if the problem has already been reported. If it has been reported, feel free to add a comment to the issue. Otherwise, if you do not see the same issue reported, then feel free to open a new IOCCC issue.

    +

    Jump to: top

    FAQ 5.4: How may I submit a fix to the IOCCC website?

    @@ -3772,6 +3855,7 @@ replace that text with:

        See the **author's description of the program** (sorry the content is no longer available) for more information.

    If you just wish to report the bad link issue, see FAQ on “report website problem”.

    +

    Jump to: top

    @@ -3791,6 +3875,7 @@ better for everyone. :-)

    If you wish to express your support and/or appreciation for our efforts, we suggest making an Anonymous gift via the IOCCC Amazon wishlist.

    +

    Jump to: top

    @@ -3871,9 +3956,11 @@ your deobfuscated code in the entry’s index.html happy to include any whatever notes and/or comments from your new discussion that be prove helpful.

    THANK YOU in advance for your willingness to assist!

    +

    Jump to: top

    Section 6: Miscellaneous IOCCC

    +

    Jump to: top

    @@ -3891,6 +3978,7 @@ original winning entries as compressed tar files for a given year.

    In some cases the entry may have abused rule 2 and declared an “abuse of the rules” (although now blatant abuse of the rules to get around rule 2 size limits is discouraged).

    +

    Jump to: top

    @@ -3905,6 +3993,7 @@ variety of kinds.

    Note that just because an entry is not in the bugs file does not mean there is not an issue and note that some issues are simply missing files, dead URL(s) or something like that.

    +

    Jump to: top

    @@ -3917,6 +4006,7 @@ something like that.

    We are not accepting mirror requests at this time, sorry. However you are free to fork the IOCCC winner repo. We do ask that your fork keep up to date with the latest changes when possible.

    +

    Jump to: top