Fix and expand markdown guidelines
Improved wording of some of the titles. Added div ids to each guideline so that we can link directly to them if necessary. The code block examples now specify a language so that when language highlighting is available it will show up better. I added this for those that are not wanted and those that are in the hopes it will stand out more. I added a guideline that for italics one should use underscores (_) as using single asterisks is known to cause some parsers problems (and this goes more so, perhaps, when it is bold italic text which would otherwise be three asterisks in a row). I first became aware of this from a document on some markdown parsers and it seems like a good idea to note. Added that it is preferable and easier to use markdown links if possible (along the lines of how it's easier and preferable to use inline code blocks instead of spans). This would also help with consistency. Typo fixes (some in code blocks, perhaps some outside as well). For tabs/spaces discussion I added a tip for vim users. Maybe this should be in the FAQ instead but I am not sure. Move rule about not including literal parentheses in markdown links to right below the rule about not ending markdown links with '))'.
This commit is contained in:
Cody Boone Ferguson committed
1 parent
dbf6921b3a
commit
1b770bb73d
2 files changed
+444
-157
No files matched your search
+175
-62
@@ -388,7 +388,9 @@
|
||||
<!-- 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 -->
|
||||
<div id="guidelines">
|
||||
<h1 id="ioccc-markdown-guidelines">IOCCC markdown guidelines</h1>
|
||||
</div>
|
||||
<p>The IOCCC makes extensive use of <a href="https://daringfireball.net/projects/markdown/">markdown</a>.
|
||||
For example, when submitting to the IOCCC
|
||||
we have people
|
||||
@@ -406,7 +408,11 @@ Some of these relate to use of markdown directly and others relate to injecting
|
||||
into the markdown file.</p>
|
||||
<p>In particular there are things we ask people to please <strong>NOT</strong> use in
|
||||
markdown files for the IOCCC:</p>
|
||||
<h2 id="please-do-not-use-name-attributes-in-html-a-..-hyperlink-elements">Please do NOT use name attributes in HTML <code><a ..></code> hyperlink elements</h2>
|
||||
<div id="name">
|
||||
<div id="anchor-name">
|
||||
<h2 id="please-do-not-use-the-name-attributes-in-html-a...a-hyperlink-elements">Please do NOT use the <code>name</code> attributes in HTML <code><a>...</a></code> hyperlink elements</h2>
|
||||
</div>
|
||||
</div>
|
||||
<p>Please do <strong>NOT</strong> use the HTML construct:</p>
|
||||
<pre><code> <a name="string">...</a> <=== no thank you</code></pre>
|
||||
<p>as those are <strong>NOT</strong> part of the HTML 5 standard.</p>
|
||||
@@ -416,43 +422,71 @@ markdown files for the IOCCC:</p>
|
||||
encapsulates the HTML you want to name: i.e., the target of some
|
||||
<code><a href="#string"></code> or some other <code><a href="URL#string"></code>
|
||||
for the given page URL.</p>
|
||||
<p>There are certain HTML Elements that cannot have internal <code><div id="string">...</div></code>.</p>
|
||||
<p>For example:</p>
|
||||
<h3 id="important-point">IMPORTANT POINT:</h3>
|
||||
<p>There are certain markdown constructs that <strong>CANNOT</strong> have an <strong>internal</strong> <code><div id="string">...</div></code> element.</p>
|
||||
<p>An example is headings (lines that start with a <code>#</code>). For example:</p>
|
||||
<pre><code> # <div id="string">THIS WILL NOT WORK!</div> <=== this will not work</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 with the <code><div id="string">...</div></code> element, as in:</p>
|
||||
<pre><code> <div id="string">
|
||||
# This will work
|
||||
</div></code></pre>
|
||||
<p>While some browsers will still recognize the HTML construct <code><a name="string">...</a></code>, it is possible they might NOT in the future.</p>
|
||||
<p>While some browsers will still recognize the HTML construct <code><a name="string">...</a></code>, it is possible <strong>they MIGHT NOT</strong> in the future.</p>
|
||||
<div id="links">
|
||||
<h2 id="if-you-can-it-is-preferable-to-use-markdown-links-rather-than-a...a">If you can, it is PREFERABLE to use markdown links rather than <code><a>...</a></code></h2>
|
||||
</div>
|
||||
<p>It is easier and preferred to use markdown links rather than HTML <code><a>..</a></code>
|
||||
anchors.</p>
|
||||
<p>Instead of:</p>
|
||||
<pre><code> Use of <a href="#links>HTML anchors</a>
|
||||
is one option, however ...</code></pre>
|
||||
<pre><code> [markdown links](#links) are easier and preferred</code></pre>
|
||||
<div id="strike">
|
||||
<div id="del">
|
||||
<h2 id="please-do-not-use-the-strike-or-the-s-html-element">Please do NOT use the <code><strike></code> or the <code><s></code> HTML element</h2>
|
||||
<p>Please do NOT use the obsolete <code><strike></code> or the obsolete <code><s></code> (<del><em>strikeout</em></del>) HTML elements:</p>
|
||||
</div>
|
||||
</div>
|
||||
<p>Please do <strong>NOT</strong> use the obsolete <code><strike></code> or the obsolete <code><s></code>
|
||||
(<del><strong>strikeout</strong></del>) HTML elements:</p>
|
||||
<pre><code> <strike>...</strike> <=== no thank you
|
||||
<s>...</s> <=== no thank you</code></pre>
|
||||
<p>Use instead:</p>
|
||||
<pre><code> <del>...</del></code></pre>
|
||||
<div id="underline">
|
||||
<div id="ins">
|
||||
<h2 id="please-do-not-use-the-u-html-element">Please do NOT use the <code><u></code> HTML element</h2>
|
||||
<p>Please NOT use the obsolete <code><u></code> (<ins><em>underline</em></ins>) HTML element:</p>
|
||||
</div>
|
||||
</div>
|
||||
<p>Please <strong>NOT</strong> use the obsolete <code><u></code> (<ins><em>underline</em></ins>) HTML element:</p>
|
||||
<pre><code> <u>...</u> <=== no thank you</code></pre>
|
||||
<p>Use instead:</p>
|
||||
<pre><code> <ins>...</ins></code></pre>
|
||||
<div id="tt">
|
||||
<div id="span">
|
||||
<h2 id="please-do-not-use-the-tt-html-element">Please do NOT use the <code><tt></code> HTML element</h2>
|
||||
<p>Please do <strong>NOT</strong> use the obsolete <code><tt></code> (<span style="font-family: monospace;"><em>teletype</em></span>) HTML element:</p>
|
||||
<pre><code> <tt>The obsolete tt element is obsolete</tt> <=== no thank you</code></pre>
|
||||
<p>Instead use either a monospaced span:</p>
|
||||
</div>
|
||||
</div>
|
||||
<p>Please do <strong>NOT</strong> use the obsolete <code><tt></code>
|
||||
(<span style="font-family: monospace;"><strong>teletype</strong></span>) HTML element:</p>
|
||||
<pre><code> <tt>The tt element is obsolete</tt> <=== no thank you</code></pre>
|
||||
<p>Instead use either a monospaced <code><span></code> or an inline markdown code block:</p>
|
||||
<pre><code> <span style="font-family: monospace;">Use of a monospaced font
|
||||
is one option,
|
||||
however ... </span></code></pre>
|
||||
<p>We recommend using the inline markdown code block method instead:</p>
|
||||
<pre><code> Using the `inline markdown code block` is easier and is `preferred`.</code></pre>
|
||||
<pre><code> Using the `inline markdown code block` is easier and is **preferred**.</code></pre>
|
||||
<div id="unindented">
|
||||
<div id="indented">
|
||||
<h2 id="please-do-not-use-unindented-code-blocks">Please do NOT use unindented code blocks</h2>
|
||||
<p>Please do <strong>NOT</strong> start code blocks at the left-hand edge.</p>
|
||||
</div>
|
||||
</div>
|
||||
<p>Please do <strong>NOT</strong> start code blocks at the first column.</p>
|
||||
<p>For example:</p>
|
||||
<pre><code>``` <!---sh-->
|
||||
echo "This code block is NOT indented\" <=== no thank you
|
||||
<pre class="<!---markdown-->"><code>``` <!---sh-->
|
||||
echo "This code block is NOT indented" <=== no thank you
|
||||
```</code></pre>
|
||||
<p>We request that you indent the code block by multiples of 4 ASCII spaces:</p>
|
||||
<pre><code>``` <!---sh-->
|
||||
echo "This code block is intended by mutiples of 4 spaces"
|
||||
<p>We request that you indent the code block by multiples of 4 ASCII <strong>SPACES</strong>:</p>
|
||||
<pre class="<!---markdown-->"><code>``` <!---sh-->
|
||||
echo "This code block is indented by mutiples of 4 spaces"
|
||||
|
||||
# The top level starts with a 4 ASCII space indent.
|
||||
#
|
||||
@@ -462,19 +496,23 @@ echo "This code block is NOT indented\" <===
|
||||
# etc.
|
||||
```</code></pre>
|
||||
<p>Moreover:</p>
|
||||
<pre><code>```
|
||||
<pre class="<!---markdown-->"><code>```
|
||||
The same thing applies to any markdown block surrounded by ``` lines.
|
||||
```</code></pre>
|
||||
<p>Please do <strong>NOT</strong> indent using ASCII tab characters in markdown files.</p>
|
||||
<div id="tabs">
|
||||
<div id="spaces">
|
||||
<h2 id="please-do-not-use-ascii-tabs-in-markdown-files">Please do NOT use ASCII tabs in markdown files</h2>
|
||||
</div>
|
||||
</div>
|
||||
<p>While we have nothing against the ASCII tab character in general,
|
||||
we have discovered that ASCII tab characters create problems when
|
||||
used as part of the leading whitespace within a markdown file.</p>
|
||||
<p>If you need to indent 2 or more levels, use multiples of 4 ASCII
|
||||
spaces. Please do <strong>NOT</strong> indent with ASCII tabs, <strong>NOR</strong> use any
|
||||
<strong>SPACES</strong>. Please do <strong>NOT</strong> indent with ASCII tabs, <strong>OR</strong> use any
|
||||
ASCII tab characters anywhere inside a markdown file:</p>
|
||||
<p>For example:</p>
|
||||
<pre><code>```
|
||||
<pre class="<!---markdown-->"><code>```
|
||||
Please do **NOT** use ASCII tabs in markdown files. <=== no thank you
|
||||
Please do **NOT** indent markdown with ASCII tabs. <=== no thank you
|
||||
|
||||
@@ -483,7 +521,7 @@ ASCII tab characters anywhere inside a markdown file:</p>
|
||||
```</code></pre>
|
||||
<p>And to clarify, we are only talking about markdown files,
|
||||
not C code or any other non-markdown content:</p>
|
||||
<pre><code> printf("Is is fine to use tabs in Obfucated C code.\n");
|
||||
<pre class="<!---c-->"><code> printf("It is fine to use tabs in Obfuscated C code.\n");
|
||||
/* if you wish */
|
||||
|
||||
// We ask that you to NOT use ASCII tab characters in your remarks.md writeup,
|
||||
@@ -491,35 +529,67 @@ not C code or any other non-markdown content:</p>
|
||||
<p><strong>NOTE</strong>: Again, you are <strong>perfectly welcome</strong> to use ASCII tab characters in
|
||||
your C code and other non-markdown files. We simply ask that you <strong>NOT</strong> use any
|
||||
ASCII tab characters in markdown files.</p>
|
||||
<h2 id="please-do-not-specify-a-language-for-a-code-block">Please do NOT specify a language for a code block</h2>
|
||||
<p>We request that (fenced) markdown code blocks <strong>NOT</strong> specify a language.</p>
|
||||
<div id="vim-tabs">
|
||||
<h3 id="tip-for-vim-users">Tip for <code>vim</code> users</h3>
|
||||
</div>
|
||||
<p>If you use <code>vim</code> you can put in your <code>.vimrc</code> file (usually <code>~/.vimrc</code>) the
|
||||
following settings to make sure the tabs are not put in without you noticing:</p>
|
||||
<pre><code> set tabstop=8 " a tab is 8 spaces (or whatever you wish it to be set to)
|
||||
set softtabstop=4 " ...but when inserting/backspacing use 4 spaces
|
||||
set shiftwidth=4 " ...and auto-indent 4 spaces (when autoindent is set)
|
||||
set expandtab " ...but don't expand tab to spaces.</code></pre>
|
||||
<p>If you have file type detection enabled you can, if you prefer, have these
|
||||
settings set just for markdown files:</p>
|
||||
<pre><code> autocmd! Filetype markdown setlocal set tabstop=8 softtabstop=4 shiftwidth=4 expandtab</code></pre>
|
||||
<p>or so.</p>
|
||||
<p>This will prevent the tab key from inserting tabs; rather it will insert 4
|
||||
spaces.</p>
|
||||
<p>To <strong>VERIFY</strong> that there are no tabs in a file you may do, in command mode:</p>
|
||||
<pre><code> /\t</code></pre>
|
||||
<p>If you’re in insert mode hit <code>ESC</code> first.</p>
|
||||
<div id="languages">
|
||||
<div id="code">
|
||||
<h2 id="please-do-not-directly-specify-a-language-for-a-code-block">Please do NOT <em>directly</em> specify a language for a code block</h2>
|
||||
</div>
|
||||
</div>
|
||||
<p>We request that <a href="https://www.markdownguide.org/extended-syntax/#fenced-code-blocks">fenced markdown code
|
||||
blocks</a>
|
||||
<strong>NOT</strong> specify a language directly.</p>
|
||||
<p>For example:</p>
|
||||
<pre><code>```c <=== no thank you
|
||||
<pre class="<!---markdown-->"><code>```c <=== no thank you
|
||||
int main(void) {return 0;}
|
||||
```</code></pre>
|
||||
<p>Instead, put the language inside an HTML comment, separated from the
|
||||
markdown code block starting fence by a space:</p>
|
||||
<pre><code>``` <!---c-->
|
||||
<pre class="<!---markdown-->"><code>``` <!---c-->
|
||||
int main(void) {return 0;}
|
||||
```</code></pre>
|
||||
<p><strong>IMPORTANT</strong>: The <strong>initial</strong> <strong>` ` `</strong> must be followed by an <strong><code>ASCII space</code></strong>,
|
||||
then by an <strong>opening</strong> <strong><code><!---</code></strong>, then by the <strong>language</strong>, then by a <strong>closing</strong> <strong><code>--></code></strong>.</p>
|
||||
<h2 id="please-do-not-add-trailing-slash-to-html-elements">Please do NOT add trailing slash to HTML elements</h2>
|
||||
<p><strong>IMPORTANT</strong>: The <strong>initial</strong> <strong>` ` `</strong> must be followed by an <strong>ASCII SPACE</strong>,
|
||||
and <strong>THEN</strong> an <strong>opening</strong> <strong><code><!---</code></strong> (a “<code><</code>”, a “<code>!</code>” and then three “<code>-</code>”s), and
|
||||
<strong>THEN</strong> the <strong>language</strong> and <strong>FINALLY</strong> a <strong>closing</strong> “<code>--></code>” (two “<code>-</code>”s
|
||||
followed by a “<code>></code>”).</p>
|
||||
<div id="slash">
|
||||
<div id="void">
|
||||
<h2 id="please-do-not-add-trailing-slash-to-void-html-elements">Please do NOT add trailing slash to void HTML elements</h2>
|
||||
</div>
|
||||
</div>
|
||||
<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>
|
||||
<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
|
||||
tags</a>.</p>
|
||||
<p>The trailing slash on void HTML elements has no effect and interacts badly with
|
||||
unquoted attribute values.</p>
|
||||
<p>For example, please do NOT use:</p>
|
||||
<p>For example, please do <strong>NOT</strong> use:</p>
|
||||
<pre><code> <br/> <=== no thank you</code></pre>
|
||||
<p>Instead use just:</p>
|
||||
<pre><code> <br></code></pre>
|
||||
<p>And for example, please do NOT use:</p>
|
||||
<p>And for example, please do <strong>NOT</strong> use:</p>
|
||||
<pre><code> <hr/> <=== no thank you</code></pre>
|
||||
<p>Instead use just:</p>
|
||||
<pre><code> <br></code></pre>
|
||||
<p>and</p>
|
||||
<pre><code> <hr></code></pre>
|
||||
<p>And for example, please do NOT use:</p>
|
||||
<p>And for example, please do <strong>NOT</strong> use:</p>
|
||||
<pre><code> <img src="1984-anonymous-tattoo.jpg"
|
||||
alt="image of a tattoo of the 1984 anonymous C code"
|
||||
width=600 height=401 /> <=== no thank you</code></pre>
|
||||
@@ -528,7 +598,11 @@ unquoted attribute values.</p>
|
||||
alt="image of a tattoo of the 1984 anonymous C code"
|
||||
width=600 height=401></code></pre>
|
||||
<p>etc.</p>
|
||||
<h2 id="please-do-not-use-trailing-backslash-outside-of-a-code-block">Please do NOT use trailing backslash outside of a code block</h2>
|
||||
<div id="backslash">
|
||||
<div id="br">
|
||||
<h2 id="please-do-not-use-a-trailing-backslash-outside-of-a-code-block">Please do NOT use a TRAILING backslash (<code>\</code>) outside of a code block</h2>
|
||||
</div>
|
||||
</div>
|
||||
<p>Unless the line is inside a markdown code block, please do <strong>NOT</strong>
|
||||
end a markdown line with a trailing backslash (<code>\</code>). Instead use
|
||||
a trailing <code><br></code>.</p>
|
||||
@@ -542,8 +616,9 @@ a trailing <code><br></code>.</p>
|
||||
use trailing<br>
|
||||
br's outside of<br>
|
||||
a code block</code></pre>
|
||||
<p>Again, use of a trailing backslash (<code>\</code>) inside a markdown code block is fine:</p>
|
||||
<pre><code>```
|
||||
<p>Again, use of a trailing backslash (<code>\</code>) inside a markdown <a href="https://www.markdownguide.org/extended-syntax/#fenced-code-blocks"><strong>fenced code
|
||||
block</strong></a> is fine:</p>
|
||||
<pre class="<!---markdown-->"><code>```
|
||||
This is OK\
|
||||
inside a\
|
||||
markdown code\
|
||||
@@ -551,11 +626,15 @@ a trailing <code><br></code>.</p>
|
||||
```</code></pre>
|
||||
<p>This will prevent <code>pandoc(1)</code> from generating deprecated HTML elements such as
|
||||
<code><br /></code>.</p>
|
||||
<div id="images">
|
||||
<div id="img">
|
||||
<h2 id="please-do-not-use-markdown-style-images">Please do NOT use markdown style images</h2>
|
||||
</div>
|
||||
</div>
|
||||
<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>
|
||||
<pre><code>  <=== no thank you</code></pre>
|
||||
<p>Use an <code><img ..></code> HTML element with <code>alt=</code>, <code>width=</code> and <code>length=</code>
|
||||
<p>Use an <code><img></code> HTML element with <code>alt=</code>, <code>width=</code> and <code>length=</code>
|
||||
attributes:</p>
|
||||
<pre><code> <img src="filename.png"
|
||||
alt="describe the filename.png image for someone who cannot view it"
|
||||
@@ -567,40 +646,66 @@ attributes:</p>
|
||||
alt="image of a tattoo of the 1984 anonymous C code"
|
||||
width=600 height=401></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
|
||||
HTML from the markdown image construct, the resulting HTML does <strong>NOT</strong>
|
||||
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
|
||||
the image size.</p>
|
||||
<div id="hr">
|
||||
<div id="horizontal">
|
||||
<div id="lines">
|
||||
<h2 id="please-do-not-use-markdown-style-horizontal-lines">Please do NOT use markdown style horizontal lines</h2>
|
||||
<p>Please do <strong>NOT</strong> use <code>**---**</code>-style lines in markdown to create horizontal
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
<p>Please do <strong>NOT</strong> use <code>---</code> style lines in markdown to create horizontal
|
||||
lines or to separate sections.</p>
|
||||
<p>Unless something is inside a markdown code block, do NOT start a
|
||||
line with 3 or more dashes (<code>-</code>s).</p>
|
||||
<p>Such causes <code>pandoc(1)</code> to generate <code><hr /></code>. The <code><hr /></code> has no effect in
|
||||
standard HTML 5 and interacts badly with unquoted attribute values.</p>
|
||||
<p>Unless something is inside a markdown <strong>code block</strong>, do <strong>NOT</strong> start a
|
||||
line with 3 or more dashes (“<code>-</code>”s).</p>
|
||||
<p>Such markdown causes <code>pandoc(1)</code> to generate <code><hr /></code>. The <code><hr /></code> 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> <hr></code></pre>
|
||||
<p>If a short line is needed, use:</p>
|
||||
<pre><code> <hr style="width:10%;text-align:left;margin-left:0"></code></pre>
|
||||
<h2 id="please-do-not-end-markdown-links-in">Please do NOT end markdown links in “))”</h2>
|
||||
<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
|
||||
<div id="closing-parentheses">
|
||||
<h2 id="please-do-not-end-markdown-links-with">Please do NOT end markdown links with “<code>))</code>”</h2>
|
||||
</div>
|
||||
<p>Please do <strong>NOT</strong> end a markdown links with a double closed parenthesis “<code>))</code>”.</p>
|
||||
<p>Markdown links that end in “<code>))</code>” complicate parsing and sometimes lead
|
||||
to incorrect URLs or file paths.</p>
|
||||
<p>Instead of:</p>
|
||||
<pre><code> [some text](https://example.com/foo_(bar)) <=== no thank you</code></pre>
|
||||
<p>Use:</p>
|
||||
<p>use:</p>
|
||||
<pre><code> [some text](https://example.com/foo_&#x28;bar&#x29;)</code></pre>
|
||||
<p>Instead of:</p>
|
||||
<p>As another example, instead of:</p>
|
||||
<pre><code> This thing, ([some text](some/path)), is NOT ideal. <=== no thank you</code></pre>
|
||||
<p>Use:</p>
|
||||
<p>use:</p>
|
||||
<pre><code> This thing, [some text](some/path), is better.</code></pre>
|
||||
<h2 id="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</h2>
|
||||
<div id="parentheses">
|
||||
<h2 id="please-do-not-put-a-literal-or-in-markdown-link-titles">Please do NOT put a LITERAL “<code>(</code>” or “<code>)</code>” in markdown link titles</h2>
|
||||
</div>
|
||||
<p>Please do <strong>NOT</strong> use literal parentheses inside markdown link titles.</p>
|
||||
<p>Instead of:</p>
|
||||
<pre><code> [some (text)](https://example.com/cyrds) <=== no thank you</code></pre>
|
||||
<p>use:</p>
|
||||
<pre><code> [some &#x28;text&#x29;](https://example.com/cyrds)</code></pre>
|
||||
<p>Instead of:</p>
|
||||
<pre><code> [ls(1)](https://example.com/ls-man-page.1) <=== no thank you</code></pre>
|
||||
<p>use:</p>
|
||||
<pre><code> [ls&#x28;1&#x29;](https://example.com/ls-man-page.1)</code></pre>
|
||||
<div id="code-text">
|
||||
<div id="code-and-text">
|
||||
<div id="text">
|
||||
<h2 id="please-do-not-place-text-on-the-immediate-very-next-line-after-a-markdown-code-block">Please do NOT place text on the IMMEDIATE (very next) line after a markdown code block</h2>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
<p>Please do <strong>NOT</strong> place text on the next line after a markdown code block.
|
||||
Instead, place a blank line after the end of a markdown code block
|
||||
as this makes it easier to detect when markdown code blocks are
|
||||
NOT properly indented.</p>
|
||||
<strong>NOT</strong> properly indented.</p>
|
||||
<p>Instead of:</p>
|
||||
<pre><code>```
|
||||
<pre class="<!---markdown-->"><code>```
|
||||
int
|
||||
main(int foo)
|
||||
{
|
||||
@@ -608,8 +713,8 @@ NOT properly indented.</p>
|
||||
}
|
||||
```
|
||||
C compilers cannot be given a -Wno-main-arg-errors flag. <=== no thank you</code></pre>
|
||||
<p>Use:</p>
|
||||
<pre><code>```
|
||||
<p>use:</p>
|
||||
<pre class="<!---markdown-->"><code>```
|
||||
int
|
||||
main(int foo)
|
||||
{
|
||||
@@ -619,16 +724,24 @@ C compilers cannot be given a -Wno-main-arg-errors flag. <=== no thank y
|
||||
|
||||
C compilers cannot be given a -Wno-main-arg-errors flag.</code></pre>
|
||||
<p><strong>BTW</strong>: Please note the blank line after the code block.</p>
|
||||
<h2 id="please-do-not-put-s-or-s-in-markdown-link-titles">Please do NOT put “(”s or “)”s in markdown link titles</h2>
|
||||
<p>Please do <strong>NOT</strong> use literal parentheses inside the markdown link titles.</p>
|
||||
<p>Instead of:</p>
|
||||
<pre><code> [some (text)](https://example.com/cyrds) <=== no thank you</code></pre>
|
||||
<p>Use:</p>
|
||||
<pre><code> [some &#x28;text&#x29;](https://example.com/cyrds)</code></pre>
|
||||
<p>Instead of:</p>
|
||||
<pre><code> [ls(1)](https://example.com/ls-man-page.1) <=== no thank you</code></pre>
|
||||
<p>Use:</p>
|
||||
<pre><code> [ls&#x28;1&#x29;](https://example.com/ls-man-page.1)</code></pre>
|
||||
<div id="italics">
|
||||
<h2 id="please-use-_-for-italics-in-markdown">Please use <code>_</code> for italics in markdown</h2>
|
||||
</div>
|
||||
<p>Please do <strong>NOT</strong> use <code>*</code> (single asterisk) for italics in markdown. Instead use
|
||||
an underscore (<code>_</code>). Using an asterisk can complicate parsing and sometimes lead
|
||||
to incorrect results. This can especially go for when it is <strong><em>bold and
|
||||
italic</em></strong>.</p>
|
||||
<p>For example, instead of:</p>
|
||||
<pre><code> *this text is italic* <=== no thank you</code></pre>
|
||||
<p>use:</p>
|
||||
<pre><code> _this text is italic_</code></pre>
|
||||
<p>Another example, for <strong><em>bold italic</em></strong>:</p>
|
||||
<p>Do <strong>NOT</strong> use:</p>
|
||||
<pre><code> ***this text is bold italic*** <=== no thank you</code></pre>
|
||||
<p>Instead use:</p>
|
||||
<pre><code> **_this text is bold italic_**</code></pre>
|
||||
<p>or:</p>
|
||||
<pre><code> _**this text is bold italic**_</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 -->
|
||||
|
||||
+269
-95
@@ -1,4 +1,6 @@
|
||||
<div id="guidelines">
|
||||
# IOCCC markdown guidelines
|
||||
</div>
|
||||
|
||||
The IOCCC makes extensive use of [markdown](https://daringfireball.net/projects/markdown/).
|
||||
For example, when submitting to the IOCCC
|
||||
@@ -22,11 +24,15 @@ In particular there are things we ask people to please **NOT** use in
|
||||
markdown files for the IOCCC:
|
||||
|
||||
|
||||
## Please do NOT use name attributes in HTML `<a ..>` hyperlink elements
|
||||
<div id="name">
|
||||
<div id="anchor-name">
|
||||
## Please do NOT use the `name` attributes in HTML `<a>...</a>` hyperlink elements
|
||||
</div>
|
||||
</div>
|
||||
|
||||
Please do **NOT** use the HTML construct:
|
||||
|
||||
```
|
||||
``` <!---html-->
|
||||
<a name="string">...</a> <=== no thank you
|
||||
```
|
||||
|
||||
@@ -34,7 +40,7 @@ as those are **NOT** part of the HTML 5 standard.
|
||||
|
||||
Instead use:
|
||||
|
||||
```
|
||||
``` <!---html-->
|
||||
<div id="string">...</div>
|
||||
```
|
||||
|
||||
@@ -43,69 +49,108 @@ 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>`.
|
||||
### IMPORTANT POINT:
|
||||
|
||||
For example:
|
||||
There are certain markdown constructs that **CANNOT** have an **internal** `<div
|
||||
id="string">...</div>` element.
|
||||
|
||||
```
|
||||
An example is headings (lines that start with a `#`). For example:
|
||||
|
||||
|
||||
``` <!---markdown-->
|
||||
# <div id="string">THIS WILL NOT WORK!</div> <=== this will not work
|
||||
```
|
||||
|
||||
For things like headings, you have to surround them, as in:
|
||||
For things like headings, you have to surround them with the `<div
|
||||
id="string">...</div>` element, as in:
|
||||
|
||||
```
|
||||
``` <!---markdown-->
|
||||
<div id="string">
|
||||
# This will work
|
||||
</div>
|
||||
```
|
||||
|
||||
While some browsers will still recognize the HTML construct `<a
|
||||
name="string">...</a>`, it is possible they might NOT in the future.
|
||||
name="string">...</a>`, it is possible **they MIGHT NOT** in the future.
|
||||
|
||||
|
||||
## Please do NOT use the `<strike>` or the `<s>` HTML element
|
||||
<div id="links">
|
||||
## If you can, it is PREFERABLE to use markdown links rather than `<a>...</a>`
|
||||
</div>
|
||||
|
||||
Please do NOT use the obsolete `<strike>` or the obsolete `<s>` (<del>_strikeout_</del>) HTML elements:
|
||||
It is easier and preferred to use markdown links rather than HTML `<a>..</a>`
|
||||
anchors.
|
||||
|
||||
Instead of:
|
||||
|
||||
|
||||
``` <!---html-->
|
||||
Use of <a href="#links>HTML anchors</a>
|
||||
is one option, however ...
|
||||
```
|
||||
|
||||
|
||||
``` <!---markdown-->
|
||||
[markdown links](#links) are easier and preferred
|
||||
```
|
||||
|
||||
|
||||
<div id="strike">
|
||||
<div id="del">
|
||||
## Please do NOT use the `<strike>` or the `<s>` HTML element
|
||||
</div>
|
||||
</div>
|
||||
|
||||
Please do **NOT** use the obsolete `<strike>` or the obsolete `<s>`
|
||||
(<del>**strikeout**</del>) HTML elements:
|
||||
|
||||
``` <!---html-->
|
||||
<strike>...</strike> <=== no thank you
|
||||
<s>...</s> <=== no thank you
|
||||
```
|
||||
|
||||
Use instead:
|
||||
|
||||
```
|
||||
``` <!---html-->
|
||||
<del>...</del>
|
||||
```
|
||||
|
||||
|
||||
<div id="underline">
|
||||
<div id="ins">
|
||||
## Please do NOT use the `<u>` HTML element
|
||||
</div>
|
||||
</div>
|
||||
|
||||
Please NOT use the obsolete `<u>` (<ins>_underline_</ins>) HTML element:
|
||||
Please **NOT** use the obsolete `<u>` (<ins>_underline_</ins>) HTML element:
|
||||
|
||||
```
|
||||
``` <!---html-->
|
||||
<u>...</u> <=== no thank you
|
||||
```
|
||||
|
||||
Use instead:
|
||||
|
||||
```
|
||||
``` <!---html-->
|
||||
<ins>...</ins>
|
||||
```
|
||||
|
||||
|
||||
<div id="tt">
|
||||
<div id="span">
|
||||
## Please do NOT use the `<tt>` HTML element
|
||||
</div>
|
||||
</div>
|
||||
|
||||
Please do **NOT** use the obsolete `<tt>` (<span style="font-family: monospace;">_teletype_</span>) HTML element:
|
||||
Please do **NOT** use the obsolete `<tt>`
|
||||
(<span style="font-family: monospace;">**teletype**</span>) HTML element:
|
||||
|
||||
```
|
||||
<tt>The obsolete tt element is obsolete</tt> <=== no thank you
|
||||
``` <!---html-->
|
||||
<tt>The tt element is obsolete</tt> <=== no thank you
|
||||
```
|
||||
|
||||
Instead use either a monospaced span:
|
||||
Instead use either a monospaced `<span>` or an inline markdown code block:
|
||||
|
||||
```
|
||||
``` <!---html-->
|
||||
<span style="font-family: monospace;">Use of a monospaced font
|
||||
is one option,
|
||||
however ... </span>
|
||||
@@ -113,28 +158,32 @@ Instead use either a monospaced span:
|
||||
|
||||
We recommend using the inline markdown code block method instead:
|
||||
|
||||
```
|
||||
Using the `inline markdown code block` is easier and is `preferred`.
|
||||
``` <!---markdown-->
|
||||
Using the `inline markdown code block` is easier and is **preferred**.
|
||||
```
|
||||
|
||||
|
||||
<div id="unindented">
|
||||
<div id="indented">
|
||||
## Please do NOT use unindented code blocks
|
||||
</div>
|
||||
</div>
|
||||
|
||||
Please do **NOT** start code blocks at the left-hand edge.
|
||||
Please do **NOT** start code blocks at the first column.
|
||||
|
||||
For example:
|
||||
|
||||
````
|
||||
```` <!---markdown-->
|
||||
``` <%%NO_COMMENT%%!---sh-->
|
||||
echo "This code block is NOT indented\" <=== no thank you
|
||||
echo "This code block is NOT indented" <=== no thank you
|
||||
```
|
||||
````
|
||||
|
||||
We request that you indent the code block by multiples of 4 ASCII spaces:
|
||||
We request that you indent the code block by multiples of 4 ASCII **SPACES**:
|
||||
|
||||
````
|
||||
```` <!---markdown-->
|
||||
``` <%%NO_COMMENT%%!---sh-->
|
||||
echo "This code block is intended by mutiples of 4 spaces"
|
||||
echo "This code block is indented by mutiples of 4 spaces"
|
||||
|
||||
# The top level starts with a 4 ASCII space indent.
|
||||
#
|
||||
@@ -147,7 +196,7 @@ We request that you indent the code block by multiples of 4 ASCII spaces:
|
||||
|
||||
Moreover:
|
||||
|
||||
````
|
||||
```` <!---markdown-->
|
||||
```
|
||||
The same thing applies to any markdown block surrounded by ``` lines.
|
||||
```
|
||||
@@ -156,19 +205,23 @@ Moreover:
|
||||
Please do **NOT** indent using ASCII tab characters in markdown files.
|
||||
|
||||
|
||||
<div id="tabs">
|
||||
<div id="spaces">
|
||||
## Please do NOT use ASCII tabs in markdown files
|
||||
</div>
|
||||
</div>
|
||||
|
||||
While we have nothing against the ASCII tab character in general,
|
||||
we have discovered that ASCII tab characters create problems when
|
||||
used as part of the leading whitespace within a markdown file.
|
||||
|
||||
If you need to indent 2 or more levels, use multiples of 4 ASCII
|
||||
spaces. Please do **NOT** indent with ASCII tabs, **NOR** use any
|
||||
**SPACES**. Please do **NOT** indent with ASCII tabs, **OR** use any
|
||||
ASCII tab characters anywhere inside a markdown file:
|
||||
|
||||
For example:
|
||||
|
||||
````
|
||||
```` <!---markdown-->
|
||||
```
|
||||
Please do **NOT** use ASCII tabs in markdown files. <=== no thank you
|
||||
Please do **NOT** indent markdown with ASCII tabs. <=== no thank you
|
||||
@@ -181,8 +234,8 @@ For example:
|
||||
And to clarify, we are only talking about markdown files,
|
||||
not C code or any other non-markdown content:
|
||||
|
||||
````
|
||||
printf("Is is fine to use tabs in Obfucated C code.\n");
|
||||
```` <!---c-->
|
||||
printf("It is fine to use tabs in Obfuscated C code.\n");
|
||||
/* if you wish */
|
||||
|
||||
// We ask that you to NOT use ASCII tab characters in your remarks.md writeup,
|
||||
@@ -193,14 +246,54 @@ not C code or any other non-markdown content:
|
||||
your C code and other non-markdown files. We simply ask that you **NOT** use any
|
||||
ASCII tab characters in markdown files.
|
||||
|
||||
<div id="vim-tabs">
|
||||
### Tip for `vim` users
|
||||
</div>
|
||||
|
||||
## Please do NOT specify a language for a code block
|
||||
If you use `vim` you can put in your `.vimrc` file (usually `~/.vimrc`) the
|
||||
following settings to make sure the tabs are not put in without you noticing:
|
||||
|
||||
We request that (fenced) markdown code blocks **NOT** specify a language.
|
||||
``` <!---vim-->
|
||||
set tabstop=8 " a tab is 8 spaces (or whatever you wish it to be set to)
|
||||
set softtabstop=4 " ...but when inserting/backspacing use 4 spaces
|
||||
set shiftwidth=4 " ...and auto-indent 4 spaces (when autoindent is set)
|
||||
set expandtab " ...but don't expand tab to spaces.
|
||||
```
|
||||
|
||||
If you have file type detection enabled you can, if you prefer, have these
|
||||
settings set just for markdown files:
|
||||
|
||||
``` <!---vim-->
|
||||
autocmd! Filetype markdown setlocal set tabstop=8 softtabstop=4 shiftwidth=4 expandtab
|
||||
```
|
||||
|
||||
or so.
|
||||
|
||||
This will prevent the tab key from inserting tabs; rather it will insert 4
|
||||
spaces.
|
||||
|
||||
To **VERIFY** that there are no tabs in a file you may do, in command mode:
|
||||
|
||||
```
|
||||
/\t
|
||||
```
|
||||
|
||||
If you're in insert mode hit `ESC` first.
|
||||
|
||||
|
||||
<div id="languages">
|
||||
<div id="code">
|
||||
## Please do NOT _directly_ specify a language for a code block
|
||||
</div>
|
||||
</div>
|
||||
|
||||
We request that [fenced markdown code
|
||||
blocks](https://www.markdownguide.org/extended-syntax/#fenced-code-blocks)
|
||||
**NOT** specify a language directly.
|
||||
|
||||
For example:
|
||||
|
||||
````
|
||||
```` <!---markdown-->
|
||||
```c <=== no thank you
|
||||
int main(void) {return 0;}
|
||||
```
|
||||
@@ -209,18 +302,24 @@ For example:
|
||||
Instead, put the language inside an HTML comment, separated from the
|
||||
markdown code block starting fence by a space:
|
||||
|
||||
````
|
||||
```` <!---markdown-->
|
||||
``` <%%NO_COMMENT%%!---c-->
|
||||
int main(void) {return 0;}
|
||||
```
|
||||
````
|
||||
|
||||
**IMPORTANT**: The **initial** **\` \` \`** must be followed by an **`ASCII space`**,
|
||||
then by an **opening** **`<!---`**, then by the **language**, then by a **closing** **`-->`**.
|
||||
**IMPORTANT**: The **initial** **\` \` \`** must be followed by an **ASCII SPACE**,
|
||||
and **THEN** an **opening** **`<!---`** (a "`<`", a "`!`" and then three "`-`"s), and
|
||||
**THEN** the **language** and **FINALLY** a **closing** "`-->`" (two "`-`"s
|
||||
followed by a "`>`").
|
||||
|
||||
|
||||
|
||||
## Please do NOT add trailing slash to HTML elements
|
||||
<div id="slash">
|
||||
<div id="void">
|
||||
## Please do NOT add trailing slash to void HTML elements
|
||||
</div>
|
||||
</div>
|
||||
|
||||
Please do **NOT** use a trailing slash on [void HTML
|
||||
elements](https://github.com/validator/validator/wiki/Markup-»-Void-elements).
|
||||
@@ -231,33 +330,39 @@ tags](https://github.com/validator/validator/wiki/Markup-»-Void-elements#traili
|
||||
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:
|
||||
|
||||
```
|
||||
``` <!---html-->
|
||||
<br/> <=== no thank you
|
||||
```
|
||||
|
||||
Instead use just:
|
||||
|
||||
```
|
||||
``` <!---html-->
|
||||
<br>
|
||||
```
|
||||
|
||||
And for example, please do NOT use:
|
||||
And for example, please do **NOT** use:
|
||||
|
||||
```
|
||||
``` <!---html-->
|
||||
<hr/> <=== no thank you
|
||||
```
|
||||
|
||||
Instead use just:
|
||||
|
||||
``` <!---html-->
|
||||
<br>
|
||||
```
|
||||
|
||||
and
|
||||
|
||||
``` <!---html-->
|
||||
<hr>
|
||||
```
|
||||
|
||||
And for example, please do NOT use:
|
||||
And for example, please do **NOT** use:
|
||||
|
||||
```
|
||||
``` <!---html-->
|
||||
<img src="1984-anonymous-tattoo.jpg"
|
||||
alt="image of a tattoo of the 1984 anonymous C code"
|
||||
width=600 height=401 /> <=== no thank you
|
||||
@@ -265,7 +370,7 @@ And for example, please do NOT use:
|
||||
|
||||
Instead use just:
|
||||
|
||||
```
|
||||
``` <!---html-->
|
||||
<img src="1984-anonymous-tattoo.jpg"
|
||||
alt="image of a tattoo of the 1984 anonymous C code"
|
||||
width=600 height=401>
|
||||
@@ -274,7 +379,11 @@ Instead use just:
|
||||
etc.
|
||||
|
||||
|
||||
## Please do NOT use trailing backslash outside of a code block
|
||||
<div id="backslash">
|
||||
<div id="br">
|
||||
## Please do NOT use a TRAILING backslash (`\`) outside of a code block
|
||||
</div>
|
||||
</div>
|
||||
|
||||
Unless the line is inside a markdown code block, please do **NOT**
|
||||
end a markdown line with a trailing backslash (`\`). Instead use
|
||||
@@ -282,7 +391,7 @@ a trailing `<br>`.
|
||||
|
||||
Instead of:
|
||||
|
||||
```
|
||||
``` <!---markdown-->
|
||||
In markdown,\ <=== no thank you
|
||||
do NOT use trailing\
|
||||
backslashes outside of\
|
||||
@@ -291,16 +400,17 @@ Instead of:
|
||||
|
||||
use:
|
||||
|
||||
```
|
||||
``` <!---markdown-->
|
||||
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:
|
||||
Again, use of a trailing backslash (`\`) inside a markdown [**fenced code
|
||||
block**](https://www.markdownguide.org/extended-syntax/#fenced-code-blocks) is fine:
|
||||
|
||||
````
|
||||
```` <!---markdown-->
|
||||
```
|
||||
This is OK\
|
||||
inside a\
|
||||
@@ -313,20 +423,24 @@ This will prevent `pandoc(1)` from generating deprecated HTML elements such as
|
||||
`<br />`.
|
||||
|
||||
|
||||
<div id="images">
|
||||
<div id="img">
|
||||
## Please do NOT use markdown style images
|
||||
</div>
|
||||
</div>
|
||||
|
||||
Please do **NOT** use the markdown embedded image element.
|
||||
|
||||
Instead of using this markdown element to embed an image:
|
||||
|
||||
```
|
||||
``` <!---markdown-->
|
||||
 <=== no thank you
|
||||
```
|
||||
|
||||
Use an `<img ..>` HTML element with `alt=`, `width=` and `length=`
|
||||
Use an `<img>` HTML element with `alt=`, `width=` and `length=`
|
||||
attributes:
|
||||
|
||||
```
|
||||
``` <!---html-->
|
||||
<img src="filename.png"
|
||||
alt="describe the filename.png image for someone who cannot view it"
|
||||
width=PIXEL_WIDTH height=PIXEL_HEIGHT>
|
||||
@@ -334,91 +448,136 @@ attributes:
|
||||
|
||||
For example, instead of:
|
||||
|
||||
```
|
||||
``` <!---markdown-->
|
||||
 <=== no thank you
|
||||
```
|
||||
|
||||
use this HTML:
|
||||
|
||||
```
|
||||
``` <!---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
|
||||
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.
|
||||
|
||||
|
||||
<div id="hr">
|
||||
<div id="horizontal">
|
||||
<div id="lines">
|
||||
## Please do NOT use markdown style horizontal lines
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
Please do **NOT** use `**---**`-style lines in markdown to create horizontal
|
||||
Please do **NOT** use `---` style lines in markdown to create horizontal
|
||||
lines or to separate sections.
|
||||
|
||||
Unless something is inside a markdown code block, do NOT start a
|
||||
line with 3 or more dashes (`-`s).
|
||||
Unless something is inside a markdown **code block**, do **NOT** start a
|
||||
line with 3 or more dashes ("`-`"s).
|
||||
|
||||
Such causes `pandoc(1)` to generate `<hr />`. The `<hr />` has no effect in
|
||||
standard HTML 5 and interacts badly with unquoted attribute values.
|
||||
Such markdown 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:
|
||||
|
||||
```
|
||||
``` <!---html-->
|
||||
<hr>
|
||||
```
|
||||
|
||||
If a short line is needed, use:
|
||||
|
||||
```
|
||||
``` <!---html-->
|
||||
<hr style="width:10%;text-align:left;margin-left:0">
|
||||
```
|
||||
|
||||
|
||||
## Please do NOT end markdown links in "))"
|
||||
|
||||
Please do **NOT** end a markdown links with a double closed parenthesis "))".
|
||||
<div id="closing-parentheses">
|
||||
## Please do NOT end markdown links with "`))`"
|
||||
</div>
|
||||
|
||||
Markdown links that end in "))" complicate parsing and sometimes lead
|
||||
Please do **NOT** end a markdown links with a double closed parenthesis "`))`".
|
||||
|
||||
Markdown links that end in "`))`" complicate parsing and sometimes lead
|
||||
to incorrect URLs or file paths.
|
||||
|
||||
Instead of:
|
||||
|
||||
```
|
||||
``` <!---markdown-->
|
||||
[some text](https://example.com/foo_(bar)) <=== no thank you
|
||||
```
|
||||
|
||||
Use:
|
||||
use:
|
||||
|
||||
```
|
||||
``` <!---markdown-->
|
||||
[some text](https://example.com/foo_(bar))
|
||||
```
|
||||
|
||||
Instead of:
|
||||
As another example, instead of:
|
||||
|
||||
```
|
||||
``` <!---markdown-->
|
||||
This thing, ([some text](some/path)), is NOT ideal. <=== no thank you
|
||||
```
|
||||
|
||||
Use:
|
||||
use:
|
||||
|
||||
```
|
||||
``` <!---markdown-->
|
||||
This thing, [some text](some/path), is better.
|
||||
```
|
||||
|
||||
|
||||
## Please do NOT place text on the next line after a markdown code block
|
||||
<div id="parentheses">
|
||||
## Please do NOT put a LITERAL "`(`" or "`)`" in markdown link titles
|
||||
</div>
|
||||
|
||||
Please do **NOT** use literal parentheses inside markdown link titles.
|
||||
|
||||
Instead of:
|
||||
|
||||
``` <!---markdown-->
|
||||
[some (text)](https://example.com/cyrds) <=== no thank you
|
||||
```
|
||||
|
||||
use:
|
||||
|
||||
``` <!---markdown-->
|
||||
[some (text)](https://example.com/cyrds)
|
||||
```
|
||||
|
||||
Instead of:
|
||||
|
||||
``` <!---markdown-->
|
||||
[ls(1)](https://example.com/ls-man-page.1) <=== no thank you
|
||||
```
|
||||
|
||||
use:
|
||||
|
||||
``` <!---markdown-->
|
||||
[ls(1)](https://example.com/ls-man-page.1)
|
||||
```
|
||||
|
||||
<div id="code-text">
|
||||
<div id="code-and-text">
|
||||
<div id="text">
|
||||
## Please do NOT place text on the IMMEDIATE (very next) line after a markdown code block
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
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
|
||||
as this makes it easier to detect when markdown code blocks are
|
||||
NOT properly indented.
|
||||
**NOT** properly indented.
|
||||
|
||||
Instead of:
|
||||
|
||||
````
|
||||
```` <!---markdown-->
|
||||
```
|
||||
int
|
||||
main(int foo)
|
||||
@@ -429,9 +588,9 @@ Instead of:
|
||||
C compilers cannot be given a -Wno-main-arg-errors flag. <=== no thank you
|
||||
````
|
||||
|
||||
Use:
|
||||
use:
|
||||
|
||||
````
|
||||
```` <!---markdown-->
|
||||
```
|
||||
int
|
||||
main(int foo)
|
||||
@@ -446,30 +605,45 @@ C compilers cannot be given a -Wno-main-arg-errors flag.
|
||||
**BTW**: Please note the blank line after the code block.
|
||||
|
||||
|
||||
## Please do NOT put "("s or ")"s in markdown link titles
|
||||
<div id="italics">
|
||||
## Please use `_` for italics in markdown
|
||||
</div>
|
||||
|
||||
Please do **NOT** use literal parentheses inside the markdown link titles.
|
||||
Please do **NOT** use `*` (single asterisk) for italics in markdown. Instead use
|
||||
an underscore (`_`). Using an asterisk can complicate parsing and sometimes lead
|
||||
to incorrect results. This can especially go for when it is **_bold and
|
||||
italic_**.
|
||||
|
||||
Instead of:
|
||||
For example, instead of:
|
||||
|
||||
```
|
||||
[some (text)](https://example.com/cyrds) <=== no thank you
|
||||
``` <!---markdown-->
|
||||
*this text is italic* <=== no thank you
|
||||
```
|
||||
|
||||
Use:
|
||||
use:
|
||||
|
||||
```
|
||||
[some (text)](https://example.com/cyrds)
|
||||
``` <!---markdown-->
|
||||
_this text is italic_
|
||||
```
|
||||
|
||||
Instead of:
|
||||
Another example, for **_bold italic_**:
|
||||
|
||||
```
|
||||
[ls(1)](https://example.com/ls-man-page.1) <=== no thank you
|
||||
Do **NOT** use:
|
||||
|
||||
|
||||
``` <!---markdown-->
|
||||
***this text is bold italic*** <=== no thank you
|
||||
```
|
||||
|
||||
Use:
|
||||
Instead use:
|
||||
|
||||
``` <!---markdown-->
|
||||
**_this text is bold italic_**
|
||||
```
|
||||
[ls(1)](https://example.com/ls-man-page.1)
|
||||
|
||||
or:
|
||||
|
||||
``` <!---markdown-->
|
||||
_**this text is bold italic**_
|
||||
```
|
||||
|
||||
Reference in new issue
Block a user