Merge pull request #136 from xexyl/readmes

Many README.md files updated

1993/lmfjyh/README.md

@@ -9,9 +9,11 @@
 
         make all
 
-NOTE: This entry will not compile on modern systems because it
+NOTE: This entry will not compile on modern systems because it relies on a
-relies on a compiler bug which was fixed in gcc 2.3.3 (a very
+compiler bug which was fixed in gcc 2.3.3 (a very long time ago now). Trying to
-long time ago now).
+compile it will also make a bogus file on your file system.  To delete it you
+can use the inode option `-inum` with `find` with the delete option after
+finding the inode with `ls -li`.
 
 ### To run
 

1998/bas1/README.md

@@ -20,6 +20,7 @@
 
 	    ./bas1 | gunzip | gv -
 or:
+
 	    ./bas1 | gunzip | gs -sDEVICE=pgmraw -sOutputFile='|xv -' -
 
 ## Judges' comments
@@ -59,9 +60,9 @@
 =====
 
 Be sure to view the source with something that can display characters
-    \240-\377.  Use LESSCHARSET=latin1, M-x standard-display-european in
+`\240-\377`.  Use `LESSCHARSET=latin1`, `M-x` `standard-display-european` in
 GNU Emacs etc.  The source does not use characters in the range
-    \200-\237 (we are not an unnamed word processor that tends to create
+`\200-\237` (we are not an unnamed word processor that tends to create
 HTML containing these control characters).
 
 Because this is not the obfuscated postscript contest, the postscript
@@ -69,7 +70,7 @@
 logic is in the C code.  There are only a few straightforward "def"s,
 because otherwise the output would become much larger.
 
-    Try running Bemazing with command line arguments and see what
+Try running `Bemazing` with command line arguments and see what
 happens.  (But note that the program only guarantees that there
 actually is a route from entrance to exit if you run it without
 command line arguments.)

1998/bas2/README.md

@@ -10,13 +10,13 @@
 
         make all
 
-### To run
+### To run:
 
 	./bas2 < bas2.c
 
-## Judges' comments
+## Judges' comments:
 
-    Questions to ponder:
+### Questions to ponder:
 
 Can you determine the relationship between the input and the
 resulting numeric output?
@@ -24,7 +24,7 @@
 The program was not designed to process files with a certain
 octet value, what value is that?
 
-    Hint and Extra Credit:
+### Hint and Extra Credit:
 
 This entry points our a minor flaw in the IOCCC rules that has
 been around since 1992.  It processes a certain octet value in
@@ -32,7 +32,7 @@
 official IOCCC rules.  What is the rule and what is the octet
 value?
 
-## Author's comments
+## Author's comments:
 
 The main obfuscation is the way characters are recognized, which is
 done by matching the bit patterns.  Minor obfuscations are:
@@ -41,7 +41,7 @@
 
 - Useless variable names.
 
-    - Recursive main() instead of 2 loops (over input characters and over
+- Recursive main() instead of 2 loops (over input characters and over bits in
-    bits in the character).
+the character).
 
 - ? and || instead of if statements.

1998/chaos/README.md

@@ -1,4 +1,4 @@
-Best Object Orientation:
+# Best Object Orientation:
 
     Alan De Smet
     8531 Greenway Blvd. #206
@@ -8,39 +8,41 @@ Best Object Orientation:
     http://www.upl.cs.wisc.edu/~chaos/
 
 
-Judge's Comments:
+## To build:
-
-    To build:
 
 	make chaos
 
-    To use:
+NOTE: Some systems do not implement `halfdelay()` in their `libcurses`.
-
-	./chaos
-
-    This is the authors first IOCCC entry.  We thought the entry was
-    a nice example of a compact collection of obfuscations.
-
-    Can you figure our why, in some cases, it wants to read itself?
-
-    Some systems do not implement halfdelay() in their libcurses.
 You might try compiling with -lncurses of you have that library.
-    Or you can build this entry without the halfdelay() call by:
+Or you can build this entry without the `halfdelay()` call by:
 
 	make chaos_nohalf
 
 
-Selected Author's Comments:
+## To run:
 
 
-    * Usage
+	./chaos
+
+## Judge's Comments:
+
+This is the author's first IOCCC entry.  We thought the entry was
+a nice example of a compact collection of obfuscations.
+
+Can you figure our why, in some cases, it wants to read itself?
+
+
+## Selected Author's Comments:
+
+
+### Usage
 
 The executable takes a single argument for the data file to use.
 If no argument is given, it will find a data file by itself, don't
 worry about it...
 
 
-    * Summary
+### Summary
 
 This is a simple ncurses 3D object viewer. The keys 'y', 'u', 'i',
 'h', 'j', and 'k' rotate.  'a' and 'z' zoom in and out.  'q' quits.
@@ -48,7 +50,7 @@ Selected Author's Comments:
 interrupted by user input.
 
 
-    * Features (aka Bugs):
+### Features (aka Bugs):
 
 Memory malloced is never freed.  This shouldn't be a big deal,
 since only one block is ever allocated, and the OS should recover it.
@@ -63,7 +65,7 @@ Selected Author's Comments:
 the embedded string.  As a result, running the program without an
 external data file may act in undefined ways.
 
-    If the compiler doesn't store char * P's data in a nice contiguous
+If the compiler doesn't store `char * P`'s data in a nice contiguous
 stream, it would be bad.  As above, it would break running the
 program without an external data file.
 

1998/df/README.md

@@ -10,11 +10,11 @@
 
         make all
 
-### To run
+### To run:
 
 	./df
 
-## Judges' comments
+## Judges' comments;
 
 Everyone talks about how data hiding can produce clearer code; I am
 pleased to offer this charming refutation.
@@ -33,9 +33,9 @@
 
 Extra credit questions:
 
-	Where are the words stored?
+- Where are the words stored?
-	How many words does this entry use?
+- How many words does this entry use?
-	Can you add more words to the program and still make it work?
+- Can you add more words to the program and still make it work?
 
 ## Author's comments
 
@@ -54,12 +54,12 @@
 
 The source should compile with any ANSI C compiler (I used CodeWarrior
 w/ ANSI strict).  Using non-ANSI compilers that implement the ANSI
-    features it uses will not work (unless they defined __STDC__ 1
+features it uses will not work (unless they defined `__STDC__ 1`
 which they shouldn't). Due to space restrictions, I did not use
 any trigraph sequences.  It does not require any special -D defines.
 
 The source passes lint without any complaint (if invoked with
-    >/dev/null). (My lclint is unable to recover from some parts of it.)
+`>/dev/null`). (My lclint is unable to recover from some parts of it.)
 
 Actually, the code not only is compliant with the ANSI specifications,
 but uses a near minimum subset of them. C keywords that were not
@@ -73,9 +73,9 @@
 There wouldn't be any if I had been allowed to use some extra space
 for prototypes etc.
 
-    Multiple defines are used (but not all of them define), and #define
+Multiple defines are used (but not all of them define), and `#define
-    y define is used with #y but the code doesn't assume #y to expand
+y define` is used with `#y` but the code doesn't assume `#y` to expand
-    to #define. I have also included comments in the code, and vital
+to `#define`. I have also included comments in the code, and vital
 code in the comments. And of course there is code that doesn't do
 anything but will crash the program if it is removed (just like
 those comments I mentioned above). Additionally, since you said
@@ -86,12 +86,14 @@
 
 The executable needs its source file present in the current directory
 or, depending on your system, in your path. The name of the source
-    file is not hard-coded, __FILE__ is used instead.
+file is not hard-coded, `__FILE__` is used instead.
 
 In the original version which was sent in to the contest, there were
 some restrictions on the file name:
-	The second letter had to be a lowercase 'r'.
+
-	The third letter could never be a '+' or a 'b'.
+- The second letter had to be a lowercase 'r'.
+- The third letter could never be a '+' or a 'b'.
+
 Valid names would have been "pr4.c", "pr.c", "prog.c", "brownie.c" etc.
 My first private version would only run when compiled on a Friday.
 I decided it would be better this way...
@@ -126,17 +128,17 @@
 (because I extracted them from a dictionary :-)
 
 The file name had to fulfill the restrictions mentioned above
-    because __FILE__+1 was used as a second parameter to fopen(). (It
+because `__FILE__+1` was used as a second parameter to fopen(). (It
-    essentially was fopen(__FILE__,__FILE__+1) ). This was an extra joke
+essentially was `fopen(__FILE__,__FILE__+1)` ). This was an extra joke
 that does no longer exist in the released version.
 
-    You probably discovered that the while(FILE) in main is not a while loop
+You probably discovered that the `while(FILE)` in main is not a while loop
 but the statement that opens the file and initializes the dictionary.
 Similarly, int and signed have been redefined (to save space, of
 course).
 
 The main function (the guessing part) is between the last #else..#endif,
-    but still is declared before main(). The 5[O]() in main() calls
+but still is declared before main(). The `5[O]()` in main() calls
 this function.  Similarly, Most indexing operations have been
 changed to this form; and I tried to write each such operation
 different.

1998/dlowe/README.md

@@ -24,13 +24,14 @@
 To see why, try using an online version, modified for use as
 a CGI program:
 
-	http://pootpoot.com/poot/pootify?URL=http%3A%2F%2Fwww.microsoft.com
+	https://web.archive.org/web/20001025182142/http://pootpoot.com/poot/pootify?URL=http://www.microsoft.com
 
 We are sure that you will find that new web page to make a much
 more consistent level of quality.  :-)
 
 A CGI script such as:
 
+
 	#!/bin/sh
 	# pootify - a sample CGI pootifier
 	#
@@ -57,7 +58,7 @@
 
 For further information see:
 
-	http://pootpoot.com/poot/pootify?URL=http%3A%2F%2Fwww.ioccc.org
+	https://web.archive.org/web/20040326083431/http://www.pootpoot.com/poot/pootify/?URL=http%3A%2F%2Fwww.ioccc.org
 
 NOTE: The original entry was just a text based pootifier.  To build
 that version try:

1998/dloweneil/README.md

@@ -21,9 +21,9 @@
 Read the Author's comments below.  We believe that your experience may
 mirror one of our experiences:
 
-	Originally, I didn't appreciate the game.  Then I actually read the
+> Originally, I didn't appreciate the game.  Then I actually read the
-	description of the controls.  I started playing.  I struggled.
+> description of the controls.  I started playing.  I struggled.
-	I spelled my first "poot".  I was hooked ...
+> I spelled my first "poot".  I was hooked ...
 
 ## Author's comments
 
@@ -31,76 +31,102 @@
 
 	./pootris [X size of board] [Y size of board]
 
-    Synopsis:
+### Synopsis:
+
 The object of this game is to spell "POOT" as much as possible.  There
 is no time pressure.  You're given one letter at a time (sort of randomly
 chosen from the set 'P', 'O', and 'T') and you get to move it freely
 around the border of the playing board, and decide when and where to drop
 it into the board.  Sound easy?  Of course, there's a catch...
 
-    Controls:
+### Controls:
-     . Only three controls:
+
+     
+Only three controls:
+
 'a' moves the current letter one position counterclockwise around
     the border of the playing field.
 's' moves the current letter one position clockwise around the border
     of the playing field.
 'd' drops the current letter onto the board.
-     . To quit, send a fatal signal to the process.
 
-    Rules of motion:
+To quit, send a fatal signal to the process.
-     . The different letters move in different directions once dropped onto
-       the board:
-        'P' moves diagonally, at a 45 degree angle and in a clockwise
-            direction around the board once dropped.
-        'O' moves in a straight line perpendicular to the border from which
-            it is dropped.
-        'T' moves diagonally, at a 45 degree angle and in a counterclockwise
-            direction around the board once dropped.
-     . The letters bounce off the top and sides of the board.  They bounce
-       in a 'natural' way, with the exception that 'O's will fall straight
-       down if they hit a side wall.
-     . The letters stop when they hit another letter or the bottom of the
-       board.
 
-    Rules of spelling:
+### Rules of motion:
-     . When you spell 'POOT' on the board, in any direction, the letters
-       comprising the word will disappear, and any letters which may have
-       accumulated above the disappeared letters will 'fall'.
-     . Letters can be used in multiple spellings of 'POOT'.
-     . Chain reactions are possible.
 
