From bb19f88222dd9bf725ec3f952b2c800f97f88f42 Mon Sep 17 00:00:00 2001
From: Landon Curt Noll <github-mail@asthe.com>
Date: Sun, 21 Apr 2024 02:54:54 -0700
Subject: [PATCH] add markdown.md and markdown.html

Add `markdown.md` which generates `markdown.html`
to document IOCCC markdown best practices.

Changed `bin/gen-top-html.sh` VERSION from to "1.4.1 2024-04-16"
to "1.4.2 2024-04-21".

Added FAQ 0.6 about IOCCC mark requirements.

Run `make gen_top_html timestamp` to perform the above.
---
 bin/gen-top-html.sh |   3 +-
 faq.html            |  17 +++
 faq.md              |  22 ++++
 inc/md2html.cfg     |  16 +++
 markdown.html       | 294 ++++++++++++++++++++++++++++++++++++++++++++
 markdown.md         | 197 +++++++++++++++++++++++++++++
 sitemap.xml         |   8 +-
 7 files changed, 552 insertions(+), 5 deletions(-)
 create mode 100644 markdown.html
 create mode 100644 markdown.md

diff --git a/bin/gen-top-html.sh b/bin/gen-top-html.sh
index 22a4d9cd9..ded9c1b8f 100755
--- a/bin/gen-top-html.sh
+++ b/bin/gen-top-html.sh
@@ -88,7 +88,7 @@ TOP_MD_SET+=("faq")
 
 # set variables referenced in the usage message
 #
-export VERSION="1.4.1 2024-04-16"
+export VERSION="1.4.2 2024-04-21"
 NAME=$(basename "$0")
 export NAME
 export V_FLAG=0
@@ -124,6 +124,7 @@ TOP_MD_SET+=("inc/README")
 TOP_MD_SET+=("index")
 TOP_MD_SET+=("judges")
 TOP_MD_SET+=("license")
+TOP_MD_SET+=("markdown")
 TOP_MD_SET+=("news")
 TOP_MD_SET+=("next/README")
 TOP_MD_SET+=("next/guidelines")
diff --git a/faq.html b/faq.html
index b8326cfc0..271f98625 100644
--- a/faq.html
+++ b/faq.html
@@ -142,6 +142,7 @@
 <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>
 </ul>
 <h2 id="section-1---history-of-the-ioccc">Section 1 - <a href="#faq1">History of the IOCCC</a></h2>
 <ul>
@@ -458,6 +459,22 @@ discussion</a>.</p>
 <p>As a very last resort and/or if you feel the need to engage in a private
 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>
+</div>
+</div>
+<p>The IOCCC makes extensive use of <a href="https://daringfireball.net/projects/markdown/">markdown</a>.
+For example, we <a href="faq.html#submit">submitting to the IOCCC</a>, we have people
+to submit remarks about entry in markdown format. Every
+<a href="years.html">winning IOCCC entry</a> uses a <code>README.md</code> markdown file
+as the basis for forming the <code>index.html</code> web page for that entry.
+All generated HTML pages on the <a href="https://www.ioccc.org/index.html">Official IOCCC web site</a>
+start with some markdown content.</p>
+<p><strong>IMPORTANT</strong>: Please read the <a href="markdown.html">IOCCC markdown best practices</a> guide
+as it lists things you <strong>should not use</strong> in markdown files.</p>
+<p>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>
 <div id="faq1">
 <h2 id="section-1-history-of-the-ioccc">Section 1: History of the IOCCC</h2>
 </div>
diff --git a/faq.md b/faq.md
index 20cd9af14..76c3e9235 100644
--- a/faq.md
+++ b/faq.md
@@ -8,6 +8,7 @@
 - [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)
 
 
 ## Section  1 - [History of the IOCCC](#faq1)
@@ -408,6 +409,27 @@ discussion with the [IOCCC judges](judges.html), then see
 [How to contact the IOCCC](contact.html).
 
 
