improve markdown conformance to IOCCC best practices

CHANGES.md

@@ -440,7 +440,7 @@ which stores the _found_ location. This is useful for `-v 1` as one can then see
 something like:
 
 
-```sh
+``` <!---sh-->
 ./location -a -s -N -v 1 'united'
 United Arab Emirates ==> AE
 United Kingdom of Great Britain and Northern Ireland (the) ==> GB
@@ -454,7 +454,7 @@ United States of America ==> US
 
 Without the `-v 1` it will only show:
 
-```sh
+``` <!---sh-->
 $ ./location -a -s -n 'united'
 AE
 GB
@@ -477,7 +477,7 @@ find their country code, if they do not know what it is (or they want say
 anonymous and don't know that it's `XX`). Search is done case-insensitively.
 Another example use:
 
-```sh
+``` <!---sh-->
 $ ./location -asnv 1 germ
 German Democratic Republic ==> DD
 Germany ==> DE
@@ -624,14 +624,14 @@ like what was done yesterday for `jval`.
 
 Fixed bug where one could not do:
 
-```sh
+``` <!---sh-->
 echo '"test"' | ./jfmt -
 ```
 
 and the same thing with `jval` and `jnamval`. This also fixes the bug where one
 could not do:
 
-```sh
+``` <!---sh-->
 ./jfmt -
 "test"
 ^D
@@ -2613,7 +2613,7 @@ The JSON parser is code complete!
 
 The following JSON parses now work:
 
-```sh
+``` <!---sh-->
 ./jparse -J 3 -s '{ "curds" : "whey", "foo" : 23209 }'
 ./jparse -J 3 test_JSON/info.json/good/info.good.json
 ./jparse -J 3 test_JSON/author.json/good/author.default.json
@@ -2702,7 +2702,7 @@ Added `-T` flag to `mkiocccentry`, `fnamchk`, `txzchk`, `jstrencode` and
 `jstrdecode` to print the IOCCC entry tool set release tag:
 
 
-```sh
+``` <!---sh-->
 ./mkiocccentry -T
 ./fnamchk -T
 ./txzchk -T

CODE_OF_CONDUCT.md

@@ -1,5 +1,6 @@
 # Contributor Covenant Code of Conduct
 
+
 ## Our Pledge
 
 We as members, contributors, and leaders pledge to make participation in our
@@ -12,6 +13,7 @@ and orientation.
 We pledge to act and interact in ways that contribute to an open, welcoming,
 diverse, inclusive, and healthy community.
 
+
 ## Our Standards
 
 Examples of behavior that contributes to a positive environment for our
@@ -36,6 +38,7 @@ Examples of unacceptable behavior include:
 * Other conduct which could reasonably be considered inappropriate in a
   professional setting
 
+
 ## Enforcement Responsibilities
 
 Community leaders are responsible for clarifying and enforcing our standards of
@@ -48,6 +51,7 @@ comments, commits, code, wiki edits, issues, and other contributions that are
 not aligned to this Code of Conduct, and will communicate reasons for moderation
 decisions when appropriate.
 
+
 ## Scope
 
 This Code of Conduct applies within all community spaces, and also applies when
@@ -56,6 +60,7 @@ Examples of representing our community include using an official e-mail address,
 posting via an official social media account, or acting as an appointed
 representative at an online or offline event.
 
+
 ## Enforcement
 
 Instances of abusive, harassing, or otherwise unacceptable behavior may be
@@ -66,11 +71,13 @@ All complaints will be reviewed and investigated promptly and fairly.
 All community leaders are obligated to respect the privacy and security of the
 reporter of any incident.
 
+
 ## Enforcement Guidelines
 
 Community leaders will follow these Community Impact Guidelines in determining
 the consequences for any action they deem in violation of this Code of Conduct:
 
+
 ### 1. Correction
 
 **Community Impact**: Use of inappropriate language or other behavior deemed
@@ -80,6 +87,7 @@ unprofessional or unwelcome in the community.
 clarity around the nature of the violation and an explanation of why the
 behavior was inappropriate. A public apology may be requested.
 
+
 ### 2. Warning
 
 **Community Impact**: A violation through a single incident or series
@@ -92,6 +100,7 @@ includes avoiding interactions in community spaces as well as external channels
 like social media. Violating these terms may lead to a temporary or
 permanent ban.
 
+
 ### 3. Temporary Ban
 
 **Community Impact**: A serious violation of community standards, including
@@ -103,6 +112,7 @@ private interaction with the people involved, including unsolicited interaction
 with those enforcing the Code of Conduct, is allowed during this period.
 Violating these terms may lead to a permanent ban.
 
+
 ### 4. Permanent Ban
 
 **Community Impact**: Demonstrating a pattern of violation of community
@@ -112,6 +122,7 @@ individual, or aggression toward or disparagement of classes of individuals.
 **Consequence**: A permanent ban from any sort of public interaction within
 the community.
 
+
 ## Attribution
 
 This Code of Conduct is adapted from the [Contributor Covenant][homepage],

FAQ.md

@@ -30,35 +30,39 @@
 12. <a href="#keyword">Why do these tools sometimes use the incorrect IOCCC terms?</a>
 
 
-## 0. <a name="download">Where can I find the mkiocccentry tool?</a>
+<div id=="download">
+## 0. Where can I find the mkiocccentry tool?
+</div>
 
 The `mkiocccentry` tool source code is found in the
 [mkiocccentry repo](https://github.com/ioccc-src/mkiocccentry).
 If you have not already done so, you may download the source by using `git
 clone`:
 
 
-```sh
-git clone git@github.com:ioccc-src/mkiocccentry.git
+``` <!---sh-->
+git clone https://github.com/ioccc-src/mkiocccentry.git
 ```
 
 If you don't have `git` you may
 [download the zip file](https://github.com/ioccc-src/mkiocccentry/archive/refs/heads/master.zip)
 and then extract that file.
 
 
-## 1. <a name="compiling">How do I compile the mkiocccentry tool?</a>
+<div id=="compiling">
+## 1. How do I compile the mkiocccentry tool?
+</div>
 
 After downloading the repo (making sure that if you downloaded the zip file that
 you unzip it first) move into the _mkiocccentry_ directory:
 
-```sh
+``` <!---sh-->
 cd mkiocccentry
 ```
 
 and compile everything from scratch:
 
-```sh
+``` <!---sh-->
 make clobber all
 ```
 
@@ -67,8 +71,9 @@ local directory.  If something went wrong, see
 <a href="#reporting-bugs">how do I report bugs or other issues?</a>
 
 
-
-## 2. <a name="package">How do I package my submission?</a>
+<div id=="package">
+## 2. How do I package my submission?
+</div>
 
 We recommend that you use the `mkiocccentry` tool to package your submission.
 If you have not already done so, download the [mkiocccentry repo](https://github.com/ioccc-src/mkiocccentry)
@@ -78,7 +83,7 @@ and compile it
 
 From the top level directory, run the `mkiocccentry` executable:
 
-```sh
+``` <!---sh-->
 ./mkiocccentry work_dir prog.c Makefile remarks.md [file ...]
 ```
 
@@ -89,7 +94,7 @@ the submit slot number.
 
 Something like _/tmp/ioccc_ is a good choice:
 
-```sh
+``` <!---sh-->
 mkdir -p /tmp/ioccc
 ```
 
@@ -110,19 +115,19 @@ Once you have answered all of the questions, the tool will form a
 XZ compressed tarball, in v7 format, under the _work_dir_ directory.
 
 
-## 3. <a href="makefile">What do I do for the Makefile in my submission?</a>
+<div id=="makefile">
+#<# 3. What do I do for the Makefile in my submission?
+</div>
 
 Although you are welcome to add additional rules, we recommend that you use the
 example Makefile, [Makefile.example](Makefile.example), removing and changing
 comments as appropriate, and making sure to add the correct specifics of each
 rule.
 
-XXX - make sure to link to the winner repo FAQ about the Makefile - XXX
-XXX - this is not done now because of link changes and possibly an anchor - XXX
-XXX - name being added to this FAQ item - XXX
-
 
-## 4. <a name="submitting">Can't I just submit my obfuscated C program to the judges?</a>
+<div id=="submitting">
+## 4. Can't I just submit my obfuscated C program to the judges?
+</div>
 
 No. While we appreciate your enthusiasm for wanting to show us your obfuscated
 code, the [IOCCC judges](https://www.ioccc.org/judges.html) request your help by
@@ -138,7 +143,9 @@ In short, you cannot simply upload your obfuscated C program as it needs to
 be in a certain form and the `mkiocccentry` tool does that.
 
 
-## 5. <a name="mkiocccentry-requirements">Do I have to use mkiocccentry to package my submission?</a>
+<div id=="mkiocccentry-requirements">
+## 5. Do I have to use mkiocccentry to package my submission?
+</div>
 
 Technically you do not have to use the `mkiocccentry` tool; however, you run the
 risk of having your submission rejected if what you upload to the submit server is
@@ -154,7 +161,10 @@ inspect the directory that you used to form the tarball to verify that the
 contents under that directory are also OK. In particular, that tool tests that
 the JSON files are correct.
 
-## 6. <a name="installing">Do I need to install this code to use it?</a>
+
+<div id=="installing">
+## 6. Do I need to install this code to use it?
+</div>
 
 No, installing the code in this repo is not necessary to use it. These tools
 were designed to be used from the top level directory of the source, or after
@@ -168,19 +178,22 @@ put _./_ before the name of a command.
 
 For example:
 
-```shell
+``` <!---sh-->
 ./mkiocccentry -h
 ```
 
-## 7. <a name="help">How can I learn more about how to use the tools?</a>
+
+<div id=="help">
+## 7. How can I learn more about how to use the tools?
+</div>
 
 Assuming you have <a href="#download">downloaded</a> and <a
 href="#compiling">compiled</a> the code you can get a quick reminder of command
 options and arguments by use of the `-h` option of any tool:
 
 For instance:
 
-```shell
+``` <!---sh-->
 ./mkiocccentry -h
 ./iocccsize -h
 ./chkentry -h
@@ -196,7 +209,7 @@ directory at the top of the source directory.
 
 For example:
 
-```shell
+``` <!---sh-->
 man man/man1/mkiocccentry.1
 man man/man1/iocccsize.1
 man man/man1/chkentry.1
@@ -211,12 +224,14 @@ Luke!"_ as you may find the code in this repo reasonably un-obfuscated and fairl
 well commented.
 
 
-## 8. <a name="reporting-bugs">How do I report bugs or other issues?</a>
+<div id=="reporting-bugs">
+## 8. How do I report bugs or other issues?
+</div>
 
 Please run the following from the main directory:
 
 
-```sh
+``` <!---sh-->
 make bug_report
 ```
 
@@ -227,7 +242,7 @@ making sure to attach the bug report file.
 
 You may also run the `bug_report.sh` tool directly:
 
-```sh
+``` <!---sh-->
 ./bug_report.sh -v 1
 ```
 
@@ -252,7 +267,9 @@ The script that the make rule runs, `bug_report.sh`, will tell you the name of
 the file to upload.
 
 
-## 9. <a name="how-to-help">How can I help test this repo?</a>
+<div id=="how-to-help">
+## 9. How can I help test this repo?
+</div>
 
 Thank you for any and all help!
 
@@ -261,7 +278,9 @@ Please see the
 for more details on what you can do to help us.
 
 
-## 10. <a name="tar">What can I do if my system's tar(1) does not support the correct options?</a>
+<div id=="tar">
+## 10. What can I do if my system's tar(1) does not support the correct options?
+</div>
 
 
 If your tar does not support the `-J` option you can either use a system
@@ -274,17 +293,27 @@ Some systems have a `GNU tar` that you can use. For instance FreeBSD has a
 specify in the tools the `-t tar` option to make this work.
 
 
-## 11. <a name="markdown">Where can I find help with formatting markdown files for my submission?</a>
+<div id=="markdown">
+## 11. Where can I find help with formatting markdown files for my submission?
+</div>
+
+The IOCCC makes extensive use of [markdown](https://daringfireball.net/projects/markdown/).
+
+Please see [Official IOCCC FAQ FAQ 0.6](https://www.ioccc.org/faq.html#markdown)
+
+**IMPORTANT**: Please read the [IOCCC markdown best practices](markdown.html) guide
+as it lists things you **should not use** in markdown files.
 
-Please see this simple
-[markdown guide](https://www.markdownguide.org/basic-syntax) for more help.
+See the [markdown syntax](https://www.markdownguide.org/basic-syntax) guide.
+See also [CommonMark Spec](https://spec.commonmark.org/current/).
 
 
-## 12. <a name="keyword">Why do these tools sometimes use incorrect IOCCC terms?</a>
+<div id=="keyword">
+## 12. Why do these tools sometimes use incorrect IOCCC terms?
+</div>
 
-According to the [Official IOCCC FAQ
-6.9](https://www.ioccc.org/faq.html#terms) this repo sometimes uses
-the wrong term.  For example the name `mkiocccentry(1)` contains
+According to the [Official IOCCC FAQ 6.9](https://www.ioccc.org/faq.html#terms)
+this repo sometimes uses the wrong term.  For example the name `mkiocccentry(1)` contains
 the name _entry_ when the tool is dealing with a _submission_.  So
 why don't we call the tool _mkiocccsubmission_ and rename the this repo?
 
@@ -311,4 +340,4 @@ it's correct, a pull request that corrects the mistake or mistakes.
 Note, however, that there are many cases where the words _entry_ and/or
 _entries_ are actually correct: they would only be incorrect if they refer to an
 IOCCC submission that has not won.  In other words if it refers to submissions
-won then it should be _entry_ or _entries_.
+won then it should be _entry_ or _entries_.