Rename hint.txt and hint.text to README.md

2020/yang/README.md

@@ -0,0 +1,141 @@
+# Best abuse of CPP
+
+Don Yang  
+<http://uguu.org/>  
+
+
+The code for this entry can be found in prog.c
+
+## Judges' comments:
+### To use:
+
+    make
+    ./prog
+
+### Try:
+
+    echo "International Obfuscated C Code Contest 2020" | ./prog 23209 > code.c
+
+    # compile without a PIN
+    cc code.c -o decode
+    # yes, you must compile with -DPIN=<number>
+
+    # compile with the wrong pin
+    cc -DPIN=555 code.c -o wrongcoded	 # wait for it ...
+    ./wrongcoded | hexdump -C
+    # Use the wrong PIN: You're gonna have a bad time.
+
+    # compile with a PIN
+    cc -DPIN=23209 code.c -o decoded	# wait for it ...
+    ./decoded
+    # weeeeeeeeeeeeee! You are having a good time!
+
+### Selected Judges Remarks:
+
+You might think of this entry as code obfuscater with a code.
+If you use the wrong code, you're gonna have a bad time.
+What is compiling this entry about?
+[Having a good .. time](https://southpark.fandom.com/wiki/Asspen/Script)!
+
+This winning entry also comes with a [JavaScript timelapse
+spoiler](spoiler.html) that shows how this entry was written.
+
+
+## Author's comments:
+### Synopsis
+
+    echo "Hello world" | ./mile 12345 > encoded.c
+
+    gcc -DPIN=12345 encoded.c -o ./decoded && ./decoded
+
+### Details
+
+Mile is a C code generator.  Run without arguments for the help message below:
+
+    usage: [PIN] < input.txt > output.c
+
+    where [PIN] is an integer in the range of 1..65535
+
+When run with an encoding PIN (first command line argument), Mile will
+read bytes from stdin and generate C code on stdout.  Example:
+
+    echo "Hello, world!" | ./mile 56789 > encoded.c
+
+This generated code will reproduce the same input bytes on stdout when
+executed, if it was compiled with the same encoding PIN.
+
+    gcc -DPIN=56789 encode.c -o decoded
+
+The generated code reconstructs all data at compile time by seeding a
+random number generator with the given PIN to reproduce the input bytes,
+and simply does one fwrite() call at run time to print those bytes.  Not
+specifying a PIN is a compile time error.  Specify the wrong PIN and
+output code will still compile, but will likely produce garbage instead of
+the input bytes.  If the original input was empty then any PIN works, but
+you might get a compile time warning complaining about empty arrays.
+
+Because all data is reconstructed at compile time, expect the compile time
+to be excruciatingly long if you try to encode too much data.  Code
+generated by encoding a haiku will probably compile in seconds, a limerick
+may require tens of seconds, a sonnet will take minutes.  Give Mile an
+epic poem and you can probably write a faster preprocessor before GCC is
+done (Clang probably already failed long before then).
+
+I see that there is a lack of preprocessor abuse in recent years, probably
+because programming in preprocessor is too tedious.  Mile is meant to help
+with that by producing C code filled with at least 98% preprocessor lines
+for any input.  Now you too can enjoy long compile times with minimal
+effort.
+
+### Features
+
++ Output is randomized using system clock, so if you wait a second between
+  runs, you should get a different generated code even for the same
+  encoding PIN.
+
++ Customized bytecode encoding of preprocessor boilerplates, mostly for
+  compression but should also make reverse engineering more fun.
+
++ CRC32 of the source code is embedded in the source code itself.
+
++ Code layout shaped to resemble "Mile" from "Didn't I Say to Make My
+  Abilities Average in the Next Life?!".  Mile is known to be able to talk
+  to nanomachines directly, which is exactly what programming in
+  preprocessor feels like.
+
+### Compatibility
+
+Mile has been verified to work in these environments (also, compiles
+without warnings on all of these):
+
++ gcc 9.2.0 on Cygwin
++ gcc 8.3.0 on Linux
++ gcc 7.4.0 on Cygwin
++ gcc 6.1.0 on JSLinux
++ gcc 5.4.0 on Linux
++ clang 8.0.1 on Linux
++ clang 8.0.1 on Cygwin
++ tcc 0.9.27 on Linux
++ tcc 0.9.25 on JSLinux
+
+Output of Mile is a bit more taxing, and only works with a subset of the
+above:
+
++ gcc: works just fine when using 8.3.0 and below, but may trigger warning
+  for large files.  gcc 9.2.0 and above may crash with large files.
++ clang: works fine for small files, fails on large files due to
+  [preprocessor bug](https://bugs.llvm.org/show_bug.cgi?id=44480).
++ tcc: works just fine on Linux.  Fails silently on JSLinux.
+
+For people eager to encode large files, an extra utility has been packaged
+with this entry to preprocess the generated output to make them more
+acceptable to typical compilers.  View the [cppp.cc](cppp.cc) source and
+then compile it with a c++ compiler of your choice.
+
+-----------------------------------------------------------------------------------------------------
+(c) Copyright 1984-2020, [Leo Broukhis, Simon Cooper, Landon Curt Noll][judges] - All rights reserved
+This work is licensed under a [Creative Commons Attribution-ShareAlike 3.0 Unported License][cc].
+
+[judges]: http://www.ioccc.org/judges.html
+[cc]: http://creativecommons.org/licenses/by-sa/3.0/
+-----------------------------------------------------------------------------------------------------