mirror/ioccc
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Typo, format and consistency fixes in markdown.md

Browse Source
This commit is contained in:
Cody Boone Ferguson committed 2024-05-01 08:31:48 -07:00
1 parent b1516f0ed9
commit 6e38199684
2 files changed
+173 -223
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

markdown.html
+111 -165
View File
@@ -389,33 +389,32 @@ 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>Nevertheless, the IOCCC does have certain practices that we ask authors to follow.
Some these relate to use of markdown directly, others relate to injecting HTML Some these relate to use of markdown directly, others relate to injecting HTML
into the markdown file.</p> into the markdown file.</p>
<p>In particular there are things we ask people to please do <strong>NOT</strong> use markdown files:</p> <p>In particular there are things we ask people to please do <strong>NOT</strong> use in
<h2 id="do-not-use-name-attributes-in-html-a-tags">Do not use name attributes in HTML a tags</h2> markdown files:</p>
<p>Please do not use the HTML construct:</p> <h2 id="do-not-use-name-attributes-in-html-a-tags">Do NOT use name attributes in HTML a tags</h2>
<pre><code> &lt;a name=&quot;string&quot;&gt;\&lt;/a&gt; &lt;=== no thank you</code></pre> <p>Please do <strong>NOT</strong> use the HTML construct:</p>
<pre><code> &lt;a name=&quot;string&quot;&gt;...&lt;/a&gt; &lt;=== no thank you</code></pre>
<p>as those are <strong>NOT</strong> part of the HTML 5 standard.</p> <p>as those are <strong>NOT</strong> part of the HTML 5 standard.</p>
<p>Instead use:</p> <p>Instead use:</p>
<pre><code> &lt;div id=&quot;string&quot;&gt;...\&lt;/div&gt;</code></pre> <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> <p>where the <code>...</code> is the HTML you want to “name”. The <code>&lt;div&gt;</code>
encapsulates the HTML you want to name: I.e., the target of some 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>” <code>&lt;a href="#string"&gt;</code> or some other <code>&lt;a href="URL#string"&gt;</code>
for the given page URL.</p> for the given page URL.</p>
<p>There are certain HTML Elements that cannot have internal “<strong>&lt;div <p>There are certain HTML Elements that cannot have internal <code>&lt;div id="string"&gt;...&lt;/div&gt;</code>. For example you cannot do this:</p>
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>
<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> <p>For things like headings, you have to surround them as in:</p>
<pre><code> &lt;div id=&quot;string&quot;&gt; <pre><code> &lt;div id=&quot;string&quot;&gt;
# This will work # This will work
&lt;/div&gt;</code></pre> &lt;/div&gt;</code></pre>
<p>While some browsers will still recognize the HTML construct “<strong>&lt;a <p>While some browsers will still recognize the HTML construct <code>&lt;a name="string"&gt;...&lt;/a&gt;</code>, it is possible they might NOT in the future.</p>
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>
<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> <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 end a markdown line with a trailing backslash (<code>\</code>). Instead use
a trailing “<strong>&lt;br&gt;</strong>”.</p> a trailing <code>&lt;br&gt;</code>.</p>
<p>Instead of:</p> <p>Instead of:</p>
<pre><code> In markdown,\ &lt;=== no thank you <pre><code> In markdown,\ &lt;=== no thank you
do not use trailing\ do NOT use trailing\
backslashes outside of\ backslashes outside of\
a code block</code></pre> a code block</code></pre>
<p>use:</p> <p>use:</p>
@@ -423,19 +422,20 @@ a trailing “<strong>&lt;br&gt;</strong>”.</p>
use trailing&lt;br&gt; use trailing&lt;br&gt;
br&#39;s outside of&lt;br&gt; br&#39;s outside of&lt;br&gt;
a code block</code></pre> a code block</code></pre>
<p>Again, use of a trailing backslash (“\”) inside a markdown code block is fine:</p> <p>Again, use of a trailing backslash (<code>\</code>) inside a markdown code block is fine:</p>
<pre><code>``` <pre><code>```
This is OK\ This is OK\
inside a\ inside a\
markdown code\ markdown code\
block block
```</code></pre> ```</code></pre>
<p>This will avoid <code>pandoc(1)</code> generating deprecated HTML elements such as <code>\&lt;br /&gt;</code>.</p> <p>This will prevent <code>pandoc(1)</code> from generating deprecated HTML elements such as
<h2 id="do-not-use-markdown-image-elements">Do not use markdown image elements</h2> <code>&lt;br /&gt;</code>.</p>
<p>Please do not use the markdown embedded image element.</p> <h2 id="do-not-use-markdown-image-elements">Do NOT use markdown image elements</h2>
<p>Please do <strong>NOT</strong> use the markdown embedded image element.</p>
<p>Instead of using this markdown element to embed an image:</p> <p>Instead of using this markdown element to embed an image:</p>
<pre><code> ![alt text](filename.png &quot;Title&quot;) &lt;=== no thank you</code></pre> <pre><code> ![alt text](filename.png &quot;Title&quot;) &lt;=== no thank you</code></pre>
<p>Use a “img” HTML element with “alt”, “alt”, “width” and “length” <p>Use an <code>img</code> HTML element with <code>alt</code>, <code>width</code> and <code>length</code>
attributes:</p> attributes:</p>
<pre><code> &lt;img src=&quot;filename.png&quot; <pre><code> &lt;img src=&quot;filename.png&quot;
alt=&quot;describe the filename.png image for someone who cannot view it&quot; alt=&quot;describe the filename.png image for someone who cannot view it&quot;
@@ -447,173 +447,119 @@ attributes:</p>
alt=&quot;image of a tattoo of the 1984 anonymous C code&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;</code></pre>
<p>The problem goes beyond the fact that <code>pandoc(1)</code> generates problematic <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 HTML from the markdown image construct, the resulting HTML does NOT
have “width” and “height” information so browsers have to slow down have <code>width</code> and <code>height</code> information so browsers have to slow down
on rendering text around the image until it can internally determine on rendering text around the image until it can internally determine
the image size.</p> the image size.</p>
<h2 id="do-not-use-markdown-style-horizontal-lines">Do not use markdown style horizontal lines</h2> <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 <p>Please do <strong>NOT</strong> use <code>**---**</code>-style lines in markdown to create horizontal
lines, nor to separate sections.</p> lines or to separate sections.</p>
<p>Unless something is inside a markdown code block, do not start a <p>Unless something is inside a markdown code block, do NOT start a
line with 3 or more dashes (“-”).</p> line with 3 or more dashes (<code>-</code>s).</p>
<p>Such causes <code>pandoc(1)</code> to generate “<strong>&lt;hr /&gt;</strong>”. The “<strong>&lt;hr <p>Such causes <code>pandoc(1)</code> to generate <code>&lt;hr /&gt;</code>. The <code>&lt;hr /&gt;</code> has no effect in
/&gt;</strong>” has no effect in standard HTML 5 and interacts badly with standard HTML 5 and interacts badly with unquoted attribute values.</p>
unquoted attribute values.</p>
<p>If a horizontal line is really needed, use:</p> <p>If a horizontal line is really needed, use:</p>
<pre><code> &lt;hr&gt;</code></pre> <pre><code> &lt;hr&gt;</code></pre>
<p>If a short line is needed, use:</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> <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> <h2 id="do-not-use-the-strike-html-element">Do NOT use the strike HTML element</h2>
<p>Please not use HTML elements:</p> <p>Please NOT use HTML elements:</p>
<pre><code> &lt;strike&gt;...&lt;/strike&gt; &lt;=== no thank you</code></pre> <pre><code> &lt;strike&gt;...&lt;/strike&gt; &lt;=== no thank you</code></pre>
<p>Use instead:</p> <p>Use instead:</p>
<pre><code> &lt;del&gt;...&lt;/del&gt;</code></pre> <pre><code> &lt;del&gt;...&lt;/del&gt;</code></pre>
<h2 id="do-not-use-the-tt-html-element">Do not use the tt HTML element</h2> <h2 id="do-not-use-the-tt-html-element">Do NOT use the <code>&lt;tt&gt;</code> HTML element</h2>
<p>Please do not use the tt HTML elements:</p> <p>Please do <strong>NOT</strong> use the <code>&lt;tt&gt;</code> 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> <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> <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> <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> <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> <pre><code> `inline markdown code block is easier and much better`</code></pre>
<h2 id="do-not-use-un-indented-code-clocks">Do not use un-indented code clocks</h2> <h2 id="do-not-use-unindented-code-clocks">Do NOT use unindented code clocks</h2>
<p>Please do not start code blocks at the left-hand edge.</p> <p>Please do <strong>NOT</strong> start code blocks at the left-hand edge.</p>
<pre><code>``` <pre><code>```
This code block &lt;=== no thank you This code block &lt;=== no thank you
is not indendted is NOT indented
``` ```</code></pre>
``` <p>We request that you indent the code block by 4 spaces:</p>
<pre><code>```
We request that you indent the code block by 4 spaces: This code block
</code></pre> is indented 4 spaces
<pre><code> This code block ```</code></pre>
is intented 4 spaces</code></pre> <p>One exception is where change bars are needed, such as
<pre><code> those used in <code>next/rules.md</code> and in <code>next/guidelines.md</code>.</p>
One exception is where change bars are needed, such as <p>For example, <code>next/guidelines.md</code> uses this markdown code block:</p>
those used in `next/rules.md` and in `next/guidelines.md`. <pre><code>```
main() {
For example, `next/guidelines.md` uses this markdown code block:
</code></pre>
<pre><code> main() {
| void please_do_not_submit_this() { | void please_do_not_submit_this() {
| printf(&quot;The machine that goes BING!\n&quot;); | printf(&quot;The machine that goes BING!\n&quot;);
} }
| please_do_not_submit_this(); | please_do_not_submit_this();
}</code></pre> }
<pre><code> ```</code></pre>
<h2 id="do-not-add-trailing-slash-on-void-html-elements">Do NOT add trailing slash on void HTML elements</h2>
## Do not add trailing slash on void HTML elements <p>Please do <strong>NOT</strong> use a trailing slash on <a href="https://github.com/validator/validator/wiki/Markup-»-Void-elements">void HTML
elements</a>.</p>
Please do not use trailing slash on [void HTML <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
elements](https://github.com/validator/validator/wiki/Markup-»-Void-elements). tags</a>.</p>
<p>The trailing slash on void HTML elements has no effect and interacts badly with
See also this note on [trailing slashes in void-element start unquoted attribute values.</p>
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). <p>For example, please do NOT use:</p>
<pre><code> &lt;br/&gt; &lt;=== no thank you</code></pre>
The trailing slash on void HTML elements has no effect and interacts badly with unquoted attribute values. <p>Instead use just:</p>
<pre><code> &lt;br&gt;</code></pre>
For example, please do not use: <p>And for example, please do NOT use:</p>
<pre><code> &lt;hr/&gt; &lt;=== no thank you</code></pre>
``` <p>Instead use just:</p>
&lt;br/&gt; &lt;=== no thank you <pre><code> &lt;hr&gt;</code></pre>
``` <p>And for example, please do NOT use:</p>
<pre><code> &lt;img src=&quot;1984-anonymous-tattoo.jpg&quot;
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; alt=&quot;image of a tattoo of the 1984 anonymous C code&quot;
width=600 height=401 /&gt; &lt;=== no thank you width=600 height=401 /&gt; &lt;=== no thank you</code></pre>
``` <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; alt=&quot;image of a tattoo of the 1984 anonymous C code&quot;
width=600 height=401&gt; width=600 height=401&gt;</code></pre>
``` <p>etc.</p>
<h2 id="do-not-end-markdown-links-in">Do NOT end markdown links in “))”</h2>
etc. <p>Please do <strong>NOT</strong> end a markdown links with a double closed parenthesis “))”.</p>
<p>Markdown links that end in “))” complicate parsing and sometimes lead
to incorrect URLs or file paths.</p>
## Do not end markdown links in )) <p>Instead of:</p>
<pre><code> [some text](https://example.com/foo_(bar)) &lt;=== no thank you</code></pre>
Please do not end a markdown links with a double closed parenthesis &quot;))&quot;. <p>Use:</p>
<pre><code> [some text](https://example.com/foo_&amp;#x28;bar&amp;#x29;)</code></pre>
Markdown links that end in &quot;))&quot; complicate parsing and sometimes lead <p>Instead of:</p>
to incorrect URLs or file paths. <pre><code> This thing, ([some text](some/path)), is NOT ideal. &lt;=== no thank you</code></pre>
<p>Use:</p>
Instead of: <pre><code> This thing, [some text](some/path), is better.</code></pre>
<h2 id="do-not-place-text-on-the-next-line-after-a-markdown-code-block">Do NOT place text on the next line after a markdown code block</h2>
``` <p>Please do <strong>NOT</strong> place text on the next line after a markdown code block.
[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 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 as this makes it easier to detect when markdown code blocks are
not properly indented. NOT properly indented.</p>
<p>Instead of:</p>
<pre><code>```
int
main(int foo)
{
return foo;
}
```
C compilers cannot be given a -Wno-main-arg-errors flag. &lt;=== no thank you</code></pre>
<p>Use:</p>
<pre><code>```
int
main(int foo)
{
return foo;
}
```
Instead of: C compilers cannot be given a -Wno-main-arg-errors flag.
</code></pre>
<pre><code> int BTW: note the blank line after the code block.</code></pre>
main(int foo) <h2 id="do-not-put-s-or-s-in-markdown-link-titles">Do NOT put “(”s or “)”s in markdown link titles</h2>
{ <p>Please do <strong>NOT</strong> use parenthesis inside the markdown link titles.</p>
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> <p>Instead of:</p>
<pre><code> [some (text)](https://example.com/cyrds) &lt;=== no thank you</code></pre> <pre><code> [some (text)](https://example.com/cyrds) &lt;=== no thank you</code></pre>
<p>Use:</p> <p>Use:</p>
markdown.md
+62 -58
View File
@@ -15,15 +15,16 @@ Nevertheless, the IOCCC does have certain practices that we ask authors to follo
Some these relate to use of markdown directly, others relate to injecting HTML Some these relate to use of markdown directly, others relate to injecting HTML
into the markdown file. into the markdown file.
In particular there are things we ask people to please do **NOT** use markdown files: In particular there are things we ask people to please do **NOT** use in
markdown files:
## Do not use name attributes in HTML a tags ## Do NOT use name attributes in HTML a tags
Please do not use the HTML construct: Please do **NOT** use the HTML construct:
``` ```
<a name="string">\</a> <=== no thank you <a name="string">...</a> <=== no thank you
``` ```
as those are **NOT** part of the HTML 5 standard. as those are **NOT** part of the HTML 5 standard.
@@ -31,19 +32,19 @@ as those are **NOT** part of the HTML 5 standard.
Instead use: Instead use:
``` ```
<div id="string">...\</div> <div id="string">...</div>
``` ```
where the "..." is the HTML you want to "name". The **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 encapsulates the HTML you want to name: i.e., the target of some
"**\<a href="#string">**" or some other "**\<a href="URL#string">**" `<a href="#string">` or some other `<a href="URL#string">`
for the given page URL. for the given page URL.
There are certain HTML Elements that cannot have internal "**\<div There are certain HTML Elements that cannot have internal `<div
id="string">...\</div>**". For example you cannot do this: id="string">...</div>`. For example you cannot do this:
``` ```
# <div id="string">This will not work</div> # <div id="string">This will NOT work</div>
``` ```
For things like headings, you have to surround them as in: For things like headings, you have to surround them as in:
@@ -54,21 +55,21 @@ For things like headings, you have to surround them as in:
</div> </div>
``` ```
While some browsers will still recognize the HTML construct "**\<a While some browsers will still recognize the HTML construct `<a
name="string">\</a>**", they may not in the future. name="string">...</a>`, it is possible they might NOT in the future.
## Do not use trailing backslash outside of a code block ## Do NOT use trailing backslash outside of a code block
Unless the line is inside a markdown code block, please do **NOT** Unless the line is inside a markdown code block, please do **NOT**
end a markdown line with a trailing backslash ("\\"). Instead use end a markdown line with a trailing backslash (`\`). Instead use
a trailing "**\<br>**". a trailing `<br>`.
Instead of: Instead of:
``` ```
In markdown,\ <=== no thank you In markdown,\ <=== no thank you
do not use trailing\ do NOT use trailing\
backslashes outside of\ backslashes outside of\
a code block a code block
``` ```
@@ -82,7 +83,7 @@ use:
a code block a code block
``` ```
Again, use of a trailing backslash ("\\") inside a markdown code block is fine: Again, use of a trailing backslash (`\`) inside a markdown code block is fine:
```` ````
``` ```
@@ -93,12 +94,13 @@ Again, use of a trailing backslash ("\\") inside a markdown code block is fine:
``` ```
```` ````
This will avoid `pandoc(1)` generating deprecated HTML elements such as `\<br />`. This will prevent `pandoc(1)` from generating deprecated HTML elements such as
`<br />`.
## Do not use markdown image elements ## Do NOT use markdown image elements
Please do not use the markdown embedded image element. Please do **NOT** use the markdown embedded image element.
Instead of using this markdown element to embed an image: Instead of using this markdown element to embed an image:
@@ -106,7 +108,7 @@ Instead of using this markdown element to embed an image:
![alt text](filename.png "Title") <=== no thank you ![alt text](filename.png "Title") <=== no thank you
``` ```
Use a "img" HTML element with "alt", "alt", "width" and "length" Use an `img` HTML element with `alt`, `width` and `length`
attributes: attributes:
``` ```
@@ -130,23 +132,22 @@ use this HTML:
``` ```
The problem goes beyond the fact that `pandoc(1)` generates problematic The problem goes beyond the fact that `pandoc(1)` generates problematic
HTML from the markdown image construct, the resulting HTML does not HTML from the markdown image construct, the resulting HTML does NOT
have "width" and "height" information so browsers have to slow down have `width` and `height` information so browsers have to slow down
on rendering text around the image until it can internally determine on rendering text around the image until it can internally determine
the image size. the image size.
## Do not use markdown style horizontal lines ## Do NOT use markdown style horizontal lines
Please do not use "**---**"-style lines in markdown to create horizontal Please do **NOT** use `**---**`-style lines in markdown to create horizontal
lines, nor to separate sections. lines or to separate sections.
Unless something is inside a markdown code block, do not start a Unless something is inside a markdown code block, do NOT start a
line with 3 or more dashes ("-"). line with 3 or more dashes (`-`s).
Such causes `pandoc(1)` to generate "**\<hr />**". The "**\<hr Such causes `pandoc(1)` to generate `<hr />`. The `<hr />` has no effect in
/>**" has no effect in standard HTML 5 and interacts badly with standard HTML 5 and interacts badly with unquoted attribute values.
unquoted attribute values.
If a horizontal line is really needed, use: If a horizontal line is really needed, use:
@@ -161,9 +162,9 @@ If a short line is needed, use:
``` ```
## Do not use the strike HTML element ## Do NOT use the strike HTML element
Please not use HTML elements: Please NOT use HTML elements:
``` ```
<strike>...</strike> <=== no thank you <strike>...</strike> <=== no thank you
@@ -176,9 +177,9 @@ Use instead:
``` ```
## Do not use the tt HTML element ## Do NOT use the `<tt>` HTML element
Please do not use the tt HTML elements: Please do **NOT** use the `<tt>` HTML elements:
```html ```html
<tt>The HTML 5 obsolete tt element is obsolete</tt> <=== no thank you <tt>The HTML 5 obsolete tt element is obsolete</tt> <=== no thank you
@@ -197,26 +198,28 @@ Or better and easier still, use an inline markdown code block:
``` ```
## Do not use un-indented code clocks ## Do NOT use unindented code clocks
Please do not start code blocks at the left-hand edge. Please do **NOT** start code blocks at the left-hand edge.
```` ````
``` ```
This code block <=== no thank you This code block <=== no thank you
is not indendted is NOT indented
```
``` ```
````
We request that you indent the code block by 4 spaces: We request that you indent the code block by 4 spaces:
```` ````
``` ```
This code block This code block
is intented 4 spaces is indented 4 spaces
``` ```
```` ````
One exception is where change bars are needed, such as One exception is where change bars are needed, such as
those used in `next/rules.md` and in `next/guidelines.md`. those used in `next/rules.md` and in `next/guidelines.md`.
@@ -234,17 +237,18 @@ For example, `next/guidelines.md` uses this markdown code block:
```` ````
## Do not add trailing slash on void HTML elements ## Do NOT add trailing slash on void HTML elements
Please do not use trailing slash on [void HTML Please do **NOT** use a trailing slash on [void HTML
elements](https://github.com/validator/validator/wiki/Markup-»-Void-elements). elements](https://github.com/validator/validator/wiki/Markup-»-Void-elements).
See also this note on [trailing slashes in void-element start 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). 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. The trailing slash on void HTML elements has no effect and interacts badly with
unquoted attribute values.
For example, please do not use: For example, please do NOT use:
``` ```
<br/> <=== no thank you <br/> <=== no thank you
@@ -256,7 +260,7 @@ Instead use just:
<br> <br>
``` ```
And for example, please do not use: And for example, please do NOT use:
``` ```
<hr/> <=== no thank you <hr/> <=== no thank you
@@ -268,7 +272,7 @@ Instead use just:
<hr> <hr>
``` ```
And for example, please do not use: And for example, please do NOT use:
``` ```
<img src="1984-anonymous-tattoo.jpg" <img src="1984-anonymous-tattoo.jpg"
@@ -287,9 +291,9 @@ Instead use just:
etc. etc.
## Do not end markdown links in )) ## Do NOT end markdown links in "))"
Please do not end a markdown links with a double closed parenthesis "))". Please do **NOT** end a markdown links with a double closed parenthesis "))".
Markdown links that end in "))" complicate parsing and sometimes lead Markdown links that end in "))" complicate parsing and sometimes lead
to incorrect URLs or file paths. to incorrect URLs or file paths.
@@ -309,7 +313,7 @@ Use:
Instead of: Instead of:
``` ```
This thing ([some text](some/path)) is not ideal. <=== no thank you This thing, ([some text](some/path)), is NOT ideal. <=== no thank you
``` ```
Use: Use:
@@ -319,12 +323,12 @@ Use:
``` ```
## Do not place text on the next line after a markdown code block ## 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. 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 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 as this makes it easier to detect when markdown code blocks are
not properly indented. NOT properly indented.
Instead of: Instead of:
@@ -352,13 +356,13 @@ Use:
C compilers cannot be given a -Wno-main-arg-errors flag. C compilers cannot be given a -Wno-main-arg-errors flag.
BTW: Not the blank line after the code block. BTW: note the blank line after the code block.
```` ````
## Do not put ('s or )' markdown link titles ## Do NOT put "("s or ")"s in markdown link titles
Please do not use parenthesis inside the markdown link titles. Please do **NOT** use parenthesis inside the markdown link titles.
Instead of: Instead of: