fix non-indented markdown code blocks

We have fixed cases where markdown code blocks were not properly intended.

Updated `markdown.md` to discuss how markdown code blocks should be indented
and how blank lines should follow a markdown code block.

We used this shell script to find problematic code blocks:

```sh
find . -name '*.md' ! -name markdown.md -print | xargs pcregrep -M '^``.*\n[^|`\n \t]'
```

Ran `make www` to perform the above.

2012/tromp/README.md

@@ -373,6 +373,7 @@ and change it to BLC8 with
     $ wc rev.Blc
 	0 1 9 rev.Blc
 ```
+
 and then try it out with:
 
 ``` <!---sh-->

2018/ferguson/README.md

@@ -744,7 +744,7 @@ Keep in mind the way I display the generations and the fact that generation 0
 has no parents; it is generation 1 that starts working towards the goal. You'll
 see also **(mutation)** at the end of the line at this point (if you enable
 monkey mode you'll find that it shows something else). The lines that only have
-`` are separators: you won't see this between generation 0 and 1 but you will
+back-quote ("\`") are separators: you won't see this between generation 0 and 1 but you will
 between future generations - as well as the final answer (if the answer is in
 generation 0 you won't see the ``).
 

2018/ferguson/index.html

@@ -895,7 +895,9 @@ bash shell built-in utility: that isn’t output from my entry.</p>
 has no parents; it is generation 1 that starts working towards the goal. You’ll
 see also <strong>(mutation)</strong> at the end of the line at this point (if you enable
 monkey mode you’ll find that it shows something else). The lines that only have
-<code>are separators: you won't see this between generation 0 and 1 but you will between future generations - as well as the final answer (if the answer is in generation 0 you won't see the</code>).</p>
+back-quote (“`”) are separators: you won’t see this between generation 0 and 1 but you will
+between future generations - as well as the final answer (if the answer is in
+generation 0 you won’t see the ``).</p>
 <div id="test">
 <p>One final thing to consider is that <strong>the program doesn’t directly read from a
 file</strong>. This combined with the way the shell works could possibly confuse some

2019/mills/README.md

@@ -412,7 +412,6 @@ performance, at the cost of a much larger parameter space.
 
 **IMPORTANT NOTE**:
 
-```
 Since OMLET uses the system stack for network storage,
 larger networks may cause OMLET to crash (typically with a message like
 Segmentation fault) unless the system stack size is first increased.
@@ -422,7 +421,6 @@ with ulimit -Hs and set it with ulimit -s 65532 (replacing 65532
 with the actual hard limit).  On csh/tcsh shells, you can view
 the hard limit with limit -h stacksize and set it with
 limit stacksize 65532 (replacing 65532 with the actual hard limit).
-```
 
 <hr style="width:10%;text-align:left;margin-left:0">
 

2019/mills/index.html

@@ -686,15 +686,15 @@ parameters and its own hidden state vector. This will improve the network’s
 performance, at the cost of a much larger parameter space.</p>
 <hr style="width:10%;text-align:left;margin-left:0">
 <p><strong>IMPORTANT NOTE</strong>:</p>
-<pre><code>Since OMLET uses the system stack for network storage,
+<p>Since OMLET uses the system stack for network storage,
 larger networks may cause OMLET to crash (typically with a message like
 Segmentation fault) unless the system stack size is first increased.
-The exact command for doing so depends on your shell and your system&#39;s
+The exact command for doing so depends on your shell and your system’s
 hard limits. On sh/ksh/bash shells, you can view the hard limit
 with ulimit -Hs and set it with ulimit -s 65532 (replacing 65532
 with the actual hard limit). On csh/tcsh shells, you can view
 the hard limit with limit -h stacksize and set it with
-limit stacksize 65532 (replacing 65532 with the actual hard limit).</code></pre>
+limit stacksize 65532 (replacing 65532 with the actual hard limit).</p>
 <hr style="width:10%;text-align:left;margin-left:0">
 <p>You can try the deeper network by doing</p>
 <pre><code>    make rnn2</code></pre>

markdown.html

@@ -464,11 +464,11 @@ unquoted attribute values.</p>
 <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>
+<p>Please not use HTML elements:</p>
 <pre><code>    &lt;strike&gt;...&lt;/strike&gt;        &lt;=== no thank you</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>
+<h2 id="do-not-use-the-tt-html-element">Do not use the tt HTML element</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 class="er">&lt;</span>=== no thank you</span></code></pre></div>
 <p>Instead use either a monospaced span:</p>
@@ -487,42 +487,131 @@ We request that you indent the code block by 4 spaces:
 </code></pre>
 <pre><code>    This code block
     is intented 4 spaces</code></pre>
-<p>````</p>
+<pre><code>
-<h2 id="do-not-add-trailing-slash-on-void-html-elements">Do not add trailing slash on void HTML elements</h2>
+One exception is where change bars are needed, such as
-<p>Please do not use trailing slash on <a href="https://github.com/validator/validator/wiki/Markup-»-Void-elements">void HTML
+those used in `next/rules.md` and in `next/guidelines.md`.
-elements</a>.</p>
+
-<p>See also this note on <a href="https://github.com/validator/validator/wiki/Markup-»-Void-elements#trailing-slashes-in-void-element-start-tags-do-not-mark-the-start-tags-as-self-closing">trailing slashes in void-element start
+For example, `next/guidelines.md` uses this markdown code block:
-tags</a>.</p>
+</code></pre>
-<p>The trailing slash on void HTML elements has no effect and interacts badly with unquoted attribute values.</p>
+<pre><code>    main() {
-<p>For example, please do not use:</p>
+|       void please_do_not_submit_this() {
-<pre><code>    &lt;br/&gt;       &lt;=== no thank you</code></pre>
+|           printf(&quot;The machine that goes BING!\n&quot;);
-<p>Instead use just:</p>
+        }
-<pre><code>    &lt;br&gt;</code></pre>
+|       please_do_not_submit_this();
-<p>And for example, please do not use:</p>
+    }</code></pre>
-<pre><code>    &lt;hr/&gt;       &lt;=== no thank you</code></pre>
+<pre><code>
-<p>Instead use just:</p>
+
-<pre><code>    &lt;hr&gt;</code></pre>
+## Do not add trailing slash on void HTML elements
-<p>And for example, please do not use:</p>
+
-<pre><code>    &lt;img src=&quot;1984-anonymous-tattoo.jpg&quot;
+Please do not use trailing slash on [void HTML
+elements](https://github.com/validator/validator/wiki/Markup-»-Void-elements).
+
+See also this note on [trailing slashes in void-element start
+tags](https://github.com/validator/validator/wiki/Markup-»-Void-elements#trailing-slashes-in-void-element-start-tags-do-not-mark-the-start-tags-as-self-closing).
+
+The trailing slash on void HTML elements has no effect and interacts badly with unquoted attribute values.
+
+For example, please do not use:
+
+```
+    &lt;br/&gt;       &lt;=== no thank you
+```
+
+Instead use just:
+
+```
+    &lt;br&gt;
+```
+
+And for example, please do not use:
+
+```
+    &lt;hr/&gt;       &lt;=== no thank you
+```
+
+Instead use just:
+
+```
+    &lt;hr&gt;
+```
+
+And for example, please do not use:
+
+```
+    &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;                                    &lt;=== no thank you</code></pre>
+     width=600 height=401 /&gt;                                    &lt;=== no thank you
-<p>Instead use just:</p>
+```
-<pre><code>    &lt;img src=&quot;1984-anonymous-tattoo.jpg&quot;
+
+Instead use just:
+
+```
+    &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>
+     width=600 height=401&gt;
-<p>etc.</p>
+```
-<h2 id="do-not-end-markdown-links-in">Do not end markdown links in ))</h2>
+
-<p>Please do not end a markdown links with a double closed parenthesis “))”.</p>
+etc.
-<p>Markdown links that end in “))” complicate parsing and sometimes lead
+
-to incorrect URLs or file paths.</p>
+
-<p>Instead of:</p>
+## Do not end markdown links in ))
-<pre><code>    [some text](https://example.com/foo_(bar))  &lt;=== no thank you</code></pre>
+
-<p>Use:</p>
+Please do not end a markdown links with a double closed parenthesis &quot;))&quot;.
-<pre><code>    [some text](https://example.com/foo_&amp;#x28;bar&amp;#x29;)</code></pre>
+
-<p>Instead of:</p>
+Markdown links that end in &quot;))&quot; complicate parsing and sometimes lead
-<pre><code>    This thing ([some text](some/path)) is not ideal.   &lt;=== no thank you</code></pre>
+to incorrect URLs or file paths.
-<p>Use:</p>
+
-<pre><code>    This thing, [some text](some/path), is better.</code></pre>
+Instead of:
+
+```
+    [some text](https://example.com/foo_(bar))  &lt;=== no thank you
+```
+
+Use:
+
+```
+    [some text](https://example.com/foo_&amp;#x28;bar&amp;#x29;)
+```
+
+Instead of:
+
+```
+    This thing ([some text](some/path)) is not ideal.   &lt;=== no thank you
+```
+
+Use:
+
+```
+    This thing, [some text](some/path), is better.
+```
+
+
+## Do not place text on the next line after a markdown code block
+
+Please do not place text on the next line after a markdown code block.
+Instead, place a blank line after the end of a markdown code block
+is this makes it easier to detect when markdown code blocks are
+not properly indented.
+
+Instead of:
+</code></pre>
+<pre><code>    int
+    main(int foo)
+    {
+        return foo;
+    }</code></pre>
+<p>C compilers cannot be given a -Wno-main-arg-errors flag. &lt;=== no thank you</p>
+<pre><code>
+Use:
+</code></pre>
+<pre><code>    int
+    main(int foo)
+    {
+        return foo;
+    }</code></pre>
+<p>C compilers cannot be given a -Wno-main-arg-errors flag.</p>
+<p>BTW: Not the blank line after the code block.
+````</p>
 <h2 id="do-not-put-s-or-markdown-link-titles">Do not put (‘s or )’ markdown link titles</h2>
 <p>Please do not use parenthesis inside the markdown link titles.</p>
 <p>Instead of:</p>