-    Rules of scoring:
+The different letters move in different directions once dropped onto the board:
-     . You get one (1) point for each letter you drop onto the board.
-     . You get a bunch of points for spelling 'POOT'.  More if you spell
-       it in more than one way simultaneously.
 
-    Some of the obfuscations:
+'P' moves diagonally, at a 45 degree angle and in a clockwise direction around
-     . Several different coordinate systems are used.  There's the "real" X
+the board once dropped.
-       by Y system used for curses, the "inside the box" X by Y system used
+'O' moves in a straight line perpendicular to the border from which it is
-       for moving things around and finding instances of "POOT" inside the
+dropped.
-       box, and the position of the current letter, which is a single value
+'T' moves diagonally, at a 45 degree angle and in a counterclockwise direction
-       from 0 to 2 * xsize + 2 * ysize - 1.
+around the board once dropped.
-     . The fact that x%3 is a perfect hash function for x values 'P', 'O'
+
-       and 'T' is used.
+The letters bounce off the top and sides of the board.  They bounce in a
-     . Of course, the code is as hideous as possible, and spells poot for
+'natural' way, with the exception that 'O's will fall straight down if they hit
-       fun (It's also exactly 3217 bytes in length, with exactly 1536
+a side wall.
-       counted characters for purposes of this contest.)
+
-     . Love that modulus operator!  Mmmm...
+The letters stop when they hit another letter or the bottom of the board.
-     . There are some equations used which are really unnecessarily ugly,
+
-       which served the dual purposes of compacting the code and making it
+### Rules of spelling:
-       trickier to understand.  I'm thinking of the equations used to convert
+
-       between coordinate systems when dropping pieces into the game board.
+- When you spell 'POOT' on the board, in any direction, the letters comprising
-     . Simple and silly ones: short, meaningless (and sometimes misleading
+the word will disappear, and any letters which may have accumulated above the
-       (see 'x')) variable names; hard-coded ASCII numeric values used for
+disappeared letters will 'fall'.
-       character constants; using goto for fun and profit; reusing and
+
-       re-purposing variables in different places.
+- Letters can be used in multiple spellings of 'POOT'.
-     . The game itself is simple, but still weird and quite difficult.
+
+- Chain reactions are possible.
+
+### Rules of scoring:
+
+- You get one (1) point for each letter you drop onto the board.
+
+- You get a bunch of points for spelling 'POOT'.  More if you spell it in more
+than one way simultaneously.
+
+
+### Some of the obfuscations:
+
+- Several different coordinate systems are used.  There's the "real" X by Y
+system used for curses, the "inside the box" X by Y system used for moving
+things around and finding instances of "POOT" inside the box, and the position
+of the current letter, which is a single value from 0 to 2 * xsize + 2 * ysize -
+1.
+
+- The fact that x%3 is a perfect hash function for x values 'P', 'O' and 'T' is
+used.
+
+- Of course, the code is as hideous as possible, and spells poot for fun (It's
+also exactly 3217 bytes in length, with exactly 1536 counted characters for
+purposes of this contest.)
+
+- Love that modulus operator!  Mmmm...
+
+- There are some equations used which are really unnecessarily ugly, which
+served the dual purposes of compacting the code and making it trickier to
+understand.  I'm thinking of the equations used to convert between coordinate
+systems when dropping pieces into the game board.
+
+- Simple and silly ones: short, meaningless (and sometimes misleading (see 'x'))
+variable names; hard-coded ASCII numeric values used for character constants;
+using goto for fun and profit; reusing and re-purposing variables in different
+places.
+
+- The game itself is simple, but still weird and quite difficult.
+
+### Some things I wish I could have fit into this, but didn't have the space:
+
+- Seeding the random number generator (doh!)
+
+- Something to detect when the game is over.
+
+- Some kind of scoreboard.
+
+- Sound.
+
+- Some way of quitting gracefully.
 
-    Some things I wish I could have fit into this, but didn't have the space:
-     . Seeding the random number generator (doh!)
-     . Something to detect when the game is over.
-     . Some kind of scoreboard.
-     . Sound.
-     . Some way of quitting gracefully.
 
 Good Luck!

1998/schnitzi/README.md

@@ -15,7 +15,7 @@
 ### To run
 
 	./schnitzi 5 > sort.c
-	cc sort.c -o sort
+	make sort
 	echo 123 > data
 	echo 234 >> data
 	echo 413 >> data

2000/primenum/README.md

@@ -44,7 +44,7 @@ it successfully fooled half of the judges, including me.
 For 15 years, IOCCC winners have obfuscated programs using esoteric,
 difficult-to-interpret, confusing algorithms.  This entry finally bucks
 that trend and obfuscates in the most "obvious" way possible: by
-painstakenly describing the algorithm in clear pseudocode.  Even novice
+painstakingly describing the algorithm in clear pseudocode.  Even novice
 programmers will recognize that the program should find and print prime
 numbers up to a given number (as specified on the command line).
 

2004/anonymous/README.md

@@ -32,6 +32,20 @@ don't have a "pgm" viewer then we suggest the "netpbm" toolkit
 graphics format that you can view - most graphical Web browsers
 can display PNG or JPEG images.
 
+BTW: if you haven't read The Lord of the Rings what are you waiting for? :-) You'll
+find out the source of the text above though you'll see that there are some
+circumflexes missing! That's okay though due to I/O of the entry and in earlier
+drafts sometimes the û with an umlaut had a H added to it. The real text is:
+
+> Ash nazg durbatulûk, ash nazg gimbatul, ash nazg thrakatulûk, agh
+> burzum-ishi krimpatul.
+
+which when translated from Black Speech means:
+
+> One Ring to rule them all, One Ring to find them,
+> One Ring to bring them all and in the darkness bind them.
+
+
 p.s. Frodo lives!
 
 ## Author's comments:
@@ -42,7 +56,7 @@ transcription to standard output as a portable graymap (PGM) file.
 
 The specific transcription mode is the Black Speech Tengwar mode, as
 used in the inscription on the One Ring. The program handles the
-following diagraphs:
+following digraphs:
 
 - "gh", "sh", "th": the corresponding tengwar are output for these
   specific sounds

2004/arachnid/README.md

@@ -26,6 +26,12 @@ make
 ./arachnid arachnid.info
 ```
 
+and then try:
+
+```sh
+./arachnid arachnid.c
+```
+
 ## Judges' comments
 
 The fun part comes when you realize that the maze scrolls.  The overall

2004/gavin/README.md

@@ -16,7 +16,7 @@ make
 ### To run:
 
 ```sh
-./prog
+./gavin
 ```
 
 ### Try:
@@ -59,7 +59,7 @@ sh
 Can have several shell windows:
 
 ```sh
-vi gavin.hint
+vi README.md
 ./prim
 ```
 

2004/hibachi/README.md

@@ -17,13 +17,13 @@ make
 ### To run:
 
 ```sh
-./hibachi-start.sh
+cd build; ./hibachi-start.sh
 ```
 
 ### Try:
 
 ```sh
-./hibachi-start.sh
+cd build; ./hibachi-start.sh
 ```
 
 Then use your web browser to visit http://localhost:8008/

2004/sds/README.md

@@ -23,7 +23,7 @@ make
 
 ```sh
 ./sds < sds.c > encoder.c
-cc -o encoder encoder.c
+make encoder
 ./encoder sds.hint <sds.c >sds_msg.c
 ```
 

2004/vik2/README.md

@@ -16,7 +16,7 @@ make
 ### To run:
 
 ```sh
-./prog
+./vik2
 ```
 
 ### Try:

2005/aidan/README.md

@@ -13,13 +13,13 @@ make
 ### To run:
 
 ```sh
-./aidan
+./aidan < puzzle
 ```
 
 ### Try:
 
 ```sh
-echo "Do or do not. There is no try."
+./aidan < insane1.sudoku 
 ```
 
 ## Judges' comments:

2005/vik/README.md

@@ -28,7 +28,7 @@ make
 
 An amazing use of the X libraries with twisty code passages,
 all different.  One risks running in code path circles as main is
-called again and again.  be sure to pay attention to commas!  :-)
+called again and again. Be sure to pay attention to commas!  :-)
 
 ## Author's comments:
 
@@ -44,7 +44,7 @@ submitted with the entry.
 This program is a complete 3D engine with
 
   * Easy configurable maze maps
-  * Up to 26 differnt bitmap textures in a maze
+  * Up to 26 different bitmap textures in a maze
   * Support for animated bitmap textures
   * Uses default bitmaps in case the configured bitmaps can't be found
   * A default map in case no one is specified
@@ -54,7 +54,7 @@ backward)
 
 ### Build and Run
 
-Compile the source code and link x libraries if nessecary. The program takes
+Compile the source code and link x libraries if necessary. The program takes
 three options which have to be typed in a specific order as described below.
 
         Usage: prog [-w <width>] [mapfile]
@@ -79,7 +79,7 @@ Use the cursor keys to navigate through the labyrinth.
 
 A maze consist of a map file and texture bitmap files. The map file is an
 ascii text file where lower case letters represent walls. The letter tells the
-engine what bitmap texture file to use. The '*' character lets the engine know
+engine what bitmap texture file to use. The `'*'` character lets the engine know
 where to position the user. The example below shows how a map file can look:
 
        aaaaaaaaaaaaa
@@ -99,7 +99,7 @@ current directory).
 
 ### Obfuscation
 
-The program is obfuscated in several ways, bad use of variables, use of the ?
+The program is obfuscated in several ways, bad use of variables, use of the `?`
 operator, recursive calls to main, bad use of for variables and the comma
 operator. To make the final obfuscated touch I ran indent which really made
 the program unreadable (I guess that is not really the intent with indent ;)