860 lines
31 KiB
HTML
860 lines
31 KiB
HTML
<!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 guidelines">
|
|
<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">
|
|
<a href="./index.html" class="logo-link">
|
|
IOCCC
|
|
</a>
|
|
</div>
|
|
|
|
<div class="topbar-items">
|
|
<div class="item">
|
|
<span class="item-header">
|
|
Entries
|
|
</span>
|
|
|
|
<div class="sub-item">
|
|
|
|
<div class="outfit-font">
|
|
<a href="./years.html" class="sub-item-link">
|
|
Winning entries
|
|
</a>
|
|
</div>
|
|
|
|
<div class="outfit-font">
|
|
<a href="./authors.html" class="sub-item-link">
|
|
Winning authors
|
|
</a>
|
|
</div>
|
|
|
|
<div class="outfit-font">
|
|
<a href="./location.html" class="sub-item-link">
|
|
Location of authors
|
|
</a>
|
|
</div>
|
|
|
|
<div class="outfit-font">
|
|
<a href="./bugs.html" class="sub-item-link">
|
|
Bugs and (mis)features
|
|
</a>
|
|
</div>
|
|
|
|
<div class="outfit-font">
|
|
<a href="./faq.html#fix_an_entry" class="sub-item-link">
|
|
Fixing entries
|
|
</a>
|
|
</div>
|
|
|
|
<div class="outfit-font">
|
|
<a href="./faq.html#fix_author" class="sub-item-link">
|
|
Updating author info
|
|
</a>
|
|
</div>
|
|
|
|
</div>
|
|
</div>
|
|
|
|
<div class="item">
|
|
<span class="item-header">
|
|
Status
|
|
</span>
|
|
|
|
<div class="sub-item">
|
|
|
|
<div class="outfit-font">
|
|
<a href="./news.html" class="sub-item-link">
|
|
News
|
|
</a>
|
|
</div>
|
|
|
|
<div class="outfit-font">
|
|
<a href="./status.html" class="sub-item-link">
|
|
Contest status
|
|
</a>
|
|
</div>
|
|
|
|
<div class="outfit-font">
|
|
<a href="./next/rules.html" class="sub-item-link">
|
|
IOCCC rules
|
|
</a>
|
|
</div>
|
|
|
|
<div class="outfit-font">
|
|
<a href="./next/guidelines.html" class="sub-item-link">
|
|
IOCCC guidelines
|
|
</a>
|
|
</div>
|
|
|
|
<div class="outfit-font">
|
|
<a href="./markdown.html" class="sub-item-link">
|
|
Markdown guidelines
|
|
</a>
|
|
</div>
|
|
|
|
<div class="outfit-font">
|
|
<a href="./SECURITY.html" class="sub-item-link">
|
|
Security policy
|
|
</a>
|
|
</div>
|
|
|
|
</div>
|
|
</div>
|
|
|
|
<div class="item">
|
|
<span class="item-header">
|
|
FAQ
|
|
</span>
|
|
|
|
<div class="sub-item">
|
|
|
|
<div class="outfit-font">
|
|
<a href="./faq.html" class="sub-item-link">
|
|
Frequently asked questions
|
|
</a>
|
|
</div>
|
|
|
|
<div class="outfit-font">
|
|
<a href="./quick-start.html#enter" class="sub-item-link">
|
|
Enter the IOCCC
|
|
</a>
|
|
</div>
|
|
|
|
<div class="outfit-font">
|
|
<a href="./faq.html#compiling" class="sub-item-link">
|
|
Compiling entries
|
|
</a>
|
|
</div>
|
|
|
|
<div class="outfit-font">
|
|
<a href="./faq.html#running_entries" class="sub-item-link">
|
|
Running entries
|
|
</a>
|
|
</div>
|
|
|
|
<div class="outfit-font">
|
|
<a href="./faq.html#help" class="sub-item-link">
|
|
How to help
|
|
</a>
|
|
</div>
|
|
|
|
</div>
|
|
</div>
|
|
|
|
<div class="item">
|
|
<span class="item-header">
|
|
About
|
|
</span>
|
|
|
|
<div class="sub-item">
|
|
|
|
<div class="outfit-font">
|
|
<a href="./index.html" class="sub-item-link">
|
|
Home page
|
|
</a>
|
|
</div>
|
|
|
|
<div class="outfit-font">
|
|
<a href="./social.html" class="sub-item-link">
|
|
IOCCC social media
|
|
</a>
|
|
</div>
|
|
|
|
<div class="outfit-font">
|
|
<a href="./about.html" class="sub-item-link">
|
|
About the IOCCC
|
|
</a>
|
|
</div>
|
|
|
|
<div class="outfit-font">
|
|
<a href="./judges.html" class="sub-item-link">
|
|
The judges
|
|
</a>
|
|
</div>
|
|
|
|
<div class="outfit-font">
|
|
<a href="./thanks-for-help.html" class="sub-item-link">
|
|
Thanks for the help
|
|
</a>
|
|
</div>
|
|
|
|
<div class="outfit-font">
|
|
<a href="./contact.html" class="sub-item-link">
|
|
Contact us
|
|
</a>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</nav>
|
|
|
|
<div class="header-mobile-menu">
|
|
<noscript>
|
|
<a href="./nojs-menu.html" class="topbar-js-label">
|
|
Please Enable JavaScript
|
|
</a>
|
|
</noscript>
|
|
|
|
<button id="header-open-menu-button" class="topbar-mobile-menu">
|
|
<img
|
|
src="./png/hamburger-icon-open.png"
|
|
alt="hamburger style menu icon - open state"
|
|
width=48
|
|
height=48>
|
|
</button>
|
|
|
|
<button id="header-close-menu-button" class="hide-content">
|
|
<img
|
|
src="./png/hamburger-icon-closed.png"
|
|
alt="hamburger style menu icon - closed state"
|
|
width=48
|
|
height=48>
|
|
</button>
|
|
|
|
<div id="mobile-menu-panel" class="hide-content">
|
|
<div class="mobile-menu-container">
|
|
|
|
<div class="mobile-menu-wrapper">
|
|
<div class="mobile-menu-item">
|
|
Entries
|
|
</div>
|
|
<div class="mobile-submenu-wrapper">
|
|
|
|
<a class="mobile-submenu-item" href="./years.html">
|
|
Winning entries
|
|
</a>
|
|
|
|
<a class="mobile-submenu-item" href="./authors.html">
|
|
Winning authors
|
|
</a>
|
|
|
|
<a class="mobile-submenu-item" href="./location.html">
|
|
Location of authors
|
|
</a>
|
|
|
|
<a class="mobile-submenu-item" href="./bugs.html">
|
|
Bugs and (mis)features
|
|
</a>
|
|
|
|
<a class="mobile-submenu-item" href="./faq.html#fix_an_entry">
|
|
Fixing entries
|
|
</a>
|
|
|
|
<a class="mobile-submenu-item" href="./faq.html#fix_author">
|
|
Updating author info
|
|
</a>
|
|
|
|
<a class="mobile-submenu-item" href="./thanks-for-help.html">
|
|
Thanks for the help
|
|
</a>
|
|
|
|
</div>
|
|
</div>
|
|
|
|
<div class="mobile-menu-wrapper">
|
|
|
|
<div class="mobile-menu-item">
|
|
Status
|
|
</div>
|
|
<div class="mobile-submenu-wrapper">
|
|
|
|
<a class="mobile-submenu-item" href="./news.html">
|
|
News
|
|
</a>
|
|
|
|
<a class="mobile-submenu-item" href="./status.html">
|
|
Contest status
|
|
</a>
|
|
|
|
<a class="mobile-submenu-item" href="./next/rules.html">
|
|
IOCCC rules
|
|
</a>
|
|
|
|
<a class="mobile-submenu-item" href="./next/guidelines.html">
|
|
IOCCC guidelines
|
|
</a>
|
|
|
|
<a class="mobile-submenu-item" href="./markdown.html">
|
|
Markdown guidelines
|
|
</a>
|
|
|
|
<a class="mobile-submenu-item" href="./SECURITY.html">
|
|
Security policy
|
|
</a>
|
|
|
|
</div>
|
|
</div>
|
|
|
|
<div class="mobile-menu-wrapper">
|
|
<div class="mobile-menu-item">
|
|
FAQ
|
|
</div>
|
|
<div class="mobile-submenu-wrapper">
|
|
|
|
<a class="mobile-submenu-item" href="./faq.html">
|
|
Frequently asked questions
|
|
</a>
|
|
|
|
<a class="mobile-submenu-item" href="./quick-start.html#enter">
|
|
Enter the IOCCC
|
|
</a>
|
|
|
|
<a class="mobile-submenu-item" href="./faq.html#compiling">
|
|
Compiling entries
|
|
</a>
|
|
|
|
<a class="mobile-submenu-item" href="./faq.html#running_entries">
|
|
Running entries
|
|
</a>
|
|
|
|
<a class="mobile-submenu-item" href="./faq.html#help">
|
|
How to help
|
|
</a>
|
|
|
|
</div>
|
|
</div>
|
|
|
|
<div class="mobile-menu-wrapper">
|
|
<div class="mobile-menu-item">
|
|
About
|
|
</div>
|
|
<div class="mobile-submenu-wrapper">
|
|
|
|
<a class="mobile-submenu-item" href="./index.html">
|
|
Home page
|
|
</a>
|
|
|
|
<a class="mobile-submenu-item" href="./social.html">
|
|
IOCCC social media
|
|
</a>
|
|
|
|
<a class="mobile-submenu-item" href="./about.html">
|
|
About the IOCCC
|
|
</a>
|
|
|
|
<a class="mobile-submenu-item" href="./judges.html">
|
|
The judges
|
|
</a>
|
|
|
|
<a class="mobile-submenu-item" href="./contact.html">
|
|
Contact us
|
|
</a>
|
|
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
|
|
</div>
|
|
|
|
<script>
|
|
var headerOpenMenuButton = document.getElementById("header-open-menu-button");
|
|
var headerCloseMenuButton = document.getElementById("header-close-menu-button");
|
|
var mobileMenuPanel = document.getElementById("mobile-menu-panel");
|
|
|
|
headerOpenMenuButton.addEventListener("click", () => {
|
|
headerOpenMenuButton.classList.remove("topbar-mobile-menu");
|
|
headerOpenMenuButton.classList.add("hide-content");
|
|
|
|
headerCloseMenuButton.classList.remove("hide-content");
|
|
headerCloseMenuButton.classList.add("topbar-mobile-menu");
|
|
|
|
mobileMenuPanel.classList.remove("hide-content");
|
|
mobileMenuPanel.classList.add("topbar-mobile-panel");
|
|
});
|
|
|
|
headerCloseMenuButton.addEventListener("click", () => {
|
|
headerCloseMenuButton.classList.remove("topbar-mobile-menu");
|
|
headerCloseMenuButton.classList.add("hide-content");
|
|
|
|
mobileMenuPanel.classList.add("hide-content");
|
|
mobileMenuPanel.classList.remove("topbar-mobile-panel");
|
|
|
|
headerOpenMenuButton.classList.add("topbar-mobile-menu");
|
|
headerOpenMenuButton.classList.remove("hide-content");
|
|
});
|
|
</script>
|
|
|
|
<!-- END: this line ends content from: inc/topbar.default.html -->
|
|
<!-- START: this line starts content from: inc/header.default.html -->
|
|
|
|
<div class="header">
|
|
<a href="./2011/zucker/index.html">
|
|
<img src="./png/ioccc.png"
|
|
alt="IOCCC image by Matt Zucker"
|
|
width=300
|
|
height=110>
|
|
</a>
|
|
<h1>The International Obfuscated C Code Contest</h1>
|
|
<h2>IOCCC markdown guidelines</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%2Fwww.ioccc.org%2Fmarkdown.html">✓</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-29th-markdown-guidelines">IOCCC 29th Markdown Guidelines</h1>
|
|
<h2 id="markdown-guidelines-version">Markdown Guidelines Version</h2>
|
|
<p>These <a href="markdown.html">Markdown Guidelines</a> are version <strong>29.02 2025-11-28</strong>.</p>
|
|
<h2 id="introduction">Introduction</h2>
|
|
<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 submit remarks about their
|
|
entry in markdown format. Every <a href="years.html">winning 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 HTML 5 generated pages on the <a href="https://www.ioccc.org/index.html">Official IOCCC website</a>
|
|
start with some markdown content. We no longer support older HTML
|
|
standards and some of our guidelines help integrate winning entries into
|
|
the website more easily.</p>
|
|
<p>See the <a href="https://www.markdownguide.org/basic-syntax">markdown syntax</a> guide.
|
|
See also the <a href="https://spec.commonmark.org/current/">CommonMark Spec</a>.
|
|
See the FAQ on “<a href="faq.html#remarks_md">remarks.md submission file</a>”.</p>
|
|
<p>Nevertheless, the IOCCC does have certain practices that we ask authors to
|
|
follow. Some of these relate to use of markdown directly and others relate
|
|
to injecting HTML into the markdown file.</p>
|
|
<p>In the sections below, examples will mark by <span style="color:red">❌</span> for the incorrect method
|
|
and <span style="color:green">✔</span> for preferred correct one.</p>
|
|
<div id="sections">
|
|
|
|
</div>
|
|
<h2 id="start-remarks.md-sections-at-level-3">Start <code>remarks.md</code> sections at level 3</h2>
|
|
<p>If (it is not required) you do use sections in your <code>remarks.md</code> file (this does
|
|
not apply to other markdown files), <strong>PLEASE</strong> start at level three up to level six:</p>
|
|
<p><span style="color:red">❌</span> Reserved in <code>remarks.md</code> only.</p>
|
|
<pre><code> # Section Reserved
|
|
## Section Reserved</code></pre>
|
|
<p><span style="color:green">✔</span> Available every where.</p>
|
|
<pre><code> ### Section Level 3
|
|
#### Section Level 4
|
|
##### Section Level 5
|
|
###### Section Level 6</code></pre>
|
|
<div id="anchor-name">
|
|
|
|
</div>
|
|
<h2 id="replace-a-nameanchor_namea-construct">Replace <code><a name="anchor_name"></a></code> construct</h2>
|
|
<p><span style="color:red">❌</span> Incorrect.</p>
|
|
<pre><code> <a name="old_way">Section title</a></code></pre>
|
|
<p><span style="color:green">✔</span> Correct.</p>
|
|
<pre><code> <div id="new_way"></div>
|
|
|
|
### Section title</code></pre>
|
|
<div id="links">
|
|
|
|
</div>
|
|
<h2 id="markdown-links-instead-of-a...a">Markdown links instead of <code><a>...</a></code></h2>
|
|
<p><span style="color:red">❌</span> Incorrect.</p>
|
|
<pre><code> This <a href="#link_target>HTML link text</a> works, but we prefer see below...</code></pre>
|
|
<p><span style="color:green">✔</span> Correct.</p>
|
|
<pre><code> [markdown link text](#link_target)</code></pre>
|
|
<div id="del">
|
|
|
|
</div>
|
|
<div id="strike">
|
|
|
|
</div>
|
|
<h2 id="replace-strike-or-s">Replace <code><strike></code> or <code><s></code></h2>
|
|
<p><span style="color:red">❌</span> Incorrect.</p>
|
|
<pre><code> <strike>striked through text</strike>
|
|
<s>HTML 5 striked through text</s></code></pre>
|
|
<p><span style="color:green">✔</span> Correct.</p>
|
|
<pre><code> ~~markdown striked through text~~
|
|
<del>HTML 5 striked through text</del></code></pre>
|
|
<div id="ins">
|
|
|
|
</div>
|
|
<div id="underline">
|
|
|
|
</div>
|
|
<h2 id="replace-u">Replace <code><u></code></h2>
|
|
<p><span style="color:red">❌</span> Incorrect.</p>
|
|
<pre><code> <u>old tags</u></code></pre>
|
|
<p><span style="color:green">✔</span> Correct.</p>
|
|
<pre><code> <ins>HTML 5 tags</ins></code></pre>
|
|
<div id="tt">
|
|
|
|
</div>
|
|
<h2 id="replace-tt">Replace <code><tt></code></h2>
|
|
<p><span style="color:red">❌</span> Incorrect.</p>
|
|
<pre><code> <tt>obsolete HTML</tt></code></pre>
|
|
<p><span style="color:green">✔</span> Correct.</p>
|
|
<pre><code> <span style="font-family: monospace;">monospace font</span>
|
|
`markdown style monospace`</code></pre>
|
|
<div id="indent">
|
|
|
|
</div>
|
|
<h2 id="indent-code-blocks-by-four-spaces-not-by-tab">Indent code blocks by four spaces, not by TAB</h2>
|
|
<p><span style="color:red">❌</span> Incorrect.</p>
|
|
<pre class="<!---markdown-->"><code> ``` <!---sh-->
|
|
echo "This shell code block is NOT properly indented!"
|
|
echo 'Please indent your code blocks with multiples of four (4) ASCII SPACES!"
|
|
```</code></pre>
|
|
<p>We request that you indent the code block by multiples of four (4)
|
|
ASCII SPACES, never TAB (␉):</p>
|
|
<p><span style="color:green">✔</span> Correct.</p>
|
|
<pre class="<!---markdown-->"><code> ``` <!---sh-->
|
|
echo "This shell code block is indented by multiples of 4 spaces"
|
|
```</code></pre>
|
|
<p>If you need to intent more than one level, use multiples of 4 ASCII spaces (no tabs):</p>
|
|
<p><span style="color:green">✔</span> Also Correct.</p>
|
|
<pre class="<!---markdown-->"><code> ``` <!---sh-->
|
|
echo "This shell code block is indented by multiples of 4 spaces"
|
|
|
|
for i in $(seq 1 9); do
|
|
echo "This 2nd level is intented by 8 spaces (no tabs)"
|
|
if [[ $i -gt 5 ]]; then
|
|
echo "This 3rd level is intented by 12 spaces (no tabs)"
|
|
break
|
|
fi
|
|
done
|
|
```</code></pre>
|
|
<p>While it is possible to use 3 backticks (```) without the initial
|
|
four (4) space indentation, we <strong>prefer</strong> that you multiples of 4 spaces if possible:</p>
|
|
<p><span style="color:green">✔</span> Preferred.</p>
|
|
<pre class="<!---markdown-->"><code> ```
|
|
Intent text by multiples of 4 spaces if possible.
|
|
```</code></pre>
|
|
<p>A reasonable exception to the rule is when are displaying C:</p>
|
|
<p><span style="color:green">✔</span> OK for C.</p>
|
|
<pre class="<!---markdown-->"><code> ``` <!---c-->
|
|
/* not intending C code is OK */
|
|
int
|
|
bar(int foo)
|
|
{
|
|
return foo;
|
|
}
|
|
```</code></pre>
|
|
<div id="tabs">
|
|
|
|
</div>
|
|
<div id="spaces">
|
|
|
|
</div>
|
|
<h2 id="do-not-use-tab-in-markdown-files">Do not use TAB in markdown files</h2>
|
|
<p>Please do <strong>NOT</strong> indent with ASCII TABs (␉), <strong>OR</strong> use any ASCII TAB
|
|
(␉) anywhere inside a markdown file.</p>
|
|
<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 two (2) or more levels, use multiples of four (4)
|
|
ASCII SPACES.</p>
|
|
<p><span style="color:red">❌</span> Incorrect for markdown files only.</p>
|
|
<pre class="<!---markdown-->"><code> ```
|
|
␉Please do **NOT**␉use ASCII tabs␉in markdown files.
|
|
␉␉Please do **NOT** indent markdown with ASCII tabs.
|
|
|
|
␉We␉don't␉mind␉tabs␉in␉general,
|
|
␉We just ask that you NOT use them in markdown files.
|
|
```</code></pre>
|
|
<p><span style="color:green">✔</span> OK for all file types, e.g., <code>.c</code>, <code>.h</code>, <code>.mk</code>, <code>.sh</code>, <strong>EXCEPT</strong> <code>.md</code> markdown files.</p>
|
|
<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,
|
|
␉// or in any other markdown files within your entry, please.</code></pre>
|
|
<p><strong>NOTE</strong>: For purposes of visual illustration, ASCII TABs are shown above with the <code>␉</code> symbol.</p>
|
|
<div id="code">
|
|
|
|
</div>
|
|
<div id="languages">
|
|
|
|
</div>
|
|
<h2 id="use-html-comments-for-code-block-language-syntax">Use HTML comments for code block language syntax</h2>
|
|
<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><span style="color:red">❌</span> Incorrect.</p>
|
|
<pre class="<!---markdown-->"><code> ```c
|
|
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>
|
|
<p><span style="color:green">✔</span> Correct.</p>
|
|
<pre class="<!---markdown-->"><code> ``` <!---c-->
|
|
int main(void) {return 0;}
|
|
```</code></pre>
|
|
<p><strong>PLEASE NOTE</strong>: There is an <strong>IMPORTANT</strong> ASCII SPACE between the 3 backticks (```)
|
|
and the start of the HTML comment!</p>
|
|
<p><strong>PLEASE</strong>: Use an HTML comment that is of this form:</p>
|
|
<ul>
|
|
<li>starts with <code><!---</code> (note the 3 dashes)</li>
|
|
<li>is immediately followed by the language</li>
|
|
<li>and finally followed by <code>--></code> (note the 2 dashes)</li>
|
|
</ul>
|
|
<div id="code-and-text">
|
|
|
|
</div>
|
|
<h2 id="ensure-blank-line-between-code-block-and-text">Ensure blank line between code block and text</h2>
|
|
<p><span style="color:red">❌</span> Incorrect, missing empty line after closing 3 backtick (```) fence.</p>
|
|
<pre class="<!---markdown-->"><code> ``` <!---c-->
|
|
/* The C compiler will insist in flagging this an error, unfortunately */
|
|
int
|
|
main(int foo)
|
|
{
|
|
return foo;
|
|
}
|
|
```
|
|
C compilers cannot be given a -Wno-main-arg-errors flag.</code></pre>
|
|
<p><span style="color:green">✔</span> Correct, has empty line between closing fence and subsequent text.</p>
|
|
<pre class="<!---markdown-->"><code> ``` <!---c-->
|
|
/* The C compiler will insist in flagging this an error, unfortunately */
|
|
int
|
|
main(int foo)
|
|
{
|
|
return foo;
|
|
}
|
|
```
|
|
|
|
C compilers cannot be given a -Wno-main-arg-errors flag.</code></pre>
|
|
<div id="tag-slash">
|
|
|
|
</div>
|
|
<h2 id="do-not-add-trailing-slash-to-void-html-tags">Do not add trailing slash to void HTML tags</h2>
|
|
<p>The trailing slash on <a href="https://github.com/validator/validator/wiki/Markup-»-Void-elements">void HTML elements</a> has no effect and interacts
|
|
badly with unquoted attribute values; do not use. 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><span style="color:red">❌</span> Incorrect.</p>
|
|
<pre><code> <br/>
|
|
<hr/>
|
|
<img src="1984-anonymous-tattoo.jpg" alt="image of a tattoo of
|
|
the 1984 anonymous C code" width=600 height=401 /></code></pre>
|
|
<p><span style="color:green">✔</span> Correct.</p>
|
|
<pre><code> <br>
|
|
<hr>
|
|
<img src="1984-anonymous-tattoo.jpg" alt="image of a tattoo of
|
|
the 1984 anonymous C code" width=600 height=401></code></pre>
|
|
<div id="br">
|
|
|
|
</div>
|
|
<div id="backslash">
|
|
|
|
</div>
|
|
<h2 id="do-not-use-a-trailing-backslash-outside-of-a-code-block">Do not use a trailing backslash outside of a code block</h2>
|
|
<p><span style="color:red">❌</span> Incorrect, do not use escaped newlines outside of a code block.</p>
|
|
<pre><code> In markdown,\
|
|
do NOT use trailing\
|
|
backslashes outside of\
|
|
a code block</code></pre>
|
|
<p><span style="color:green">✔</span> Correct.</p>
|
|
<pre class="<!---html-->"><code> In markdown,<br>
|
|
use trailing<br>
|
|
br's outside of<br>
|
|
a code block
|
|
|
|
```
|
|
This is OK\
|
|
inside a\
|
|
markdown code\
|
|
block
|
|
```
|
|
|
|
`This is OK\`</code></pre>
|
|
<p>Doing it this way will prevent <code>pandoc(1)</code> from generating deprecated
|
|
HTML elements, such as <code><br /></code>.</p>
|
|
<div id="img">
|
|
|
|
</div>
|
|
<h2 id="do-not-use-markdown-style-images">Do not use markdown style images</h2>
|
|
<p><span style="color:red">❌</span> Incorrect.</p>
|
|
<pre><code> </code></pre>
|
|
<p><span style="color:green">✔</span> Correct.</p>
|
|
<pre><code> <img src="filename.png"
|
|
alt="describe the filename.png image for someone who cannot view it"
|
|
width=PIXEL_WIDTH height=PIXEL_HEIGHT>
|
|
|
|
Which allows for HTML <img> attributes `alt=`, `width=` and `length=`.</code></pre>
|
|
<p>The problem is that <code>pandoc(1)</code> generates problematic 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>
|
|
<h2 id="replace-markdown-style-horizontal-lines">Replace markdown style horizontal lines</h2>
|
|
<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 <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><span style="color:red">❌</span> Incorrect.</p>
|
|
<pre><code> * * *
|
|
- - -
|
|
---</code></pre>
|
|
<p><span style="color:green">✔</span> Correct.</p>
|
|
<pre><code> Regular divider...
|
|
<hr>
|
|
|
|
A short divider...
|
|
<hr style="width:10%;text-align:left;margin-left:0"></code></pre>
|
|
<div id="parentheses">
|
|
|
|
</div>
|
|
<h2 id="do-not-put-a-literal-or-in-markdown-link-titles">Do not put a literal “<code>(</code>” or “<code>)</code>” in markdown link titles</h2>
|
|
<p><span style="color:red">❌</span> Incorrect.</p>
|
|
<pre><code> [some (text)](https://example.com/curds)
|
|
[ls(1)](https://example.com/ls-man-page.1)</code></pre>
|
|
<p><span style="color:green">✔</span> Correct.</p>
|
|
<pre><code> [some &lpar;text&rpar;](https://example.com/curds)
|
|
[ls&lpar;1&rpar;](https://example.com/ls-man-page.1)</code></pre>
|
|
<div id="closing-parentheses">
|
|
|
|
</div>
|
|
<h2 id="do-not-end-markdown-links-with">Do not end markdown links with “<code>))</code>”</h2>
|
|
<p>Markdown links that end in “<code>))</code>” complicate parsing and sometimes lead
|
|
to incorrect URLs or file paths.</p>
|
|
<p><span style="color:red">❌</span> Incorrect.</p>
|
|
<pre><code> [some text](https://example.com/foo_(bar))
|
|
This thing, ([some text](some/path)), is NOT ideal.</code></pre>
|
|
<p><span style="color:green">✔</span> Correct.</p>
|
|
<pre><code> [some text](https://example.com/foo_&lpar;bar&rpar;)
|
|
This thing, [some text](some/path), is better.</code></pre>
|
|
<div id="italics">
|
|
|
|
</div>
|
|
<h2 id="use-_-for-italics-in-markdown">Use <code>_</code> for italics in markdown</h2>
|
|
<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><span style="color:red">❌</span> Incorrect.</p>
|
|
<pre><code> *this text is italic*
|
|
***this text is bold italic***</code></pre>
|
|
<p><span style="color:green">✔</span> Correct.</p>
|
|
<pre><code> _this text is italic_
|
|
**_this text is bold italic_**
|
|
_**this text is bold italic**_</code></pre>
|
|
<p><strong>BTW</strong>: the astute reader might notice that some cases of <code>*</code> for italic
|
|
might have slipped through. We do ask you, however, to please
|
|
observe this rule, as best you can.
|
|
<!-- AFTER: last line of markdown file: markdown.md --></p>
|
|
|
|
<!-- 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-2025 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"><h3>Copyright © 1984-2025 by Landon Curt Noll:
|
|
<a href="https://creativecommons.org/faq/#what-does-some-rights-reserved-mean"
|
|
target="_blank"
|
|
rel="license noopener noreferrer">Some Rights Reserved</a></h3>
|
|
<p>
|
|
This work is <b>licensed by Landon Curt Noll</b> under
|
|
<b><a href="https://creativecommons.org/licenses/by-sa/4.0/?ref=chooser-v1"
|
|
target="_blank"
|
|
rel="license noopener noreferrer"
|
|
style="display:inline-block;">CC BY-SA 4.0</a></b>.
|
|
<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"><br>
|
|
You should <b>carefully review</b> the
|
|
<b><a href="https://creativecommons.org/licenses/by-sa/4.0/legalcode.en"
|
|
target="_blank"
|
|
rel="license noopener noreferrer">CC BY-SA 4.0 LEGAL CODE</a></b>
|
|
before using the licensed material.<br>
|
|
You may wish to review the
|
|
<b><a href="./license.html"
|
|
target="_blank"
|
|
rel="license noopener noreferrer">highlights of some of the key features and terms</a></b>
|
|
of <b>CC BY-SA 4.0</b>.<br>
|
|
</p>
|
|
</div>
|
|
|
|
<div id="coda"><h3>Coda</h3>
|
|
<p>
|
|
<a href="https://validator.w3.org/nu/?doc=https%3A%2F%2Fwww.ioccc.org%2Fmarkdown.html" rel="nofollow">Nu HTML check this web page</a><br>
|
|
<a href="#top">Jump to top</a> <a href="#content">Jump to Content</a>
|
|
</p>
|
|
</div>
|
|
|
|
</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 -->
|