Landon Curt Noll
bb19f88222
Add `markdown.md` which generates `markdown.html` to document IOCCC markdown best practices. Changed `bin/gen-top-html.sh` VERSION from to "1.4.1 2024-04-16" to "1.4.2 2024-04-21". Added FAQ 0.6 about IOCCC mark requirements. Run `make gen_top_html timestamp` to perform the above.
295 lines
15 KiB
HTML
295 lines
15 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">
|
|
<meta name="keywords" content="IOCCC, markdown">
|
|
</head>
|
|
|
|
<!-- !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -->
|
|
<!-- !!! DO NOT MODIFY THIS FILE - This file is generated by a tool !!! -->
|
|
<!-- !!! DO NOT MODIFY THIS FILE - This file is generated by a tool !!! -->
|
|
<!-- !!! DO NOT MODIFY THIS FILE - This file is generated by a tool !!! -->
|
|
<!-- !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -->
|
|
|
|
<!-- END: this line ends content from: inc/head.default.html -->
|
|
|
|
<!-- -->
|
|
<!-- This web page was formed via the tool: bin/gen-top-html.sh -->
|
|
<!-- The content of main section of this web page came from: markdown.md -->
|
|
<!-- -->
|
|
|
|
<!-- !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -->
|
|
<!-- !!! Do not modify this web page, instead modify the file: markdown.md !!! -->
|
|
<!-- !!! Do not modify this web page, instead modify the file: markdown.md !!! -->
|
|
<!-- !!! Do not modify this web page, instead modify the file: markdown.md !!! -->
|
|
<!-- !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -->
|
|
|
|
<!-- Markdown content was converted into HTML via the tool: bin/md2html.sh -->
|
|
|
|
<!-- START: this line starts content from: inc/body.default.html -->
|
|
|
|
<body>
|
|
|
|
<!-- END: this line ends content from: inc/body.default.html -->
|
|
<!-- START: this line starts content from: inc/topbar.default.html -->
|
|
|
|
<div class="theader">
|
|
<nav class="topbar">
|
|
<div class="container">
|
|
<div class="logo">
|
|
IOCCC
|
|
</div>
|
|
|
|
<div class="topbar-items">
|
|
<div class="item">
|
|
<span class="item-header">
|
|
Home
|
|
</span>
|
|
|
|
<div class="sub-item">
|
|
<div class="outfit-font"><a href="./index.html">IOCCC Home</a></div>
|
|
<div class="outfit-font"><a href="./years.html">Winning Entries</a></div>
|
|
<div class="outfit-font"><a href="./authors.html">People who have won</a></div>
|
|
<div class="outfit-font"><a href="./location.html">Location of authors</a></div>
|
|
</div>
|
|
</div>
|
|
|
|
<div class="item">
|
|
<span class="item-header">
|
|
News
|
|
</span>
|
|
|
|
<div class="sub-item">
|
|
<div class="outfit-font"><a href="./news.html">IOCCC News</a></div>
|
|
<div class="outfit-font"><a href="./status.html">Contest status</a></div>
|
|
<div class="outfit-font"><a href="./next/index.html">Rules and Guidelines</a></div>
|
|
<div class="outfit-font"><a href="./faq.html#submit">How to enter the IOCCC</a></div>
|
|
<div class="outfit-font"><a href="./faq.html">FAQ</a></div>
|
|
</div>
|
|
</div>
|
|
|
|
<div class="item">
|
|
<span class="item-header">
|
|
Bugs
|
|
</span>
|
|
|
|
<div class="sub-item">
|
|
<div class="outfit-font"><a href="./bugs.html">Bugs & (mis)features</a></div>
|
|
<div class="outfit-font"><a href="./faq.html#fix_an_entry">Fixing IOCCC entries</a></div>
|
|
<div class="outfit-font"><a href="./faq.html#fix_web_site">Fixing the web site</a></div>
|
|
<div class="outfit-font"><a href="./faq.html#fix_author">Fixing author info</a></div>
|
|
<div class="outfit-font"><a href="./thanks-for-help.html">Thanks for the help</a></div>
|
|
</div>
|
|
</div>
|
|
|
|
<div class="item">
|
|
<span class="item-header">
|
|
Judges
|
|
</span>
|
|
|
|
<div class="sub-item">
|
|
<div class="outfit-font"><a href="./judges.html">The IOCCC Judges</a></div>
|
|
<div class="outfit-font"><a href="./contact.html">Contacting the IOCCC</a></div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</nav>
|
|
</div>
|
|
|
|
<!-- END: this line ends content from: inc/topbar.default.html -->
|
|
<!-- START: this line starts content from: inc/header.default.html -->
|
|
|
|
<div class="header">
|
|
<img src="./png/ioccc.png" alt="IOCCC image by Matt Zucker" width=300 height=110>
|
|
<h1>The International Obfuscated C Code Contest</h1>
|
|
<h2>IOCCC markdown best practices</h2>
|
|
</div>
|
|
|
|
<!-- END: this line ends content from: inc/header.default.html -->
|
|
<!-- START: this line starts content from: inc/navbar.empty.html -->
|
|
|
|
<div class="navbar">
|
|
<a class="Right" href="https://validator.w3.org/nu/?doc=https%3A%2F%2Fioccc-src.github.io%2Ftemp-test-ioccc%2Fmarkdown.html">✓</a>
|
|
</div>
|
|
|
|
<!-- END: this line ends content from: inc/navbar.empty.html -->
|
|
<!-- START: this line starts content from: inc/before-content.default.html -->
|
|
|
|
<div class="content" id="content">
|
|
|
|
<!-- END: this line ends content from: inc/before-content.default.html -->
|
|
<!-- START: this line starts content for HTML phase 21 by: bin/pandoc-wrapper.sh via bin/md2html.sh -->
|
|
|
|
<!-- BEFORE: 1st line of markdown file: markdown.md -->
|
|
<h1 id="ioccc-markdown-best-practices">IOCCC markdown best practices</h1>
|
|
<p>The IOCCC makes extensive use of <a href="https://daringfireball.net/projects/markdown/">markdown</a>.
|
|
For example, we <a href="faq.html#submit">submitting to the IOCCC</a>, we have people
|
|
to submit remarks about entry in markdown format. Every
|
|
<a href="years.html">winning IOCCC entry</a> uses a <code>README.md</code> markdown file
|
|
as the basis for forming the <code>index.html</code> web page for that entry.
|
|
All generated HTML pages on the <a href="https://www.ioccc.org/index.html">Official IOCCC web site</a>
|
|
start with some markdown content.</p>
|
|
<p>See the <a href="https://www.markdownguide.org/basic-syntax">markdown syntax</a> guide.
|
|
See also <a href="https://spec.commonmark.org/current/">CommonMark Spec</a>.</p>
|
|
<p>Nevertheless, the IOCCC does have certain practices that we ask authors to follow.</p>
|
|
<p>In particular there are things we ask people to please do <strong>NOT</strong> use markdown files:</p>
|
|
<h2 id="do-not-use-name-attributes-in-html-a-tags">Do not use name attributes in HTML a tags</h2>
|
|
<p>Please do not use the HTML construct:</p>
|
|
<pre><code> <a name="string">\</a></code></pre>
|
|
<p>as those are <strong>NOT</strong> part of the HTML 5 standard.</p>
|
|
<p>Instead use:</p>
|
|
<pre><code> <div id="string">...\</div></code></pre>
|
|
<p>where the “…” is the HTML you want to “name”. The <strong>div</strong>
|
|
encapsulates the HTML you want to name: I.e., the target of some
|
|
“<strong><a href=”#string”></strong>” or some other “<strong><a href=”URL#string”></strong>”
|
|
for the given page URL.</p>
|
|
<p>There are certain HTML Elements that cannot have internal “<strong><div
|
|
id=”string”>…</div></strong>”. For example you cannot do this:</p>
|
|
<pre><code> # <div id="string">This will not work</div></code></pre>
|
|
<p>For things like headings, you have to surround them as in:</p>
|
|
<pre><code> <div id="string">
|
|
# This will work
|
|
</div></code></pre>
|
|
<p>While some browsers will still recognize the HTML construct “<strong><a
|
|
name=”string”></a></strong>”, they may not in the future.</p>
|
|
<h2 id="do-not-use-trailing-backslash-outside-of-a-code-block">Do not use trailing backslash outside of a code block</h2>
|
|
<p>Unless the line is inside a markdown code block, please do <strong>NOT</strong>
|
|
end a markdown line with a trailing backslash (“\”). Instead use
|
|
a trailing “<strong><br></strong>”.</p>
|
|
<p>Instead of:</p>
|
|
<pre><code> In markdown,\
|
|
do not use trailing\
|
|
backslashes outside of\
|
|
a code block</code></pre>
|
|
<p>use:</p>
|
|
<pre><code> In markdown,<br>
|
|
use trailing<br>
|
|
br's outside of<br>
|
|
a code block</code></pre>
|
|
<p>Again, use of a trailing backslash (“\”) inside a markdown code block is fine:</p>
|
|
<pre><code>```
|
|
This is OK\
|
|
inside a\
|
|
markdown code\
|
|
block
|
|
```</code></pre>
|
|
<p>This will avoid <code>pandoc(1)</code> generating deprecated HTML elements such as:</p>
|
|
<p>“<strong><br /></strong>”</p>
|
|
<h2 id="do-not-use-markdown-image-elements">Do not use markdown image elements</h2>
|
|
<p>Please do not use the markdown embedded image element.</p>
|
|
<p>Instead of using this markdown element to embed an image:</p>
|
|
<pre><code> </code></pre>
|
|
<p>Use a “img” HTML element with “alt”, “alt”, “width” and “length”
|
|
attributes:</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></code></pre>
|
|
<p>For example, instead of:</p>
|
|
<pre><code> </code></pre>
|
|
<p>use this HTML:</p>
|
|
<pre><code> <img src="1984-anonymous-tattoo.jpg"
|
|
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
|
|
have “width” and “height” information so browsers have to slow down
|
|
on rendering text around the image until it can internally determine
|
|
the image size.</p>
|
|
<h2 id="do-not-use-markdown-style-horizontal-lines">Do not use markdown style horizontal lines</h2>
|
|
<p>Please do not use “<strong>—</strong>”-style lines in markdown to create horizontal
|
|
lines, nor to separate sections.</p>
|
|
<p>Unless something is inside a markdown code block, do not start a
|
|
line with 3 or more dashes (“-”).</p>
|
|
<p>Such causes <code>pandoc(1)</code> to generate “<strong><hr /></strong>”. The “<strong><hr
|
|
/></strong>” has no effect in standard HTML 5 and interacts badly with
|
|
unquoted attribute values.</p>
|
|
<p>If a horizontal line is really needed, use:</p>
|
|
<pre><code> <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="do-not-use-the-strike-html-element">Do not use the strike HTML element</h2>
|
|
<p>Please not use the HTML element:</p>
|
|
<pre><code> <strike>...</strike></code></pre>
|
|
<p>Use instead:</p>
|
|
<pre><code> <del>...</del></code></pre>
|
|
<h2 id="do-not-use-tt-html-elements">Do not use tt HTML elements</h2>
|
|
<p>Please do not use the tt HTML elements:</p>
|
|
<div class="sourceCode" id="cb16"><pre class="sourceCode html"><code class="sourceCode html"><span id="cb16-1"><a href="#cb16-1" aria-hidden="true" tabindex="-1"></a> <span class="dt"><</span><span class="kw">tt</span><span class="dt">></span>The HTML 5 obsolete tt element is obsolete<span class="dt"></</span><span class="kw">tt</span><span class="dt">></span></span></code></pre></div>
|
|
<p>Instead use either a monospaced span:</p>
|
|
<div class="sourceCode" id="cb17"><pre class="sourceCode html"><code class="sourceCode html"><span id="cb17-1"><a href="#cb17-1" aria-hidden="true" tabindex="-1"></a> <span class="dt"><</span><span class="kw">span</span><span class="ot"> style</span><span class="op">=</span><span class="st">"font-family: monospace;"</span><span class="dt">></span>Use of monospaced font is one option<span class="dt"></</span><span class="kw">span</span><span class="dt">></span></span></code></pre></div>
|
|
<p>Or better and easier still, use an inline markdown code block:</p>
|
|
<pre><code> `inline markdown code block is easier and much better`</code></pre>
|
|
<!-- AFTER: last line of markdown file: markdown.md -->
|
|
|
|
<!-- END: this line ends content for HTML phase 21 by: bin/pandoc-wrapper.sh via bin/md2html.sh -->
|
|
<!-- START: this line starts content from: inc/after-content.default.html -->
|
|
|
|
</div>
|
|
|
|
<!-- END: this line ends content from: inc/after-content.default.html -->
|
|
<!-- START: this line starts content from: inc/footer.default.html -->
|
|
|
|
<!--
|
|
|
|
Copyright © 1984-2024 by Landon Curt Noll. All Rights Reserved.
|
|
|
|
You are free to share and adapt this file under the terms of this license:
|
|
|
|
Creative Commons Attribution-ShareAlike 4.0 International (CC BY-SA 4.0)
|
|
|
|
For more information, see:
|
|
|
|
https://creativecommons.org/licenses/by-sa/4.0/
|
|
|
|
-->
|
|
|
|
<div class="footer">
|
|
<div id="copyright"><h2>Copyright and CC BY-SA 4.0 License</h2></div>
|
|
<p>All IOCCC content including this file and web page are:</p>
|
|
<b> Copyright © 1984-2024 by Landon Curt Noll. <a href="https://creativecommons.org/faq/#what-does-some-rights-reserved-mean">Some Rights Reserved</a>.</b>
|
|
<p>This work is licensed by Landon Curt Noll under:</p>
|
|
<p><b><a href="https://creativecommons.org/licenses/by-sa/4.0/?ref=chooser-v1"
|
|
target="_blank" rel="license noopener noreferrer" style="display:inline-block;"> CC BY-SA 4.0
|
|
<img style="height:22px!important;margin-left:3px;vertical-align:text-bottom;"
|
|
src="./png/cc.png"
|
|
alt="cc inside circle symbol">
|
|
<img style="height:22px!important;margin-left:3px;vertical-align:text-bottom;"
|
|
src="./png/by.png"
|
|
alt="person inside circle symbol">
|
|
<img style="height:22px!important;margin-left:3px;vertical-align:text-bottom;"
|
|
src="./png/sa.png"
|
|
alt="arrow looping back on itself inside circle symbol">
|
|
</a></b></p>
|
|
<p>The <b>CC BY-SA 4.0 LEGAL CODE</b> for this license is found under:</p>
|
|
<p> <b><a href="https://creativecommons.org/licenses/by-sa/4.0/legalcode.en">
|
|
https://creativecommons.org/licenses/by-sa/4.0/legalcode.en</a></b></p>
|
|
<p>You should <b>carefully review</b> all of the terms and conditions of the
|
|
<a href="https://creativecommons.org/licenses/by-sa/4.0/legalcode.en">actual license</a>
|
|
before using the licensed material.</p>
|
|
<p>You may wish to review the <b><a href="./license.html">highlights of some of the key
|
|
features and terms</a></b> of the <a href="https://creativecommons.org/licenses/by-sa/4.0/legalcode.en">actual license</a>.</p>
|
|
<h2>Coda</h2>
|
|
<p><a href="https://validator.w3.org/nu/?doc=https%3A%2F%2Fioccc-src.github.io%2Ftemp-test-ioccc%2Fmarkdown.html">Nu HTML check this web page</a></p>
|
|
<p><a href="#top">Jump to top</a> <a href="#content">Jump to Content</a> <a href="#inventory">Jump to Inventory</a></p>
|
|
</div>
|
|
|
|
<!-- END: this line ends content from: inc/footer.default.html -->
|
|
<!-- START: this line starts content from: inc/bottom.default.html -->
|
|
|
|
</body>
|
|
</html>
|
|
|
|
<!-- END: this line ends content from: inc/bottom.default.html -->
|