From 9ed9f571073421e65ff27f28075d2207f38b4877 Mon Sep 17 00:00:00 2001
From: Landon Curt Noll <github-mail@asthe.com>
Date: Sun, 21 Apr 2024 18:54:59 -0700
Subject: [PATCH] tone down FAQ on themes

We toned down the FAQ 0.1 entry, referring instead to
_frequently submitted_ themes and providing suggestions
to those who wish to try and submit such entries.

Run `make gen_top_html` to perform the above.
---
 faq.html | 110 +++++++++++++++++++++++++++++------------------------
 faq.md   | 113 +++++++++++++++++++++++++++++++++----------------------
 2 files changed, 127 insertions(+), 96 deletions(-)

diff --git a/faq.html b/faq.html
index ec86379db..0d7ccec33 100644
--- a/faq.html
+++ b/faq.html
@@ -137,12 +137,12 @@
 <h2 id="section-0---submitting-entries-to-a-new-ioccc">Section 0 - <a href="#faq0">Submitting entries to a new IOCCC</a></h2>
 <ul>
 <li><a href="#faq0_0">0.0 - How may I submit to the IOCCC?</a></li>
-<li><a href="#faq0_1">0.1 - What types of entries have been over-submitted to the IOCCC?</a></li>
+<li><a href="#faq0_1">0.1 - What types of entries have been frequently submitted to the IOCCC?</a></li>
 <li><a href="#faq0_2">0.2 - What should I put in my entry’s Makefile?</a></li>
 <li><a href="#faq0_3">0.3 - May I use a different source or compiled filename than prog.c or prog?</a></li>
 <li><a href="#faq0_4">0.4 - What platform should I assume for my entry?</a></li>
 <li><a href="#faq0_5">0.5 - How may I comment or make a suggestion on IOCCC rules, guidelines and tools?</a></li>
-<li><a href="#faq0_6">0.6 - What are the IOCCC requirements for using markdown?</a></li>
+<li><a href="#faq0_6">0.6 - What are the IOCCC best practices for using markdown?</a></li>
 </ul>
 <h2 id="section-1---history-of-the-ioccc">Section 1 - <a href="#faq1">History of the IOCCC</a></h2>
 <ul>
@@ -268,9 +268,9 @@ git rebase</p></li>
 <p>work_dir directory where the entry directory and tarball are formed
 prog.c path to the C source for your entry</p>
 <p>Makefile Makefile to build (make all) and cleanup (make clean &amp; make clobber)</p>