markdown.md

@@ -163,7 +163,7 @@ If a short line is needed, use:
 
 ## Do not use the strike HTML element
 
-Please not use the HTML element:
+Please not use HTML elements:
 
 ```
     <strike>...</strike>	<=== no thank you
@@ -176,7 +176,7 @@ Use instead:
 ```
 
 
-## Do not use tt HTML elements
+## Do not use the tt HTML element
 
 Please do not use the tt HTML elements:
 
@@ -217,6 +217,22 @@ We request that you indent the code block by 4 spaces:
 ```
 ````
 
+One exception is where change bars are needed, such as
+those used in `next/rules.md` and in `next/guidelines.md`.
+
+For example, `next/guidelines.md` uses this markdown code block:
+
+````
+```
+    main() {
+|       void please_do_not_submit_this() {
+|           printf("The machine that goes BING!\n");
+        }
+|       please_do_not_submit_this();
+    }
+```
+````
+
 
 ## Do not add trailing slash on void HTML elements
 
@@ -303,6 +319,43 @@ Use:
 ```
 
 
+## Do not place text on the next line after a markdown code block
+
+Please do not place text on the next line after a markdown code block.
+Instead, place a blank line after the end of a markdown code block
+is this makes it easier to detect when markdown code blocks are
+not properly indented.
+
+Instead of:
+
+````
+```
+    int
+    main(int foo)
+    {
+        return foo;
+    }
+```
+C compilers cannot be given a -Wno-main-arg-errors flag.	 <=== no thank you
+````
+
+Use:
+
+````
+```
+    int
+    main(int foo)
+    {
+        return foo;
+    }
+```
+
+C compilers cannot be given a -Wno-main-arg-errors flag.
+
+BTW: Not the blank line after the code block.
+````
+
+
 ## Do not put ('s or )' markdown link titles
 
 Please do not use parenthesis inside the markdown link titles.

next/guidelines.html

@@ -25,7 +25,7 @@
 <!-- END: this line ends content from: inc/head.default.html -->
 
 <!-- -->
-<!-- This web page was formed via the tool: bin/gen-status.sh -->
+<!-- This web page was formed via the tool: bin/gen-top-html.sh -->
 <!-- The content of main section of this web page came from: next/guidelines.md -->
 <!-- -->
 

next/rules.html

@@ -25,7 +25,7 @@
 <!-- END: this line ends content from: inc/head.default.html -->
 
 <!-- -->
-<!-- This web page was formed via the tool: bin/gen-status.sh -->
+<!-- This web page was formed via the tool: bin/gen-top-html.sh -->
 <!-- The content of main section of this web page came from: next/rules.md -->
 <!-- -->
 

thanks-for-help.md

@@ -1506,6 +1506,7 @@ changed from `char*s` to `char s[]`):
 ```
     !.Xop.fssps!.Xop.sfuvso.uzqf!.Xop.jnqmjdju.gvodujpo.efdmbsbujpo
 ```
+
 and then the call to `system()` had to be changed to:
 
 ``` <!---c-->