+<div id="faq0_6">
+<div id="markdown">
+### FAQ 0.6: - What are the IOCCC requirements for using markdown?
+</div>
+</div>
+
+The IOCCC makes extensive use of [markdown](https://daringfireball.net/projects/markdown/).
+For example, we [submitting to the IOCCC](faq.html#submit), we have people
+to submit remarks about entry in markdown format.  Every
+[winning IOCCC entry](years.html) uses a `README.md` markdown file
+as the basis for forming the `index.html` web page for that entry.
+All generated HTML pages on the [Official IOCCC web site](https://www.ioccc.org/index.html)
+start with some markdown content.
+
+**IMPORTANT**: Please read the [IOCCC markdown best practices](markdown.html) guide
+as it lists things you **should not use** in markdown files.
+
+See the [markdown syntax](https://www.markdownguide.org/basic-syntax) guide.
+See also [CommonMark Spec](https://spec.commonmark.org/current/).
+
+
 <div id="faq1">
 ## Section 1: History of the IOCCC
 </div>
diff --git a/inc/md2html.cfg b/inc/md2html.cfg
index 925df5736..3391bba14 100644
--- a/inc/md2html.cfg
+++ b/inc/md2html.cfg
@@ -227,6 +227,22 @@ location.md
 	-D
 	./
 
+markdown.md
+	-H
+	navbar=empty
+	-o
+	bin/subst.default.sh
+	-s
+	TITLE=The International Obfuscated C Code Contest
+	-s
+	DESCRIPTION=IOCCC markdown
+	-s
+	KEYWORDS=IOCCC, markdown
+	-s
+	HEADER_2=IOCCC markdown best practices
+	-D
+	./
+
 news.md
 	-H
 	navbar=empty
diff --git a/markdown.html b/markdown.html
new file mode 100644
index 000000000..77500b4df
--- /dev/null
+++ b/markdown.html
@@ -0,0 +1,294 @@
+<!DOCTYPE html>
+<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
+<!-- START: two lines up starts content from: inc/top.default.html -->
+
+<!-- END: this line ends content from: inc/top.default.html -->
+<!-- START: this line starts content from: inc/head.default.html -->
+
+<head>
+<link rel="stylesheet" href="./ioccc.css">
+<link href="https://fonts.googleapis.com/css2?family=Outfit:wght@100..900&display=swap" rel="stylesheet">
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1.0, user-scalable=yes">
+<title>The International Obfuscated C Code Contest</title>
+<link rel="icon" type="image/x-icon" href="./favicon.ico">
+<meta name="description" content="IOCCC markdown">
+<meta name="keywords" content="IOCCC, markdown">
+</head>
+
+<!-- !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -->
+<!-- !!! DO NOT MODIFY THIS FILE - This file is generated by a tool !!! -->
+<!-- !!! DO NOT MODIFY THIS FILE - This file is generated by a tool !!! -->
+<!-- !!! DO NOT MODIFY THIS FILE - This file is generated by a tool !!! -->
+<!-- !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -->
+
+<!-- END: this line ends content from: inc/head.default.html -->
+
+<!-- -->
+<!-- This web page was formed via the tool: bin/gen-top-html.sh -->
+<!-- The content of main section of this web page came from: markdown.md -->
+<!-- -->
+
+<!-- !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -->
+<!-- !!! Do not modify this web page, instead modify the file: markdown.md !!! -->
+<!-- !!! Do not modify this web page, instead modify the file: markdown.md !!! -->
+<!-- !!! Do not modify this web page, instead modify the file: markdown.md !!! -->
+<!-- !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -->
+
+<!-- Markdown content was converted into HTML via the tool: bin/md2html.sh -->
+
+<!-- START: this line starts content from: inc/body.default.html -->
+
+<body>
+
+<!-- END: this line ends content from: inc/body.default.html -->
+<!-- START: this line starts content from: inc/topbar.default.html -->
+
+<div class="theader">
+  <nav class="topbar">
+    <div class="container">
+      <div class="logo">
+        IOCCC
+      </div>
+
+      <div class="topbar-items">
+        <div class="item">
+          <span class="item-header">
+            Home
+          </span>
+
+          <div class="sub-item">
+            <div class="outfit-font"><a href="./index.html">IOCCC Home</a></div>
+            <div class="outfit-font"><a href="./years.html">Winning Entries</a></div>
+            <div class="outfit-font"><a href="./authors.html">People who have won</a></div>
+            <div class="outfit-font"><a href="./location.html">Location of authors</a></div>
+          </div>
+        </div>
+
+        <div class="item">
+          <span class="item-header">
+            News
+          </span>
+
+          <div class="sub-item">
+            <div class="outfit-font"><a href="./news.html">IOCCC News</a></div>
+            <div class="outfit-font"><a href="./status.html">Contest status</a></div>
+            <div class="outfit-font"><a href="./next/index.html">Rules and Guidelines</a></div>
+            <div class="outfit-font"><a href="./faq.html#submit">How to enter the IOCCC</a></div>
+            <div class="outfit-font"><a href="./faq.html">FAQ</a></div>
+          </div>
+        </div>
+
+        <div class="item">
+          <span class="item-header">
+            Bugs
+          </span>
+
+          <div class="sub-item">
+            <div class="outfit-font"><a href="./bugs.html">Bugs &amp; (mis)features</a></div>
+            <div class="outfit-font"><a href="./faq.html#fix_an_entry">Fixing IOCCC entries</a></div>
+            <div class="outfit-font"><a href="./faq.html#fix_web_site">Fixing the web site</a></div>
+            <div class="outfit-font"><a href="./faq.html#fix_author">Fixing author info</a></div>
+            <div class="outfit-font"><a href="./thanks-for-help.html">Thanks for the help</a></div>
+          </div>
+        </div>
+
+        <div class="item">
+          <span class="item-header">
+            Judges
+          </span>
+
+          <div class="sub-item">
+            <div class="outfit-font"><a href="./judges.html">The IOCCC Judges</a></div>
+            <div class="outfit-font"><a href="./contact.html">Contacting the IOCCC</a></div>
+          </div>
+        </div>
+      </div>
+    </div>
+  </nav>
+</div>
+
+<!-- END: this line ends content from: inc/topbar.default.html -->
+<!-- START: this line starts content from: inc/header.default.html -->
+
+<div class="header">
+  <img src="./png/ioccc.png" alt="IOCCC image by Matt Zucker" width=300 height=110>
+  <h1>The International Obfuscated C Code Contest</h1>
+  <h2>IOCCC markdown best practices</h2>
+</div>
+
+<!-- END: this line ends content from: inc/header.default.html -->
+<!-- START: this line starts content from: inc/navbar.empty.html -->
+
+<div class="navbar">
+<a class="Right" href="https://validator.w3.org/nu/?doc=https%3A%2F%2Fioccc-src.github.io%2Ftemp-test-ioccc%2Fmarkdown.html">&#x2713;</a>
+</div>
+
+<!-- END: this line ends content from: inc/navbar.empty.html -->
+<!-- START: this line starts content from: inc/before-content.default.html -->
+
+    <div class="content" id="content">
+
+<!-- END: this line ends content from: inc/before-content.default.html -->
+<!-- START: this line starts content for HTML phase 21 by: bin/pandoc-wrapper.sh via bin/md2html.sh -->
+
+<!-- BEFORE: 1st line of markdown file: markdown.md -->
+<h1 id="ioccc-markdown-best-practices">IOCCC markdown best practices</h1>
+<p>The IOCCC makes extensive use of <a href="https://daringfireball.net/projects/markdown/">markdown</a>.
+For example, we <a href="faq.html#submit">submitting to the IOCCC</a>, we have people
+to submit remarks about entry in markdown format. Every
+<a href="years.html">winning IOCCC entry</a> uses a <code>README.md</code> markdown file
+as the basis for forming the <code>index.html</code> web page for that entry.
+All generated HTML pages on the <a href="https://www.ioccc.org/index.html">Official IOCCC web site</a>
+start with some markdown content.</p>
+<p>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>Nevertheless, the IOCCC does have certain practices that we ask authors to follow.</p>
+<p>In particular there are things we ask people to please do <strong>NOT</strong> use markdown files:</p>
+<h2 id="do-not-use-name-attributes-in-html-a-tags">Do not use name attributes in HTML a tags</h2>
+<p>Please do not use the HTML construct:</p>
+<pre><code>    &lt;a name=&quot;string&quot;&gt;\&lt;/a&gt;</code></pre>
+<p>as those are <strong>NOT</strong> part of the HTML 5 standard.</p>
+<p>Instead use:</p>
+<pre><code>    &lt;div id=&quot;string&quot;&gt;...\&lt;/div&gt;</code></pre>
+<p>where the “…” is the HTML you want to “name”. The <strong>div</strong>
+encapsulates the HTML you want to name: I.e., the target of some
+“<strong>&lt;a href=”#string”&gt;</strong>” or some other “<strong>&lt;a href=”URL#string”&gt;</strong>”
+for the given page URL.</p>
+<p>There are certain HTML Elements that cannot have internal “<strong>&lt;div
+id=”string”&gt;…&lt;/div&gt;</strong>”. For example you cannot do this:</p>
+<pre><code>    # &lt;div id=&quot;string&quot;&gt;This will not work&lt;/div&gt;</code></pre>
+<p>For things like headings, you have to surround them as in:</p>
+<pre><code>    &lt;div id=&quot;string&quot;&gt;
+    # This will work
+    &lt;/div&gt;</code></pre>
+<p>While some browsers will still recognize the HTML construct “<strong>&lt;a
+name=”string”&gt;&lt;/a&gt;</strong>”, they may not in the future.</p>
+<h2 id="do-not-use-trailing-backslash-outside-of-a-code-block">Do not use trailing backslash outside of a code block</h2>
+<p>Unless the line is inside a markdown code block, please do <strong>NOT</strong>
+end a markdown line with a trailing backslash (“\”). Instead use
+a trailing “<strong>&lt;br&gt;</strong>”.</p>
+<p>Instead of:</p>
+<pre><code>    In markdown,\
+    do not use trailing\
+    backslashes outside of\
+    a code block</code></pre>
+<p>use:</p>
+<pre><code>    In markdown,&lt;br&gt;
+    use trailing&lt;br&gt;
+    br&#39;s outside of&lt;br&gt;
+    a code block</code></pre>
+<p>Again, use of a trailing backslash (“\”) inside a markdown code block is fine:</p>
+<pre><code>```
+    This is OK\
+    inside a\
+    markdown code\
+    block
+```</code></pre>
+<p>This will avoid <code>pandoc(1)</code> generating deprecated HTML elements such as:</p>
+<p>“<strong>&lt;br /&gt;</strong>”</p>
+<h2 id="do-not-use-markdown-image-elements">Do not use markdown image elements</h2>
+<p>Please do not use the markdown embedded image element.</p>
+<p>Instead of using this markdown element to embed an image:</p>
+<pre><code>    ![alt text](filename.png &quot;Title&quot;)</code></pre>
+<p>Use a “img” HTML element with “alt”, “alt”, “width” and “length”
+attributes:</p>
+<pre><code>    &lt;img src=&quot;filename.png&quot;
+     alt=&quot;describe the filename.png image for someone who cannot view it&quot;
+     width=PIXEL_WIDTH height=PIXEL_HEIGHT&gt;</code></pre>
+<p>For example, instead of:</p>
+<pre><code>    ![1984-anonymous-tattoo.jpg](1984-anonymous-tattoo.jpg)</code></pre>
+<p>use this HTML:</p>
+<pre><code>    &lt;img src=&quot;1984-anonymous-tattoo.jpg&quot;
+     alt=&quot;image of a tattoo of the 1984 anonymous C code&quot;
+     width=600 height=401&gt;</code></pre>
+<p>The problem goes beyond the fact that <code>pandoc(1)</code> generates problematic
+HTML from the markdown image construct, the resulting HTML does not
+have “width” and “height” information so browsers have to slow down
+on rendering text around the image until it can internally determine
+the image size.</p>
+<h2 id="do-not-use-markdown-style-horizontal-lines">Do not use markdown style horizontal lines</h2>
+<p>Please do not use “<strong>—</strong>”-style lines in markdown to create horizontal
+lines, nor to separate sections.</p>
+<p>Unless something is inside a markdown code block, do not start a
+line with 3 or more dashes (“-”).</p>
+<p>Such causes <code>pandoc(1)</code> to generate “<strong>&lt;hr /&gt;</strong>”. The “<strong>&lt;hr
+/&gt;</strong>” has no effect in standard HTML 5 and interacts badly with
+unquoted attribute values.</p>
+<p>If a horizontal line is really needed, use:</p>
+<pre><code>    &lt;hr&gt;</code></pre>
+<p>If a short line is needed, use:</p>
+<pre><code>    &lt;hr style=&quot;width:10%;text-align:left;margin-left:0&quot;&gt;</code></pre>
+<h2 id="do-not-use-the-strike-html-element">Do not use the strike HTML element</h2>
+<p>Please not use the HTML element:</p>
+<pre><code>    &lt;strike&gt;...&lt;/strike&gt;</code></pre>
+<p>Use instead:</p>
+<pre><code>    &lt;del&gt;...&lt;/del&gt;</code></pre>
+<h2 id="do-not-use-tt-html-elements">Do not use tt HTML elements</h2>
+<p>Please do not use the tt HTML elements:</p>
+<div class="sourceCode" id="cb16"><pre class="sourceCode html"><code class="sourceCode html"><span id="cb16-1"><a href="#cb16-1" aria-hidden="true" tabindex="-1"></a>    <span class="dt">&lt;</span><span class="kw">tt</span><span class="dt">&gt;</span>The HTML 5 obsolete tt element is obsolete<span class="dt">&lt;/</span><span class="kw">tt</span><span class="dt">&gt;</span></span></code></pre></div>
+<p>Instead use either a monospaced span:</p>
+<div class="sourceCode" id="cb17"><pre class="sourceCode html"><code class="sourceCode html"><span id="cb17-1"><a href="#cb17-1" aria-hidden="true" tabindex="-1"></a>    <span class="dt">&lt;</span><span class="kw">span</span><span class="ot"> style</span><span class="op">=</span><span class="st">&quot;font-family: monospace;&quot;</span><span class="dt">&gt;</span>Use of monospaced font is one option<span class="dt">&lt;/</span><span class="kw">span</span><span class="dt">&gt;</span></span></code></pre></div>
+<p>Or better and easier still, use an inline markdown code block:</p>
+<pre><code>    `inline markdown code block is easier and much better`</code></pre>
+<!-- AFTER: last line of markdown file: markdown.md -->
+
+<!-- END: this line ends content for HTML phase 21 by: bin/pandoc-wrapper.sh via bin/md2html.sh -->
+<!-- START: this line starts content from: inc/after-content.default.html -->
+
+    </div>
+
+<!-- END: this line ends content from: inc/after-content.default.html -->
+<!-- START: this line starts content from: inc/footer.default.html -->
+
+<!--
+
+    Copyright © 1984-2024 by Landon Curt Noll. All Rights Reserved.
+
+    You are free to share and adapt this file under the terms of this license:
+
+	Creative Commons Attribution-ShareAlike 4.0 International (CC BY-SA 4.0)
+
+    For more information, see:
+
+	https://creativecommons.org/licenses/by-sa/4.0/
+
+-->
+
+<div class="footer">
+  <div id="copyright"><h2>Copyright and CC BY-SA 4.0 License</h2></div>
+  <p>All IOCCC content including this file and web page are:</p>
+  <b>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Copyright &copy; 1984-2024 by Landon Curt Noll. <a href="https://creativecommons.org/faq/#what-does-some-rights-reserved-mean">Some Rights Reserved</a>.</b>
+  <p>This work is licensed by Landon Curt Noll under:</p>
+  <p><b><a href="https://creativecommons.org/licenses/by-sa/4.0/?ref=chooser-v1"
+  target="_blank" rel="license noopener noreferrer" style="display:inline-block;">&nbsp;&nbsp;&nbsp;&nbsp;CC BY-SA 4.0
+  <img style="height:22px!important;margin-left:3px;vertical-align:text-bottom;"
+  src="./png/cc.png"
+  alt="cc inside circle symbol">
+  <img style="height:22px!important;margin-left:3px;vertical-align:text-bottom;"
+  src="./png/by.png"
+  alt="person inside circle symbol">
+  <img style="height:22px!important;margin-left:3px;vertical-align:text-bottom;"
+  src="./png/sa.png"
+  alt="arrow looping back on itself inside circle symbol">
+  </a></b></p>
+  <p>The <b>CC BY-SA 4.0 LEGAL CODE</b> for this license is found under:</p>
+  <p>&nbsp;&nbsp;&nbsp;<b><a href="https://creativecommons.org/licenses/by-sa/4.0/legalcode.en">
+  https://creativecommons.org/licenses/by-sa/4.0/legalcode.en</a></b></p>
+  <p>You should <b>carefully review</b> all of the terms and conditions of the
+  <a href="https://creativecommons.org/licenses/by-sa/4.0/legalcode.en">actual license</a>
+  before using the licensed material.</p>
+  <p>You may wish to review the <b><a href="./license.html">highlights of some of the key
+  features and terms</a></b> of the <a href="https://creativecommons.org/licenses/by-sa/4.0/legalcode.en">actual license</a>.</p>
+  <h2>Coda</h2>
+  <p><a href="https://validator.w3.org/nu/?doc=https%3A%2F%2Fioccc-src.github.io%2Ftemp-test-ioccc%2Fmarkdown.html">Nu HTML check this web page</a></p>
+  <p><a href="#top">Jump to top</a> <a href="#content">Jump to Content</a> <a href="#inventory">Jump to Inventory</a></p>
+</div>
+
+<!-- END: this line ends content from: inc/footer.default.html -->
+<!-- START: this line starts content from: inc/bottom.default.html -->
+
+</body>
+</html>
+
+<!-- END: this line ends content from: inc/bottom.default.html -->
diff --git a/markdown.md b/markdown.md
new file mode 100644
index 000000000..18fcc5010
--- /dev/null
+++ b/markdown.md
@@ -0,0 +1,197 @@
+# IOCCC markdown best practices
+
+The IOCCC makes extensive use of [markdown](https://daringfireball.net/projects/markdown/).
+For example, we [submitting to the IOCCC](faq.html#submit), we have people
+to submit remarks about entry in markdown format.  Every
+[winning IOCCC entry](years.html) uses a `README.md` markdown file
+as the basis for forming the `index.html` web page for that entry.
+All generated HTML pages on the [Official IOCCC web site](https://www.ioccc.org/index.html)
+start with some markdown content.
+
+See the [markdown syntax](https://www.markdownguide.org/basic-syntax) guide.
+See also [CommonMark Spec](https://spec.commonmark.org/current/).
+
+Nevertheless, the IOCCC does have certain practices that we ask authors to follow.
+
+In particular there are things we ask people to please do **NOT** use markdown files:
+
+
+## Do not use name attributes in HTML a tags
+
+Please do not use the HTML construct:
+
+```
+    <a name="string">\</a>
+```
+
+as those are **NOT** part of the HTML 5 standard.
+
+Instead use:
+
+```
+    <div id="string">...\</div>
+```
+
+where the "..." is the HTML you want to "name". The **div**
+encapsulates the HTML you want to name: I.e., the target of some
+"**\<a href="#string">**" or some other "**\<a href="URL#string">**"
+for the given page URL.
+
+There are certain HTML Elements that cannot have internal "**\<div
+id="string">...\</div>**".  For example you cannot do this:
+
+```
+    # <div id="string">This will not work</div>
+```
+
+For things like headings, you have to surround them as in:
+
+```
+    <div id="string">
+    # This will work
+    </div>
+```
+
+While some browsers will still recognize the HTML construct "**\<a
+name="string">\</a>**", they may not in the future.
+
+
+## Do not use trailing backslash outside of a code block
+
+Unless the line is inside a markdown code block, please do **NOT**
+end a markdown line with a trailing backslash ("\\").  Instead use
+a trailing "**\<br>**".
+
+Instead of:
+
+```
+    In markdown,\
+    do not use trailing\
+    backslashes outside of\
+    a code block
+```
+
+use:
+
+```
+    In markdown,<br>
+    use trailing<br>
+    br's outside of<br>
+    a code block
+```
+
+Again, use of a trailing backslash ("\\") inside a markdown code block is fine:
+
+````
+```
+    This is OK\
+    inside a\
+    markdown code\
+    block
+```
+````
+
+This will avoid `pandoc(1)` generating deprecated HTML elements such as:
+
+"**\<br />**"
+
+
+## Do not use markdown image elements
+
+Please do not use the markdown embedded image element.
+
+Instead of using this markdown element to embed an image:
+
+```
+    ![alt text](filename.png "Title")
+```
+
+Use a "img" HTML element with "alt", "alt", "width" and "length"
+attributes:
+
+```
+    <img src="filename.png"
+     alt="describe the filename.png image for someone who cannot view it"
+     width=PIXEL_WIDTH height=PIXEL_HEIGHT>
+```
+
+For example, instead of:
+
+```
+    ![1984-anonymous-tattoo.jpg](1984-anonymous-tattoo.jpg)
+```
+
+use this HTML:
+
+```
+    <img src="1984-anonymous-tattoo.jpg"
+     alt="image of a tattoo of the 1984 anonymous C code"
+     width=600 height=401>
+```
+
+The problem goes beyond the fact that `pandoc(1)` generates problematic
+HTML from the markdown image construct, the resulting HTML does not
+have "width" and "height" information so browsers have to slow down
+on rendering text around the image until it can internally determine
+the image size.
+
+
+## Do not use markdown style horizontal lines
+
+Please do not use "**---**"-style lines in markdown to create horizontal
+lines, nor to separate sections.
+
+Unless something is inside a markdown code block, do not start a
+line with 3 or more dashes ("-").
+
+Such causes `pandoc(1)` to generate "**\<hr />**".  The  "**\<hr
+/>**" has no effect in standard HTML 5 and interacts badly with
+unquoted attribute values.
+
+If a horizontal line is really needed, use:
+
+```
+    <hr>
+```
+
+If a short line is needed, use:
+
+```
+    <hr style="width:10%;text-align:left;margin-left:0">
+```
+
+
+## Do not use the strike HTML element
+
+Please not use the HTML element:
+
+```
+    <strike>...</strike>
+```
+
+Use instead:
+
+```
+    <del>...</del>
+```
+
+
+## Do not use tt HTML elements
+
+Please do not use the tt HTML elements:
+
+```html
+    <tt>The HTML 5 obsolete tt element is obsolete</tt>
+```
+
+Instead use either a monospaced span:
+
+```html
+    <span style="font-family: monospace;">Use of monospaced font is one option</span>
+```
+
+Or better and easier still, use an inline markdown code block:
+
+```
+    `inline markdown code block is easier and much better`
+```
diff --git a/sitemap.xml b/sitemap.xml
index ed3078483..3f37f9c62 100644
--- a/sitemap.xml
+++ b/sitemap.xml
@@ -19098,7 +19098,7 @@
 </url>
 <url>
     <loc>https://ioccc-src.github.io/temp-test-ioccc/bin/gen-top-html.sh</loc>
-    <lastmod>2024-04-17T01:29:11+00:00</lastmod>
+    <lastmod>2024-04-21T09:25:57+00:00</lastmod>
 </url>
 <url>
     <loc>https://ioccc-src.github.io/temp-test-ioccc/bin/gen-year-index.sh</loc>
@@ -19222,11 +19222,11 @@
 </url>
 <url>
     <loc>https://ioccc-src.github.io/temp-test-ioccc/faq.html</loc>
-    <lastmod>2024-04-20T20:35:51+00:00</lastmod>
+    <lastmod>2024-04-21T09:51:32+00:00</lastmod>
 </url>
 <url>
     <loc>https://ioccc-src.github.io/temp-test-ioccc/faq.md</loc>
-    <lastmod>2024-04-20T20:35:51+00:00</lastmod>
+    <lastmod>2024-04-21T09:47:11+00:00</lastmod>
 </url>
 <url>
     <loc>https://ioccc-src.github.io/temp-test-ioccc/.gitignore</loc>
@@ -19314,7 +19314,7 @@
 </url>
 <url>
     <loc>https://ioccc-src.github.io/temp-test-ioccc/inc/md2html.cfg</loc>
-    <lastmod>2024-04-21T05:39:44+00:00</lastmod>
+    <lastmod>2024-04-21T09:28:05+00:00</lastmod>
 </url>
 <url>
     <loc>https://ioccc-src.github.io/temp-test-ioccc/inc/navbar.default.html</loc>