-<p>remarks.md Remarks about your entry in markdown format
-NOTE: See the <a href="https://www.markdownguide.org/basic-syntax">markdown syntax</a> guide.
-See also <a href="https://spec.commonmark.org/current/">CommonMark Spec</a>.</p>
+<p>remarks.md Remarks about your entry in markdown format: see <a href="#remarks_md">FAQ 2.1</a> for more info.</p>
+<pre><code>             NOTE: See the [markdown syntax](https://www.markdownguide.org/basic-syntax) guide.
+             See also [CommonMark Spec](https://spec.commonmark.org/current/).</code></pre>
 <p>[file …] extra data files to include with your entry</p>
 <p>NOTE: It is <em>NOT</em> necessary to install the tools to use them as you can run
 the tools from the top of the <em>mkiocccentry repo</em> directory just fine.</p>
@@ -279,7 +279,7 @@ especially if it identifies a <a href="rules.html#2">rule 2</a> related problem,
 you are <strong>strongly</strong> encouraged to revise and correct your entry and
 then re-run the <code>mkiocccentry</code> tool.</p>
 <p>If you choose to risk violating rules, be sure an explain your reason
-for doing so in your _remarks.md file.</p></li>
+for doing so in your <code>remarks.md</code> file.</p></li>
 <li><p>Upload your entry to the IOCCC submit server</p>
 <p>The <strong>IOCCC submit server</strong> is still being written as of 2024
 Mar 10. <!--XXX--> As such, we do not yet have instructions
@@ -289,20 +289,29 @@ with the proper instructions. Watch the <a href="news.html">IOCCC news</a>
 for an annoucement of the availability of the <strong>IOCCC submit server</strong>.</p></li>
 </ol>
 <div id="faq0_1">
-<h3 id="faq-0.1-what-types-of-entries-have-been-over-submitted-to-the-ioccc">FAQ 0.1: What types of entries have been over-submitted to the IOCCC?</h3>
+<h3 id="faq-0.1-what-types-of-entries-have-been-frequently-submitted-to-the-ioccc">FAQ 0.1: What types of entries have been frequently submitted to the IOCCC?</h3>
 </div>
-<p>There are types of entries that show up over and over again. The
-IOCCC judges, and we suspect the public that enjoy viewing the
-results of the IOCCC, like variety.</p>
-<p>While it is possible to win a new IOCCC with one of these
-<strong>over-submitted</strong> types of entries, level of the competition from
-previous IOCCC entries make it more challenging to be successful.</p>
-<p>It is also important to note that the <a href="guidelines.html">guidelines</a> often
-state something along the lines of:</p>
-<blockquote>
-<p><em>We tend to dislike programs that: are similar to previous winning entries</em></p>
-</blockquote>
-<h4 id="maze-generator">maze generator</h4>
+<p>There are types of entries that are frequently submitted to the IOCCC.
+While we <strong>do not wish to prevent</strong> people from sending
+a submission to the IOCCC on a frequently submitted theme,
+we do wish to provide a <strong>fair warning</strong> to those who do.</p>
+<h4 id="fair-warnings-on-frequently-submitted-themes">Fair warnings on frequently submitted themes</h4>
+<p><strong>IMPORTANT HINT</strong>: It is <strong>not fatal</strong> to send in those types of
+entries, it is just <strong>HARDER to win</strong> with such a submission. A
+submission on a frequently submitted theme will have to do something
+in a <strong>really unique AND interesting way</strong> to even make it into the
+final judging rounds. It will have to compete with previous IOCCC
+winners based on the same theme.</p>
+<p><strong>IMPORTANT HINT</strong>: If you really wish send in an submission on a
+frequently submitted theme, be sure that it is obfuscated in several
+new and novel ways.</p>
+<p><strong>IMPORTANT HINT</strong>: Be sure to <strong>clearly explain</strong> near the beginning
+of your <code>remarks.md</code> file (see <a href="#remarks_md">FAQ 2.1</a>)
+<strong>why you are submitting a entry based on a frequently
+submitted theme</strong> and <strong>how compares with previous IOCCC winners</strong>
+of the same theme.</p>
+<h4 id="examples-of-frequently-submitted-themes">Examples of frequently submitted themes</h4>
+<h5 id="maze-generator">maze generator</h5>
 <ul>
 <li><a href="1985/shapiro/index.html">1985/shapiro</a></li>
 <li><a href="1991/buzzard/index.html">1991/buzzard</a></li>
@@ -310,35 +319,33 @@ state something along the lines of:</p>
 <li><a href="1995/dodsond2/index.html">1995/dodsond2</a></li>
 <li><a href="1998/bas1/index.html">1998/bas1</a></li>
 </ul>
-<h4 id="tic-tac-toenoughts-and-crossesxs-and-os-game">tic-tac-toe/noughts and crosses/Xs and Os game</h4>
+<h5 id="tic-tac-toenoughts-and-crossesxs-and-os-game">tic-tac-toe/noughts and crosses/Xs and Os game</h5>
 <ul>
 <li><a href="1991/westley/index.html">1991/westley</a></li>
 <li><a href="1996/jonth/index.html">1996/jonth</a></li>
 <li><a href="2020/carlini/index.html">2020/carlini</a></li>
 </ul>
-<h4 id="solitaireothello-game">solitaire/Othello game</h4>
+<h5 id="solitaireothello-game">solitaire/Othello game</h5>
 <ul>
 <li><a href="1987/lievaart/index.html">1987/lievaart</a></li>
 <li><a href="1994/dodsond1/index.html">1994/dodsond1</a></li>
 </ul>
-<h4 id="generating-small-primes-below-is-the-list-of-all-prime-related-winning-entries">generating small primes (below is the list of all prime related winning entries)</h4>
+<h5 id="generating-small-primes-below-is-the-list-of-all-prime-related-winning-entries">generating small primes (below is the list of all prime related winning entries)</h5>
 <ul>
-<li><p><a href="1985/august/index.html">1985/august</a></p></li>
-<li><p><a href="1988/applin/index.html">1988/applin</a></p></li>
-<li><p><a href="1994/weisberg/index.html">1994/weisberg</a></p></li>
-<li><p><a href="1995/makarios/index.html">1995/makarios</a></p></li>
-<li><p><a href="1996/dalbec/index.html">1996/dalbec</a></p></li>
-<li><p><a href="2000/bellard/index.html">2000/bellard</a></p></li>
+<li><a href="1985/august/index.html">1985/august</a></li>
+<li><a href="1988/applin/index.html">1988/applin</a></li>
+<li><a href="1994/weisberg/index.html">1994/weisberg</a></li>
+<li><a href="1995/makarios/index.html">1995/makarios</a></li>
+<li><a href="1996/dalbec/index.html">1996/dalbec</a></li>
+<li><a href="2000/bellard/index.html">2000/bellard</a></li>
 </ul>
-<p><em>As you can see, just a list of primes (let alone small primes) does not cut it
-anymore.</em></p>
-<h4 id="self-reproducing-program">self reproducing program</h4>
+<h5 id="self-reproducing-program">self reproducing program</h5>
 <ul>
 <li><a href="1990/scjones/index.html">1990/scjones</a></li>
-<li><a href="1994/smr/index.html">1994/smr</a> - <em>do not claim your program is the smallest one without seeing this</em>!</li>
-<li><a href="2000/dhyang/index.html">2000/dhyang</a> - <em>unless you beat this one, your chances are slim</em></li>
+<li><a href="1994/smr/index.html">1994/smr</a> - <em>do not claim your program is the smallest without seeing this entry</em>!</li>
+<li><a href="2000/dhyang/index.html">2000/dhyang</a> - <em>this entry set a high bar for entries of this theme</em></li>
 </ul>
-<h4 id="entries-that-just-print-hello-world">entries that just print “Hello, world!”</h4>
+<h5 id="entries-that-just-print-hello-world">entries that just print “Hello, world!”</h5>
 <ul>
 <li><a href="1984/anonymous/index.html">1984/anonymous</a></li>
 <li><a href="1985/applin/index.html">1985/applin</a></li>
@@ -348,39 +355,40 @@ anymore.</em></p>
 <li><a href="1992/lush/index.html">1992/lush</a></li>
 <li><a href="2000/tomx/index.html">2000/tomx</a></li>
 </ul>
-<p><em><strong>…it’s so 20th century…</strong></em> :-)</p>
-<h4 id="entries-that-use-some-complex-state-machinetable-to-print-something">entries that use some complex state machine/table to print something</h4>
+<h5 id="entries-that-use-some-complex-state-machinetable-to-print-something">entries that use some complex state machine/table to print something</h5>
 <ul>
 <li><a href="1988/isaak/index.html">1988/isaak</a></li>
 <li><a href="1988/phillipps/index.html">1988/phillipps</a></li>
 <li><a href="2018/ciura/index.html">2018/ciura</a></li>
 <li><a href="2018/giles/index.html">2018/giles</a></li>
 </ul>
-<h4 id="rot13">rot13</h4>
+<h5 id="rot13">rot13</h5>
 <ul>
 <li><a href="1985/sicherman/index.html">1985/sicherman</a></li>
 <li><a href="1989/westley/index.html">1989/westley</a></li>
 <li><a href="1990/dg/index.html">1990/dg</a></li>
 <li><a href="1991/fine/index.html">1991/fine</a></li>
 </ul>
-<h4 id="pi-or-e-computation"><strong>pi</strong> or <strong>e</strong> computation</h4>
+<h5 id="pi-or-e-computation"><strong>pi</strong> or <strong>e</strong> computation</h5>
 <ul>
 <li><a href="1986/august/index.html">1986/august</a></li>
 <li><a href="1988/robison/index.html">1988/robison</a></li>
 <li><a href="1988/westley/index.html">1988/westley</a></li>
 <li><a href="1989/roemer/index.html">1989/roemer</a></li>
 </ul>
-<h4 id="hints-on-overused-themes">Hints on overused themes</h4>
-<p>HINT: It is not fatal to send in those types of entries, it is just MUCH
-HARDER to win. Such an entry would have to do something <em>really unique <strong>AND</strong>
-interesting</em> to even make it into the final judging rounds. Entries that
-reuse these ‘worn out’ themes frequently lose to other entries that do
-something different.</p>
-<p>HINT: If you really MUST send in an entry based on an ‘overused theme’, be sure
-that it is obfuscated in several new and novel ways. Be sure to <em>clearly</em>
-explain near the beginning of your remarks why you are submitting a entry based
-on an ‘overused theme’ and why the judges should not simply toss it out as being
-boring.</p>
+<h4 id="the-above-list-of-frequently-submitted-themes-is-not-exhaustive">The above list of frequently submitted themes is not exhaustive</h4>
+<h4 id="some-final-thoughts-on-frequently-used-themes">Some final thoughts on frequently used themes</h4>
+<p>While it is possible to win a new IOCCC with one of these
+<strong>frequently submitted</strong> types of entries, level of the competition from
+previous IOCCC entries make it more challenging to be successful.</p>
+<p>It is also important to note that the <a href="guidelines.html">guidelines</a> often
+state something along the lines of:</p>
+<pre><code>    We tend to dislike programs that: are similar to previous winning entries.</code></pre>
+<p><strong>FAIR WARNING</strong>: Be sure to <strong>clearly explain</strong> near the beginning
+of your <code>remarks.md</code> file (see <a href="#remarks_md">FAQ 2.1</a>)
+<strong>why you are submitting a entry based on a frequently
+submitted theme</strong> and <strong>how compares with previous IOCCC winners</strong>
+of the same theme.</p>
 <div id="faq0_2">
 <h3 id="faq-0.2-what-should-i-put-in-my-entrys-makefile">FAQ 0.2: What should I put in my entry’s Makefile?</h3>
 </div>
@@ -462,7 +470,7 @@ discussion with the <a href="judges.html">IOCCC judges</a>, then see
 <a href="contact.html">How to contact the IOCCC</a>.</p>
 <div id="faq0_6">
 <div id="markdown">
-<h3 id="faq-0.6---what-are-the-ioccc-requirements-for-using-markdown">FAQ 0.6: - What are the IOCCC requirements for using markdown?</h3>
+<h3 id="faq-0.6---what-are-the-ioccc-best-practices-for-using-markdown">FAQ 0.6: - What are the IOCCC best practices for using markdown?</h3>
 </div>
 </div>
 <p>The IOCCC makes extensive use of <a href="https://daringfireball.net/projects/markdown/">markdown</a>.
@@ -759,8 +767,10 @@ to the <a href="https://www.ioccc.org">official IOCCC web site</a>.</p>
 </div>
 <p>By tradition, we do not say.</p>
 <div id="faq2_1">
+<div id="remarks_md">
 <h3 id="faq-2.1-what-should-i-put-in-the-remarks.md-file-of-my-entry">FAQ 2.1: What should I put in the remarks.md file of my entry?</h3>
 </div>
+</div>
 <p>While you may put in as much or as little as you wish into your entry’s
 <code>remarks.md</code> file, we do have few important suggestions:</p>
 <p>We recommend that you explain how to use your entry. Explain the
diff --git a/faq.md b/faq.md
index 231d3c3d1..eeec60b63 100644
--- a/faq.md
+++ b/faq.md
@@ -3,12 +3,12 @@
 
 ## Section  0 - [Submitting entries to a new IOCCC](#faq0)
 - [0.0  - How may I submit to the IOCCC?](#faq0_0)
-- [0.1  - What types of entries have been over-submitted to the IOCCC?](#faq0_1)
+- [0.1  - What types of entries have been frequently submitted to the IOCCC?](#faq0_1)
 - [0.2  - What should I put in my entry's Makefile?](#faq0_2)
 - [0.3  - May I use a different source or compiled filename than prog.c or prog?](#faq0_3)
 - [0.4  - What platform should I assume for my entry?](#faq0_4)
 - [0.5  - How may I comment or make a suggestion on IOCCC rules, guidelines and tools?](#faq0_5)
-- [0.6  - What are the IOCCC requirements for using markdown?](#faq0_6)
+- [0.6  - What are the IOCCC best practices for using markdown?](#faq0_6)
 
 
 ## Section  1 - [History of the IOCCC](#faq1)
@@ -162,7 +162,8 @@ To submit your code to the IOCCC, you **MUST** follow these steps:
 
 	Makefile	Makefile to build (make all) and cleanup (make clean & make clobber)
 
-	remarks.md	Remarks about your entry in markdown format
+	remarks.md	Remarks about your entry in markdown format: see [FAQ 2.1](#remarks_md) for more info.
+
 			NOTE: See the [markdown syntax](https://www.markdownguide.org/basic-syntax) guide.
 			See also [CommonMark Spec](https://spec.commonmark.org/current/).
 
@@ -177,7 +178,7 @@ To submit your code to the IOCCC, you **MUST** follow these steps:
     then re-run the `mkiocccentry` tool.
 
     If you choose to risk violating rules, be sure an explain your reason
-    for doing so in your _remarks.md file.
+    for doing so in your `remarks.md` file.
 
 6. Upload your entry to the IOCCC submit server
 
@@ -191,24 +192,39 @@ To submit your code to the IOCCC, you **MUST** follow these steps:
 
 
 <div id="faq0_1">
-### FAQ 0.1: What types of entries have been over-submitted to the IOCCC?
+### FAQ 0.1: What types of entries have been frequently submitted to the IOCCC?
 </div>
 
-There are types of entries that show up over and over again.  The
-IOCCC judges, and we suspect the public that enjoy viewing the
-results of the IOCCC, like variety.
-
-While it is possible to win a new IOCCC with one of these
-__over-submitted__ types of entries, level of the competition from
-previous IOCCC entries make it more challenging to be successful.
-
-It is also important to note that the [guidelines](guidelines.html) often
-state something along the lines of:
-
-> _We tend to dislike programs that: are similar to previous winning entries_
+There are types of entries that are frequently submitted to the IOCCC.
+While we **do not wish to prevent** people from sending
+a submission to the IOCCC on a frequently submitted theme,
+we do wish to provide a **fair warning** to those who do.
 
 
-#### maze generator
+#### Fair warnings on frequently submitted themes
+
+**IMPORTANT HINT**: It is **not fatal** to send in those types of
+entries, it is just **HARDER to win** with such a submission.  A
+submission on a frequently submitted theme will have to do something
+in a **really unique AND interesting way** to even make it into the
+final judging rounds.  It will have to compete with previous IOCCC
+winners based on the same theme.
+
+**IMPORTANT HINT**: If you really wish send in an submission on a
+frequently submitted theme, be sure that it is obfuscated in several
+new and novel ways.
+
+**IMPORTANT HINT**: Be sure to **clearly explain** near the beginning
+of your `remarks.md` file (see [FAQ 2.1](#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.
+
+
+#### Examples of frequently submitted themes
+
+
+##### maze generator
 
 - [1985/shapiro](1985/shapiro/index.html)
 - [1991/buzzard](1991/buzzard/index.html)
@@ -217,41 +233,37 @@ state something along the lines of:
 - [1998/bas1](1998/bas1/index.html)
 
 
-#### tic-tac-toe/noughts and crosses/Xs and Os game
+##### tic-tac-toe/noughts and crosses/Xs and Os game
 
 - [1991/westley](1991/westley/index.html)
 - [1996/jonth](1996/jonth/index.html)
 - [2020/carlini](2020/carlini/index.html)
 
 
-#### solitaire/Othello game
+##### solitaire/Othello game
 
 - [1987/lievaart](1987/lievaart/index.html)
 - [1994/dodsond1](1994/dodsond1/index.html)
 
 
-#### generating small primes (below is the list of all prime related winning entries)
+##### generating small primes (below is the list of all prime related winning entries)
 
 - [1985/august](1985/august/index.html)
 - [1988/applin](1988/applin/index.html)
 - [1994/weisberg](1994/weisberg/index.html)
 - [1995/makarios](1995/makarios/index.html)
 - [1996/dalbec](1996/dalbec/index.html)
-
 - [2000/bellard](2000/bellard/index.html)
 
-_As you can see, just a list of primes (let alone small primes) does not cut it
-anymore._
 
-
-#### self reproducing program
+##### self reproducing program
 
 - [1990/scjones](1990/scjones/index.html)
-- [1994/smr](1994/smr/index.html) - _do not claim your program is the smallest one without seeing this_!
-- [2000/dhyang](2000/dhyang/index.html) - _unless you beat this one, your chances are slim_
+- [1994/smr](1994/smr/index.html) - _do not claim your program is the smallest without seeing this entry_!
+- [2000/dhyang](2000/dhyang/index.html) - _this entry set a high bar for entries of this theme_
 
 
-#### entries that just print "Hello, world!"
+##### entries that just print "Hello, world!"
 
 - [1984/anonymous](1984/anonymous/index.html)
 - [1985/applin](1985/applin/index.html)
@@ -261,10 +273,8 @@ anymore._
 - [1992/lush](1992/lush/index.html)
 - [2000/tomx](2000/tomx/index.html)
 
-_**...it's so 20th century...**_ :-)
 
-
-#### entries that use some complex state machine/table to print something
+##### entries that use some complex state machine/table to print something
 
 - [1988/isaak](1988/isaak/index.html)
 - [1988/phillipps](1988/phillipps/index.html)
@@ -272,7 +282,7 @@ _**...it's so 20th century...**_ :-)
 - [2018/giles](2018/giles/index.html)
 
 
-#### rot13
+##### rot13
 
 - [1985/sicherman](1985/sicherman/index.html)
 - [1989/westley](1989/westley/index.html)
@@ -280,7 +290,7 @@ _**...it's so 20th century...**_ :-)
 - [1991/fine](1991/fine/index.html)
 
 
-#### **pi** or **e** computation
+##### **pi** or **e** computation
 
 - [1986/august](1986/august/index.html)
 - [1988/robison](1988/robison/index.html)
@@ -288,19 +298,28 @@ _**...it's so 20th century...**_ :-)
 - [1989/roemer](1989/roemer/index.html)
 
 
-#### Hints on overused themes
+####  The above list of frequently submitted themes is not exhaustive
 
-HINT: It is not fatal to send in those types of entries, it is just MUCH
-HARDER to win. Such an entry would have to do something _really unique **AND**
-interesting_ to even make it into the final judging rounds. Entries that
-reuse these 'worn out' themes frequently lose to other entries that do
-something different.
 
-HINT: If you really MUST send in an entry based on an 'overused theme', be sure
-that it is obfuscated in several new and novel ways. Be sure to _clearly_
-explain near the beginning of your remarks why you are submitting a entry based
-on an 'overused theme' and why the judges should not simply toss it out as being
-boring.
+#### Some final thoughts on frequently used themes
+
+While it is possible to win a new IOCCC with one of these
+**frequently submitted** types of entries, level of the competition from
+previous IOCCC entries make it more challenging to be successful.
+
+It is also important to note that the [guidelines](guidelines.html) often
+state something along the lines of:
+
+```
+    We tend to dislike programs that: are similar to previous winning entries.
+```
+
+**FAIR WARNING**: Be sure to **clearly explain** near the beginning
+of your `remarks.md` file (see [FAQ 2.1](#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.
+
 
 
 <div id="faq0_2">
@@ -411,7 +430,7 @@ discussion with the [IOCCC judges](judges.html), then see
 
 <div id="faq0_6">
 <div id="markdown">
-### FAQ 0.6: - What are the IOCCC requirements for using markdown?
+### FAQ 0.6: - What are the IOCCC best practices for using markdown?
 </div>
 </div>
 
@@ -788,8 +807,10 @@ By tradition, we do not say.
 
 
 <div id="faq2_1">
+<div id="remarks_md">
 ### FAQ 2.1: What should I put in the remarks.md file of my entry?
 </div>
+</div>
 
 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: