Files
ioccc/bin/index.html
T
Landon Curt Noll 9b98d02645 fix alignment and HTML bug
Fixed the alignment of an arrow in `markdown.md`.

Fixed an HTML error, caught by `make quick_www`, in `bin/README.md`.
2024-06-15 13:08:25 -07:00

1162 lines
58 KiB
HTML
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
<!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="Tools used to build and maintain the IOCCC website">
<meta name="keywords" content="IOCCC, tools, website tools, bin">
</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: bin/README.md -->
<!-- -->
<!-- !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -->
<!-- !!! Do not modify this web page, instead modify the file: bin/README.md !!! -->
<!-- !!! Do not modify this web page, instead modify the file: bin/README.md !!! -->
<!-- !!! Do not modify this web page, instead modify the file: bin/README.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">
People who have won
</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>
</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">
IOCCC 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/index.html" class="sub-item-link">
Rules and Guidelines
</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">
FAQ
</a>
</div>
<div class="outfit-font">
<a href="../faq.html#submit" class="sub-item-link">
How to enter the IOCCC
</a>
</div>
<div class="outfit-font">
<a href="../faq.html#fix_an_entry" class="sub-item-link">
Fixing IOCCC entries
</a>
</div>
<div class="outfit-font">
<a href="../faq.html#fix_web_site" class="sub-item-link">
Fixing the website
</a>
</div>
<div class="outfit-font">
<a href="../faq.html#fix_author" class="sub-item-link">
Fixing author info
</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">
IOCCC Home
</a>
</div>
<div class="outfit-font">
<a href="../judges.html" class="sub-item-link">
The IOCCC Judges
</a>
</div>
<div class="outfit-font">
<a href="../contact.html" class="sub-item-link">
Contacting the IOCCC
</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="../markdown.html" class="sub-item-link">
IOCCC markdown
</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">
People who have won
</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>
</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="../status.html">
Contest status
</a>
<a class="mobile-submenu-item" href="../next/index.html">
Rules and Guidelines
</a>
<a class="mobile-submenu-item" href="../news.html">
IOCCC News
</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="../faq.html#submit">
How to enter the IOCCC
</a>
<a class="mobile-submenu-item" href="../faq.html#fix_an_entry">
Fixing IOCCC entries
</a>
<a class="mobile-submenu-item" href="../faq.html#fix_web_site">
Fixing the website
</a>
<a class="mobile-submenu-item" href="../faq.html#fix_author">
Fixing author info
</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">
IOCCC Home
</a>
<a class="mobile-submenu-item" href="../judges.html">
The IOCCC Judges
</a>
<a class="mobile-submenu-item" href="../contact.html">
Contacting the IOCCC
</a>
<a class="mobile-submenu-item" href="../thanks-for-help.html">
Thanks for the help
</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 tools used build and maintain the IOCCC website</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%2Fbin%2Findex.html">&#x2713;</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: bin/README.md -->
<h1 id="bin">bin</h1>
<p>The <a href="index.html">bin directory</a> holds tools that build files, such as HTML
content, for the <a href="https://www.ioccc.org">official IOCCC website</a>.</p>
<p>For HTML content, the <a href="index.html">bin directory</a> tools make use of HTML
fragments from the <a href="../inc/index.html">inc directory</a> as well as various JSON
files and other content from the <a href="https://github.com/ioccc-src/temp-test-ioccc">IOCCC GitHub
repo</a>.</p>
<h2 id="bin-tools"><a href="index.html">bin/</a> tools</h2>
<p>All tools in this directory support a number of options that can be used to get
help, diagnose problems, see progress etc. These options are as follows:</p>
<h3 id="get-help-usage-string-of-a-tool">Get help / usage string of a tool</h3>
<p>If you need to remember the syntax of the tool or get certain notes about
different options, you can use the <code>-h</code> option.</p>
<p>For instance if you want help on the <a href="index.html#all-run">all-run.sh</a> tool
from the root directory, you would do:</p>
<pre><code> bin/all-run.sh -h</code></pre>
<h3 id="set-verbosity-level-of-a-tool">Set verbosity level of a tool</h3>
<p>If, however, you want verbosity, say for debugging purposes or to see what is
going on more, you should use the <code>-v level</code> option. For instance if you wish to
see what is going on with the
<a href="index.html#quick-readme2index">quick-readme2index.sh</a> tool, you might do:</p>
<pre><code> bin/quick-readme2index.sh -v 3</code></pre>
<p>to set the verbosity level to <code>3</code>. The default for verbosity is <code>0</code>, no
verbosity, though using the <a href="https://github.com/ioccc-src/temp-test-ioccc/blob/master/Makefile">top level Makefile</a> will,
for some tools, set a verbosity level.</p>
<h3 id="get-version-string-of-a-tool">Get version string of a tool</h3>
<p>If you just want to know what version the tool is, you can use the <code>-V</code> option.
For instance to see what version the <a href="index.html#chk-entry">chk-entry.sh</a> tool
is, you would do:</p>
<pre><code> bin/chk-entry.sh -V</code></pre>
<h3 id="other-notes">Other notes</h3>
<p>These options, and especially <code>-h</code> and <code>-v level</code>, can be very useful to get
basic usage information and to see what is going on when the tool is running.
For more details on each tool, including the ones mentioned above, see below. As
you go through each tool, if you need to understand more of it, we recommend
that you use the <code>-h</code> option on it first.</p>
<p>There are some scripts that are invoked by the
<a href="https://github.com/ioccc-src/temp-test-ioccc/blob/master/bin/md2html.cfg">bin/md2html.cfg</a> file but some of these tools can be directly
invoked as well, should you wish to see their output or if you have some odd
need to do so.</p>
<div id="all-run">
<h3 id="all-run.sh"><a href="https://github.com/ioccc-src/temp-test-ioccc/blob/master/bin/all-run.sh">all-run.sh</a></h3>
</div>
<p>Run a command on all winning entries.</p>
<p>For example:</p>
<pre><code> bin/all-run.sh -v 3 bin/quick-readme2index.sh -v 1</code></pre>
<p>Or for example:</p>
<pre><code> bin/all-run.sh -v 3 bin/readme2index.sh -v 1</code></pre>
<div id="all-years">
<h3 id="all-years.sh"><a href="https://github.com/ioccc-src/temp-test-ioccc/blob/master/bin/all-years.sh">all-years.sh</a></h3>
</div>
<p>Run a command on all IOCCC years.</p>
<p>For example:</p>
<pre><code> bin/all-years.sh -v 1 bin/gen-year-index.sh -v 1</code></pre>
<p>Or for example:</p>
<pre><code> bin/all-years.sh -v 1 bin/chk-entry.sh</code></pre>
<div id="chk-entry">
<h3 id="chk-entry.sh"><a href="https://github.com/ioccc-src/temp-test-ioccc/blob/master/bin/chk-entry.sh">chk-entry.sh</a></h3>
</div>
<p>Check an entry directory to verify that both the files in its manifest
(<code>.entry.json</code>) exist and that no other files exist.</p>
<p>For example:</p>
<pre><code> bin/chk-entry.sh 2020/ferguson1</code></pre>
<p>If you wish to run it on all entries, we recommend that this tool be invoked via
the top level <code>Makefile</code> by:</p>
<pre><code> make verify_entry_files</code></pre>
<div id="filelist-entry-json-awk">
<h3 id="filelist.entry.json.awk"><a href="https://github.com/ioccc-src/temp-test-ioccc/blob/master/bin/filelist.entry.json.awk">filelist.entry.json.awk</a></h3>
</div>
<p>Generate a list of files in an entry’s manifest (the <code>.entry.json</code> file).</p>
<p>For example:</p>
<pre><code> awk -f bin/filelist.entry.json.awk 2020/ferguson1/.entry.json</code></pre>
<p>In this case the command will list all the files of the
<a href="../2020/ferguson1/index.html">2020/ferguson1</a> winning entry.</p>
<div id="find-missing-links">
<h3 id="find-missing-links.sh"><a href="https://github.com/ioccc-src/temp-test-ioccc/blob/master/bin/find-missing-links.sh">find-missing-links.sh</a></h3>
</div>
<p>Find all markdown links to local files that do not exist.</p>
<p>This tool does <strong>NOT</strong> check that a remote URL exists.
This tool only checks on links to local files.</p>
<p>This tool does <strong>NOT</strong> check links in a given place in a file.
This tool only checks that local files linked by markdown exist.</p>
<p>This tool does <strong>NOT</strong> check HTML file links.
This tool only checks markdown based links.</p>
<p>Usage:</p>
<pre><code> bin/find-missing-links.sh -v 1</code></pre>
<p>If no missing links are found, this tool exits 0 with no output
(debug messages not withstanding), otherwise this tool will exit non-zero.</p>
<p>NOTE: If the markdown link is malformed, this tool
might generate an error about a file that does exist.
If this tool claims that a file is missing that does exist,
look for a malformed markdown line and/or use of markdown
that is <strong>NOT</strong> an IOCCC markdown best practice.</p>
<p>See also the <a href="../markdown.html">IOCCC markdown best practices</a> document for more
details.</p>
<p>We recommend that this tool be invoked via the top level <code>Makefile</code> by:</p>
<pre><code> make find_missing_links</code></pre>
<div id="gen-authors">
<h3 id="gen-authors.sh"><a href="https://github.com/ioccc-src/temp-test-ioccc/blob/master/bin/gen-authors.sh">gen-authors.sh</a></h3>
</div>
<p>Generate the top level <a href="../authors.html">authors.html</a> page.</p>
<p>Usage:</p>
<pre><code> bin/gen-authors.sh -v 1</code></pre>
<p>We recommend that this tool be invoked via the top level <code>Makefile</code> by:</p>
<pre><code> make gen_authors</code></pre>
<div id="gen-location">
<h3 id="gen-location.sh"><a href="https://github.com/ioccc-src/temp-test-ioccc/blob/master/bin/gen-location.sh">gen-location.sh</a></h3>
</div>
<p>Generate the top level <a href="../location.html">location.html</a> page.</p>
<p>Usage:</p>
<pre><code> bin/gen-location.sh -v 1</code></pre>
<p>We recommend that this tool be invoked via the top level <code>Makefile</code> by:</p>
<pre><code> make gen_location</code></pre>
<div id="gen-other-html">
<h3 id="gen-other-html.sh"><a href="https://github.com/ioccc-src/temp-test-ioccc/blob/master/bin/gen-other-html.sh">gen-other-html.sh</a></h3>
</div>
<p>Generate the HTML files (other than the README.md to index.html files) from
markdown files, of all entries.</p>
<p>Usage:</p>
<pre><code> bin/gen-other-html.sh -v 1</code></pre>
<p>We recommend that this tool be invoked via the top level <code>Makefile</code> by:</p>
<pre><code> make gen_other_html</code></pre>
<div id="gen-sitemap">
<h3 id="gen-sitemap.sh"><a href="https://github.com/ioccc-src/temp-test-ioccc/blob/master/bin/gen-sitemap.sh">gen-sitemap.sh</a></h3>
</div>
<p>Generate an XML sitemap for the IOCCC website.</p>
<p>Usage:</p>
<pre><code> bin/gen-sitemap.sh -v 1</code></pre>
<p>This would generate the <a href="../sitemap.xml">sitemap.xml</a> file.</p>
<p>We recommend that this tool be invoked via the top level <code>Makefile</code> by:</p>
<pre><code> make gen_sitemap</code></pre>
<p><strong>IMPORTANT NOTE</strong>: if a file is open with vim or some editor that creates a swap
file, this will cause a problem with the output.</p>
<div id="gen-status">
<h3 id="gen-status.sh"><a href="https://github.com/ioccc-src/temp-test-ioccc/blob/master/bin/gen-status.sh">gen-status.sh</a></h3>
</div>
<p>Generate <a href="../status.json">status.json</a> according to the modification date of
<a href="https://github.com/ioccc-src/temp-test-ioccc/blob/master/news.md">news.md</a> and/or whether the <code>contest_status</code> is changed
at the command line.</p>
<p>Without an argument, the <code>contest_status</code> is unchanged.</p>
<p>Usage:</p>
<pre><code> bin/gen-status.sh -v 1</code></pre>
<p>To force the <code>contest_status</code> to be closed:</p>
<pre><code> bin/gen-status.sh -v 1 closed</code></pre>
<p>To force the <code>contest_status</code> to be open:</p>
<pre><code> bin/gen-status.sh -v 1 open</code></pre>
<p>To see other valid statuses:</p>
<pre><code> bin/gen-status -h</code></pre>
<p>We recommend that this tool be invoked via the top level <code>Makefile</code> by:</p>
<pre><code> make gen_status</code></pre>
<p>unless the <code>contest_status</code> is to be changed, but since only the judges should
do that, that is not a problem.</p>
<div id="gen-top-html">
<h3 id="gen-top-html.sh"><a href="https://github.com/ioccc-src/temp-test-ioccc/blob/master/bin/gen-top-html.sh">gen-top-html.sh</a></h3>
</div>
<p>Generate a number of top level HTML pages for the IOCCC websites.</p>
<p>Usage:</p>
<pre><code> bin/gen-top-html.sh -v 1</code></pre>
<p>Examples of top level HTML pages built by this tool include:</p>
<ul>
<li><a href="../CODE_OF_CONDUCT.html">CODE_OF_CONDUCT.html</a></li>
<li><a href="../archive/historic/index.html">archive/historic/index.html</a></li>
<li><a href="../bin/index.html">bin/index.html</a></li>
<li><a href="../bugs.html">bugs.html</a></li>
<li><a href="../contact.html">contact.html</a></li>
<li><a href="../faq.html">faq.html</a></li>
<li><a href="../inc/index.html">inc/index.html</a></li>
<li><a href="../index.html">index.html</a></li>
<li><a href="../judges.html">judges.html</a></li>
<li><a href="../news.html">news.html</a></li>
<li><a href="../thanks-for-help.html">thanks-for-help.html</a></li>
</ul>
<p>We recommend that this tool be invoked via the top level <code>Makefile</code> by:</p>
<pre><code> make gen_top_html</code></pre>
<div id="gen-year-index">
<h3 id="gen-year-index.sh"><a href="https://github.com/ioccc-src/temp-test-ioccc/blob/master/bin/gen-year-index.sh">gen-year-index.sh</a></h3>
</div>
<p>Generate an <code>index.html</code> page for a given IOCCC year.</p>
<p>Usage:</p>
<pre><code> bin/gen-year-index.sh -v 1 2020</code></pre>
<p>This would create the <a href="../2020/index.html">2020/index.html</a> file.</p>
<p>We recommend that this tool be invoked via the top level <code>Makefile</code> by:</p>
<pre><code> make gen_year_index</code></pre>
<p>which will create the <code>index.html</code> for every IOCCC year (<code>1984/index.html</code>,
<code>1985/index.html</code> etc.).</p>
<div id="gen-years">
<h3 id="gen-years.sh"><a href="https://github.com/ioccc-src/temp-test-ioccc/blob/master/bin/gen-years.sh">gen-years.sh</a></h3>
</div>
<p>Generate the top level <a href="../years.html">years.html</a> page.</p>
<p>Usage:</p>
<pre><code> bin/gen-years.sh -v 1</code></pre>
<p>We recommend that this tool be invoked via the top level <code>Makefile</code> by:</p>
<pre><code> make gen_years</code></pre>
<div id="md2html">
<h3 id="md2html.sh"><a href="https://github.com/ioccc-src/temp-test-ioccc/blob/master/bin/md2html.sh">md2html.sh</a></h3>
</div>
<p>This is the primary tool that forms IOCCC generated HTML content from
markdown files (permanent markdown files or temporarily generated
markdown files) and HTML fragments from the <a href="../inc/index.html">inc directory</a>.</p>
<p>The <a href="https://github.com/ioccc-src/temp-test-ioccc/blob/master/bin/md2html.cfg">bin/md2html.cfg</a> configuration file is
used by <a href="https://github.com/ioccc-src/temp-test-ioccc/blob/master/bin/md2html.sh">md2html.sh</a> to drive the generation process.</p>
<div id="output-index-author">
<h3 id="output-index-author.sh"><a href="https://github.com/ioccc-src/temp-test-ioccc/blob/master/bin/output-index-author.sh">output-index-author.sh</a></h3>
</div>
<p>Output author’s or authors’ related HTML details for an entry’s index.html
page.</p>
<p>For an example, see the <a href="../1984/anonymous/index.html#author">author details in
1984/anonymous</a>.</p>
<p>This tool is used in the <a href="https://github.com/ioccc-src/temp-test-ioccc/blob/master/bin/md2html.cfg">bin/md2html.cfg</a> file as part of
the <a href="index.html#md2html">md2html tool</a>.</p>
<div id="output-index-inventory">
<h3 id="output-index-inventory.sh"><a href="https://github.com/ioccc-src/temp-test-ioccc/blob/master/bin/output-index-inventory.sh">output-index-inventory.sh</a></h3>
</div>
<p>Output the inventory in HTML form for an entry’s index.html page. For an example
inventory, see the <a href="../1984/anonymous/index.html#inventory">inventory in
1984/anonymous</a>.</p>
<p>This tool is used in the <a href="https://github.com/ioccc-src/temp-test-ioccc/blob/master/bin/md2html.cfg">bin/md2html.cfg</a> file as part of
the <a href="index.html#md2html">md2html tool</a>.</p>
<h3 id="output-year-index.sh"><a href="https://github.com/ioccc-src/temp-test-ioccc/blob/master/bin/output-year-index.sh">output-year-index.sh</a></h3>
<p>Output the inventory for a given year’s winning entries in HTML form. In other
words in <a href="../1984/index.html">1984</a> it would list, as links, the four winning
entries, which you can see directly at <a href="../1984/index.html#inventory">1984
inventory</a>.</p>
<p>This tool is used in the <a href="https://github.com/ioccc-src/temp-test-ioccc/blob/master/bin/md2html.cfg">bin/md2html.cfg</a> file as part of
the <a href="index.html#md2html">md2html tool</a>.</p>
<h3 id="pandoc-wrapper.sh"><a href="https://github.com/ioccc-src/temp-test-ioccc/blob/master/bin/pandoc-wrapper.sh">pandoc-wrapper.sh</a></h3>
<p>Wrapper tool to run <code>pandoc(1)</code>.</p>
<div id="quick-readme2index">
<h3 id="quick-readme2index.sh"><a href="https://github.com/ioccc-src/temp-test-ioccc/blob/master/bin/quick-readme2index.sh">quick-readme2index.sh</a></h3>
</div>
<p>Build an entry’s <code>index.html</code> file if the entry directory
does not have a non-empty <code>index.hmtl</code> file, or if either
<code>.entry.json</code> or <code>README.md</code> is newer than the <code>index.hmtl</code> file.</p>
<p>This is useful when only a few entries have been
modified (resulting in an updated <code>.entry.json</code> file)
or if the <code>README.md</code> of a few entries have been changed: while the
<a href="index.html#readme2index">readme2index.sh</a> script takes a few seconds
to run for a few entries, when applied to 300+ entries, the extra time can add
up.</p>
<p>If only a few <code>index.hmtl</code> files need updating, then
this command will only briefly pause while the
<a href="index.html#readme2index">readme2index.sh</a> can take much longer.</p>
<p>Usage:</p>
<pre><code> # For all entries:
bin/all-run.sh -v 3 bin/quick-readme2index.sh -v 1
# For an individual entry:
bin/quick-readme2index.sh -v 1 2020/ferguson2</code></pre>
<p><strong>NOTE</strong>: This command assumes that the relative
modification times for <code>README.md</code>, <code>.entry.json</code>,
and <code>index.html</code> are correct. If in doubt, use
<a href="index.html#readme2index">readme2index.sh</a>.</p>
<p>We recommend that this tool be invoked via the top level <code>Makefile</code> by:</p>
<pre><code> make quick_entry_index</code></pre>
<div id="readme2index">
<h3 id="readme2index.sh"><a href="https://github.com/ioccc-src/temp-test-ioccc/blob/master/bin/readme2index.sh">readme2index.sh</a></h3>
</div>
<p>Convert an entry’s <code>README.md</code> into its <code>index.html</code> file.</p>
<p>Usage:</p>
<pre><code> bin/readme2index.sh -v 3 1984/mullender</code></pre>
<p>To build <code>index.html</code> files for all entries:</p>
<pre><code> bin/all-run.sh -v 3 bin/readme2index.sh -v 1</code></pre>
<p>We recommend that this tool be invoked via the top level <code>Makefile</code> by:</p>
<pre><code> make entry_index</code></pre>
<div id="status2html">
<h3 id="status2html.sh"><a href="https://github.com/ioccc-src/temp-test-ioccc/blob/master/bin/status2html.sh">status2html.sh</a></h3>
</div>
<p>Convert <a href="../status.json">status.json</a> into HTML.</p>
<p>This tool is a ‘before tool’ (<code>-b tool</code>) that is intended
to be used by <a href="index.html#gen-status">gen-status.sh</a>.</p>
<div id="sgi">
<h3 id="sgi.sh"><a href="https://github.com/ioccc-src/temp-test-ioccc/blob/master/bin/sgi.sh">sgi.sh</a></h3>
</div>
<p>Sort <code>.gitignore</code> content from <code>stdin</code> to <code>stdout</code>.</p>
<p>We sort with lines starting with <code>#</code> first.
We sort with lines starting with <code>*</code> second.
We sort with lines that do not start with <code>[#!*]</code> third.
We sort with lines starting with <code>!</code> fourth.</p>
<p>This tool is used by <a href="index.html#sort-gitignore">sort.gitignore.sh</a>.</p>
<div id="sort-gitignore">
<h3 id="sort.gitignore.sh"><a href="https://github.com/ioccc-src/temp-test-ioccc/blob/master/bin/sort.gitignore.sh">sort.gitignore.sh</a></h3>
</div>
<p>Sort a <code>.gitignore</code> in a entry directory.</p>
<p>Usage:</p>
<pre><code> bin/sort.gitignore.sh -v 1 YYYY/dir</code></pre>
<p>Suggested usage (for all <code>.gitignore</code> files):</p>
<pre><code> bin/all-run.sh bin/sort.gitignore.sh -v 1</code></pre>
<p>We recommend that this tool be invoked via the top level <code>Makefile</code> by:</p>
<pre><code> make sort_gitignore</code></pre>
<div id="subst-default">
<h3 id="subst.default.sh"><a href="https://github.com/ioccc-src/temp-test-ioccc/blob/master/bin/subst.default.sh">subst.default.sh</a></h3>
</div>
<p>Print default substitutions.</p>
<p>This tool is used in the <a href="https://github.com/ioccc-src/temp-test-ioccc/blob/master/bin/md2html.cfg">bin/md2html.cfg</a> file.</p>
<div id="subst-entry-index">
<h3 id="subst.entry-index.sh"><a href="https://github.com/ioccc-src/temp-test-ioccc/blob/master/bin/subst.entry-index.sh">subst.entry-index.sh</a></h3>
</div>
<p>Print substitutions for an entry’s <code>index.html</code>.</p>
<p>This tool is used in the <a href="https://github.com/ioccc-src/temp-test-ioccc/blob/master/bin/md2html.cfg">bin/md2html.cfg</a> file.</p>
<div id="subst-entry-navbar-awk">
<h3 id="subst.entry-navbar.awk"><a href="https://github.com/ioccc-src/temp-test-ioccc/blob/master/bin/subst.entry-navbar.awk">subst.entry-navbar.awk</a></h3>
</div>
<p>Output substitutions for <code>navbar</code> on behalf of an entry.</p>
<p>This tool is used in <a href="index.html#subst-entry-index">subst.entry-index.sh</a>.</p>
<div id="subst-year-index">
<h3 id="subst.year-index.sh"><a href="https://github.com/ioccc-src/temp-test-ioccc/blob/master/bin/subst.year-index.sh">subst.year-index.sh</a></h3>
</div>
<p>Print substitutions for a year level <code>index.html</code>.</p>
<p>This tool is used in the <a href="https://github.com/ioccc-src/temp-test-ioccc/blob/master/bin/md2html.cfg">bin/md2html.cfg</a> file.</p>
<div id="subst-year-navbar-awk">
<h3 id="subst.year-navbar.awk"><a href="https://github.com/ioccc-src/temp-test-ioccc/blob/master/bin/subst.year-navbar.awk">subst.year-navbar.awk</a></h3>
</div>
<p>Output substitutions for <code>navbar</code> on behalf of a year level <code>index.html</code>.</p>
<p>This tool is used in <a href="index.html#subst-year-index">subst.year-index.sh</a>.</p>
<div id="tar-entry">
<h2 id="tar-entry.sh"><a href="https://github.com/ioccc-src/temp-test-ioccc/blob/master/bin/tar-entry.sh">tar-entry.sh</a></h2>
</div>
<p>Form a compressed tarball for an entry.</p>
<p>Usage:</p>
<pre><code> bin/tar-entry.sh -v 1 YYYY/dir</code></pre>
<p>Suggested usage:</p>
<pre><code> bin/all-run.sh -v 3 bin/tar-entry.sh -v 1 -W</code></pre>
<div id="tar-year">
<h2 id="tar-year.sh"><a href="https://github.com/ioccc-src/temp-test-ioccc/blob/master/bin/tar-year.sh">tar-year.sh</a></h2>
</div>
<p>Form a compressed tarball for an IOCCC year.</p>
<p>Usage:</p>
<pre><code> bin/tar-year.sh -v 1 YYYY</code></pre>
<p>Suggested usage:</p>
<pre><code> bin/all-years.sh -v 3 bin/tar-year.sh -v 1 -W</code></pre>
<p>We recommend that this tool be invoked via the top level <code>Makefile</code> by:</p>
<pre><code> make form_year_tarball</code></pre>
<div id="untar-entry">
<h2 id="untar-entry.sh"><a href="https://github.com/ioccc-src/temp-test-ioccc/blob/master/bin/untar-entry.sh">untar-entry.sh</a></h2>
</div>
<p>Untar an entry’s compressed tarball.</p>
<p>Usage:</p>
<pre><code> bin/untar-entry.sh -v 1 YYYY/dir</code></pre>
<p>Suggested usage:</p>
<pre><code> bin/all-run.sh -v 3 bin/untar-entry.sh -v 1</code></pre>
<p>We recommend that this tool be invoked via the top level <code>Makefile</code> by:</p>
<pre><code> make untar_entry_tarball</code></pre>
<div id="untar-year">
<h2 id="untar-year.sh"><a href="https://github.com/ioccc-src/temp-test-ioccc/blob/master/bin/untar-year.sh">untar-year.sh</a></h2>
</div>
<p>Untar an IOCCC year’s compressed tarball.</p>
<p>Usage:</p>
<pre><code> bin/untar-year.sh -v 1 YYYY</code></pre>
<p>Suggested usage:</p>
<pre><code> bin/all-years.sh -v 3 bin/untar-year.sh -v 1</code></pre>
<p>We recommend that this tool be invoked via the top level <code>Makefile</code> by:</p>
<pre><code> make untar_year_tarball</code></pre>
<div id="how">
<h1 id="how-ioccc-html-content-is-built">How IOCCC HTML content is built</h1>
</div>
<p>The <a href="index.html#md2html">md2html.sh</a> tool is the primary tool that
is used to form all IOCCC related HTML pages for the <a href="https://www.ioccc.org">official IOCCC web
site</a>.</p>
<p>Nearly all IOCCC related HTML pages are built from markdown files,
from either permanent markdown files or temporary generated markdown files,
as well as HTML fragments from the <a href="../inc/index.html">inc directory</a>.</p>
<p>Most HTML content is built from permanent markdown files, such as a <code>README.md</code>
markdown file found in each entry directory. Some HTML content are generated
from temporary markdown files. These temporary markdown files are produced by
tools in the <a href="index.html">bin directory</a> and exist only while the tool is running.</p>
<p>In addition to converting markdown to HTML, the canonical way that HTML content is
built uses, by default, files from the <a href="../inc/index.html">inc directory</a>, of
the file name form:</p>
<pre><code> *.default.html</code></pre>
<p>By using command line options of the form:</p>
<pre><code> -H phase=name</code></pre>
<p>where <code>phase</code> is the name of an HTML phase,
a non-default file may be used. For example:</p>
<pre><code> -H navbar=up2index</code></pre>
<p>will cause <a href="../inc/navbar.up2index.html">inc/navbar.up2index.html</a>
instead of <a href="../inc/navbar.default.html">inc/navbar.default.html</a> to be
used during the <em>navbar</em> HTML phase.</p>
<p>If <code>name</code> is dot (i.e., <code>.</code>), then the given HTML phase is skipped.
For example:</p>
<pre><code> -H footer=.</code></pre>
<p>will cause no HTML content to be produced during the <code>footer</code> HTML phase.</p>
<div id="html">
<h2 id="html-phases">HTML phases</h2>
</div>
<p>The following HTML phase files are used to build HTML content:</p>
<ol start="0" type="1">
<li><a href="../inc/top.default.html">inc/top.default.html</a></li>
<li><a href="../inc/head.default.html">inc/head.default.html</a></li>
<li><a href="../inc/body.default.html">inc/body.default.html</a></li>
<li><a href="../inc/topbar.default.html">inc/topbar.default.html</a></li>
<li><a href="../inc/header.default.html">inc/header.default.html</a></li>
<li><a href="../inc/navbar.default.html">inc/navbar.default.html</a></li>
<li><a href="../inc/before-content.default.html">inc/before-content.default.html</a></li>
</ol>
<p>Phases 7-19 are reserved for future use.</p>
<ol start="20" type="1">
<li>((insert ‘before tool’ output))</li>
<li>((insert ‘pandoc wrapper tool’ output))</li>
<li>((insert ‘after tool’ output))</li>
</ol>
<p>Phases 23-29 are reserved for future use.</p>
<ol start="30" type="1">
<li><a href="../inc/after-content.default.html">inc/after-content.default.html</a></li>
<li><a href="../inc/footer.default.html">inc/footer.default.html</a></li>
<li><a href="../inc/bottom.default.html">inc/bottom.default.html</a></li>
</ol>
<p>Phases 33-39 are reserved for future use.</p>
<p>In all of the above HTML phase numbers, symbols of the form <code>%%TOKEN%%</code> are
substituted.</p>
<p>Substitutions of the form <code>%%TOKEN%%</code> are performed on included HTML content,
content generated by the ‘before tool’ (<code>-b tool</code>),
content generated by the ‘after tool’ (<code>-a tool</code>),
as well as the markdown content given to the <code>pandoc wrapper tool</code> (<code>-p tool</code>).</p>
<p>It is an error, unless <code>-S</code> is given, for any phase, except phases HTML
20-29, to not substitute all <code>%%TOKEN%%</code>s. For phases HTML 20-29, any
<code>%%TOKEN%%</code> that is not substituted are passed thru without substitution.</p>
<p>See the tool <a href="index.html#readme2index">readme2index.sh</a> for an example of
how HTML phases are implemented.</p>
<div id="getopt">
<h2 id="getopt-phase-processing-of-the-command-line">getopt phase processing of the command line</h2>
</div>
<p>The command options are evaluated in the following <code>getopt</code> phases:</p>
<div id="getopt-0">
<h3 id="getopt-phase-0"><code>getopt</code> phase 0</h3>
</div>
<p>In <code>getopt</code> phase 0 we parse command line options and save all arguments for the
end of the final command line.</p>
<p>Depending on the program, the argument at the end is directory under topdir, or
it is a file under topdir.</p>
<p><code>getopt</code> phase 0 is the only <code>getopt</code> phase where <code>-d topdir</code> and <code>-c md2html.cfg</code> may be used.</p>
<div id="getopt-1">
<h3 id="getopt-phase-1"><code>getopt</code> phase 1</h3>
</div>
<p>In <code>getopt</code> phase 1 we execute each <code>-o "output tool"</code> from <code>getopt</code> phase 0,
parsing the output as a command line.</p>
<p>The <code>-o "output tool"</code> may be given <code>optstr</code> from <code>"-O tool=optstr"</code>, followed
by the phase 0 argument.</p>
<p>The <code>-o "output tool"</code> is not allowed to output another <code>"-o tool"</code> or a <code>"-O tool=optstr"</code>. Instead a <code>-o "output tool"</code> may execute another <code>-o "output tool"</code> and merge the output into its own.</p>
<div id="getopt-2">
<h3 id="getopt-phase-2"><code>getopt</code> phase 2</h3>
</div>
<p>In <code>getopt</code> phase 2 we parse the <code>cfg_options</code> from the first <code>md2html.cfg</code> line
matched by a saved argument.</p>
<p>The match is made with the (possibly modified) phase 0 argument.</p>
<div id="getopt-3">
<h3 id="getopt-phase-3"><code>getopt</code> phase 3</h3>
</div>
<p>In <code>getopt</code> phase 3 we execute each <code>-o "output tool"</code> from <code>getopt</code> phase 2,
parsing the output as a command line.</p>
<p>The <code>-o "output tool"</code> may be given <code>optstr</code> from <code>"-O tool=optstr"</code>, followed
by the phase 0 argument.</p>
<p>The <code>-o "output tool"</code> is not allowed to output another <code>"-o tool"</code> or a <code>"-O tool=optstr"</code>. Instead a <code>-o "output tool"</code> may execute another <code>-o "output tool"</code> and merge the output into its own.</p>
<h3 id="command-line-option-order">Command line option order</h3>
<p>Most command line options override earlier copies of the same option. However
in the case of <code>-H phase=name</code>, a later <code>-H phase=name</code> only overrides an
earlier use of <code>-H</code> for the same <code>phase</code> <em>only</em>. Also in the case of <code>-s token=value</code>, a later <code>-s token=value</code> only overrides an earlier use of <code>-s</code> for
the same <code>token</code> <em>only</em>.</p>
<h3 id="output-tools">Output tools</h3>
<p>An “output tool” may be used to add certain additional command line options to be processed.</p>
<p><strong>IMPORTANT</strong>: An “output tool” will print each command line option / argument on a separate line.
So for example, if an “output tool” wishes to convey:</p>
<pre><code> -s TITLE=&#39;IOCCC entry locations&#39; -H navbar=top-of-site</code></pre>
<p>The “output tool” would output the following 4 lines:</p>
<pre><code> -s
TITLE=&#39;IOCCC entry locations&#39;
-H
navbar=top-of-site</code></pre>
<p>The command line options printed by an “output tool” are processed
after all command line options, and all options from a matching
line from the <a href="https://github.com/ioccc-src/temp-test-ioccc/blob/master/bin/md2html.cfg">md2html.cfg</a> file, and before any filename arguments
on the command line.</p>
<p>For example:</p>
<pre><code> command [command_options ..] [cfg_options ..] [output_tool_options ..] [--] [filename_arg ..]</code></pre>
<p>Here the <code>command</code> first processes any command line options, then it processes
<code>cfg_options</code> obtained from this file from a first match of a given <code>file_glob</code>,
then it processes <code>output tool</code> (i.e., <code>-o tool</code>) options found in
<code>command_options</code>, and <code>cfg_options</code>, then an optional <code>--</code> (end of all
options), then zero of more <code>filename_arg</code> filename arguments.</p>
<p>The <code>-o tool</code> must <strong>NOT</strong> output any <code>-o tool</code> options as <code>-o tool</code> is <strong>NOT
RECURSIVE</strong>. A <code>-o tool</code> is free, however, to execute other <code>-o tool</code> output
tools and merge the output from those tools into its own.</p>
<div id="special-exit-code">
<h3 id="special--e-exitcode-option">Special <code>-E exitcode</code> option</h3>
</div>
<p>When <code>-E exitcode</code> is evaluated, the application will exit with the <code>exitcode</code>
value. If one wishes to also output a message to <code>stderr</code>, the <code>-e string</code> must
come <strong>BEFORE</strong> any <code>-E exitcode</code> in the command line.</p>
<h3 id="substitution-tokens">Substitution tokens</h3>
<p>All tokens (i.e., strings of the form <code>%%token%%</code>) <strong>MUST</strong> be substituted (by
some <code>-s token=value</code>) in all HTML output, except during phase numbers 20-29
(i.e., except <code>before tool</code> output, pandoc wrapper output, and <code>after tool</code>
output), or the command will exit non-zero, unless <code>-S</code> is given. If <code>-S</code> is
given, only a warning about non-substituted tokens will be written to <code>stderr</code>.</p>
<p>The command line of tools in the <a href="index.html">bin directory</a>, and perhaps
modified via the <a href="https://github.com/ioccc-src/temp-test-ioccc/blob/master/bin/md2html.cfg">md2html config file</a> may change to using a
different filename for a given phase.</p>
<p>For example when forming the HTML from
<a href="https://github.com/ioccc-src/temp-test-ioccc/blob/master/2020/ferguson1/chocolate-cake.md">2020/ferguson1/chocolate-cake.md</a>,
a different <code>navbar</code> navigation bar is needed. So instead of the
usual top navigation bar that normally directs people to the previous
entry for the year, or go up to the year page, or to the next entry
for the year, a top navigation bar to just go up to the entry’s
main page is needed. A line in the <a href="https://github.com/ioccc-src/temp-test-ioccc/blob/master/bin/md2html.cfg">md2html config file</a>
that refers to
<a href="https://github.com/ioccc-src/temp-test-ioccc/blob/master/2020/ferguson1/chocolate-cake.md">2020/ferguson1/chocolate-cake.md</a> may
specify use of <code>navbar.up2index.html</code> (as <code>navbar.up2index</code>)instead of using the
<code>navbar.default.html</code> (<code>navbar.default.html</code>) default.</p>
<p>The HTML phase may be skipped resulting in no HTML output during a given phase
and furthermore, forming no HTML content from a given markdown file altogether.</p>
<p>See comments in the <a href="https://github.com/ioccc-src/temp-test-ioccc/blob/master/bin/md2html.cfg">md2html config file</a> for details.
See also, the tool <a href="index.html#readme2index">readme2index.sh</a> for an example of
how such command lines are used.</p>
<h1 id="use-caution-when-modifying-inc-files">Use CAUTION when modifying <code>inc/</code> files</h1>
<p>Some of the files under this directory are used to form <strong>MOST</strong> of the HTML content
on the <a href="https://www.ioccc.org">official IOCCC website</a>.</p>
<p>These files are used to form <strong>MOST</strong> of the HTML content
on the <a href="https://ioccc-src.github.io/temp-test-ioccc/">experimental website</a>.</p>
<p>… and in particular files under <a href="../inc/index.html">inc</a> that are of the form
(called default HTML files) …:</p>
<pre><code> *.default.html</code></pre>
<p>… contain default content used to form IOCCC HTML / IOCCC web pages.</p>
<p>Instead of editing the default HTML files in order to fix a special web page,
consider making a copy of the default file and modifying the <a href="https://github.com/ioccc-src/temp-test-ioccc/blob/master/bin/md2html.cfg">md2html config
file</a> to refer to the copy instead. That way your special case
situation will not impact <strong>MOST</strong> of the HTML content.</p>
<h1 id="why-we-do-not-use-certain-well-known-html-technologies">Why we do not use certain well-known HTML technologies</h1>
<p>You may wonder why we need these files in the first place. You may wonder why
we even need the tools in the <a href="index.html">bin</a> directory when there other
solutions available to form web pages.</p>
<div id="static-only">
<h2 id="static-web-pages-only">Static web pages only</h2>
</div>
<p>Here are some reasons why we are using these files and
special tools to create HTML content / IOCCC web pages:</p>
<p>We host <a href="https://www.ioccc.org">official IOCCC website</a> via <a href="https://pages.github.com">GitHub
pages</a>. As of the time this file written, <strong>only
static web pages are supported</strong>.</p>
<h2 id="we-cannot-use-server-side-include">We cannot use server side include</h2>
<p>We use <a href="#static-only">static web pages</a>, so use of “server side include” is not
available to the IOCCC.</p>
<p>For example, Apache SSI <code>#include</code> does not work on <a href="https://pages.github.com">GitHub
pages</a>.</p>
<h2 id="we-cannot-use-a-back-end-database">We cannot use a back-end database</h2>
<p>We use <a href="index.html#static-only">static web pages</a>, so use of a “back-end database” is not
available to the IOCCC.</p>
<div id="why-github">
<h2 id="we-cannot-use-non-github-web-servers">We cannot use non-GitHub web servers</h2>
</div>
<p>The <a href="https://pages.github.com">GitHub pages</a> have the distributed server capacity needed to handle
the <strong>huge download volume</strong> or <a href="https://en.wikipedia.org/wiki/Slashdot_effect">Slashdot effect</a>
that happens when a IOCCC entries are published.</p>
<p>Most so-called low cost web hosting sites have a somewhat hidden excessive bandwidth charge
and/or cap bandwidth when the volume gets too high, and/or do not have the infrastructure
that can handle the <a href="https://en.wikipedia.org/wiki/Slashdot_effect">Slashdot effect</a>.</p>
<p>The IOCCC had experience with people offering web mirrors and even free hosting
only to find that the generous benefactor moves on, or their service is purchased
by someone else who is not so generous. While it is possible that GitHub might someday
suffer a similar fate, for the time being we are betting that GitHub will remain
willing to host the IOCCC.</p>
<p>The <a href="https://www.ioccc.org">official IOCCC website</a> is, after all, primarily C
source code with some supporting documentation (sometimes :-) ). As such it is
a natural fit for GitHub and <a href="https://pages.github.com">GitHub pages</a>.</p>
<h2 id="we-cannot-use-the-html-object-element">We cannot use the HTML <code>&lt;object&gt;</code> element</h2>
<p>The <code>&lt;object&gt;</code> HTML element does not work for our needs.</p>
<p>HTML elements do not extend into the content that they include.
For example, menu bars (see the <a href="../ioccc.css">ioccc.css</a>
stylesheet) will not operate under an HTML element.</p>
<h2 id="we-cannot-use-the-html-embed-element">We cannot use the HTML <code>&lt;embed&gt;</code> element</h2>
<p>The <code>&lt;embed&gt;</code> HTML element does not work for our needs.</p>
<p>This element wants one to specify the <code>width</code> and <code>height</code> in pixels.
Use of a percentage is not officially supported even if some browsers
might do so. Our Responsive Web Design in the
<a href="../ioccc.css">ioccc.css</a> stylesheet
needs to be responsive to small-sized cell phone-like screens,
mid-sized table-like screens, as well as large-sized desktop-like screens.
Specifying a <code>width</code> and <code>height</code> in pixels will not work well in
all of those screen size contexts.</p>
<h2 id="we-cannot-use-the-html-iframe-element">We cannot use the HTML <code>&lt;iframe&gt;</code> element</h2>
<p>The <code>&lt;iframe&gt;</code> HTML element does not work for our needs.</p>
<p>This element wants one to specify the <code>width</code> and <code>height</code> in pixels. Use of a
percentage is not officially supported even if some browsers might do so. Our
Responsive Web Design in the <a href="../ioccc.css">ioccc.css</a> stylesheet
needs to be responsive to small-sized cell phone-like screens, mid-sized
table-like screens, as well as large-sized desktop-like screens. Specifying a
<code>width</code> and <code>height</code> in pixels will not work well in all of those screen size
contexts.</p>
<h2 id="we-cannot-use-javascript-to-include-content">We cannot use JavaScript to include content</h2>
<p>We do not use JavaScript to include HTML content.</p>
<p>While the IOCCC may use JavaScript in the future to directly render things like
C source code, we will do so in such a way that someone will be able to view
<a href="https://www.ioccc.org">official IOCCC website</a> content with JavaScript
disabled.</p>
<p>The IOCCC will <strong>NOT MANDATE USE OF JavaScript</strong> to view <a href="https://www.ioccc.org">official IOCCC web
site</a> (except for some mobile devices for the menu).</p>
<p>For this reason, we cannot use JavaScript include HTML content.</p>
<div id="terms">
<h1 id="ioccc-terms">IOCCC terms</h1>
</div>
<p>The following IOCCC terms apply to tools, JSON files, and the directory structure of this repo.</p>
<h2 id="author"><code>author</code></h2>
<p>An individual who was an <code>author</code> of at least one winning IOCCC entry.</p>
<p>Some authors have submitted more than one IOCCC entry that won. Some winning
IOCCC entries have more than one author. In that case we might use the word
<code>authors</code>.</p>
<div id="author-handle">
<h2 id="author_handle"><code>author_handle</code></h2>
</div>
<p>An <code>author_handle</code> is string that refers to a given author and is unique to the
IOCCC. Each author has <strong>EXACTLY ONE</strong> <code>author_handle</code>.</p>
<p>For each <code>author_handle</code>, there will be a JSON file located at:</p>
<pre><code> author/author_handle.json</code></pre>
<p>where <code>author_handle</code> is the author’s <code>author_handle</code>.</p>
<p>Because the <code>author_handle</code> is used to form a JSON filename, the string must be
a POSIX safe string with the addition of <code>+</code> (for technical reasons beyond this
document). In particular, the <code>author_handle</code> must be an ASCII
string that matches this regexp:</p>
<pre><code> ^[0-9A-Za-z][0-9A-Za-z._+-]*$&quot;</code></pre>
<p>Default <code>author_handle</code>s do not have multiple consecutive <code>_</code> (underscore)
characters. Nevertheless, multiple consecutive <code>_</code> (underscore) characters are
allowed. Contest submitters who wish to override the <code>author_handle</code> may do so.</p>
<p>The <code>author_handle</code> is derived from the name of the author. While there is a
algorithm that maps the name of the author (which can contain any UTF-8
characters) into a default <code>author_handle</code> string, those who submit an entry to
the IOCCC are free to choose a different <code>author_handle</code> string if they so
desire.</p>
<p>An <code>author</code> who has won a previous IOCCC is encouraged to reuse their
<code>author_handle</code> so that new winning entries can be associated with the same
author.</p>
<p>For an anonymous <code>author</code>, their handle is one of these forms:</p>
<pre><code> Anonymous_year</code></pre>
<p>or:</p>
<pre><code> Anonymous_year.digits</code></pre>
<p>The latter form is in case there are more than one anonymous author in a given
year.</p>
<p>NOTE: even if the directory name is not <code>anonymous</code> the above rules apply as in
in the case of <a href="../2005/anon/index.html">2005/anon</a>.</p>
<p>Anonymous <code>author_handle</code>’s match this regexp:</p>
<pre><code> Anonymous_[0-9][0-9][0-9][0-9][.0-9]*$</code></pre>
<h2 id="entry"><code>entry</code></h2>
<p>An IOCCC entry that won an award for a given IOCCC.</p>
<p>An <code>entry</code> has one or more <code>author</code>s.</p>
<p>Each <code>entry</code> is contained under its own directory. The parent of the entry
directory is the year’s directory.</p>
<p>While in most cases an <code>entry</code> consists of files under an entry’s directory,
there are a few cases where an <code>entry</code> directory contains subdirectories.</p>
<p>Use of subdirectories under an <code>entry</code> directory is discouraged and
may be limited to previous <code>entry</code>s that used them.</p>
<p>NOTE: In the past, the term <code>winner</code> was used in instead of today’s term of
<code>entry</code>.</p>
<h2 id="year"><code>year</code></h2>
<p>A <code>year</code> is a 4 character string. Most years are 4-digit strings that
represent the year. Some special <code>year</code> strings are possible, such as <code>mock</code>.
Non-numeric <code>year</code> strings are lower case.</p>
<p>A <code>year</code> string matches this regexp:</p>
<pre><code> [0-9a-z][0-9a-z][0-9a-z][0-9a-z]</code></pre>
<p>The <code>year</code> directories reside directly below the top level directory.</p>
<div id="dot-year">
<h2 id="year-1"><code>.year</code></h2>
</div>
<p>Each <code>year</code> directory will have a file under it named <code>.year</code>.</p>
<p>The contents of the <code>.year</code> file is the year string of the directory. For
instance, <a href="https://github.com/ioccc-src/temp-test-ioccc/blob/master/2020/.year">2020/.year</a> lists, one directory per line,
the directories of the winning entries of that year. For instance, for 2020:</p>
<pre class="&lt;!--sh--&gt;"><code> $ cat 2020/.year
2020/burton
2020/carlini
2020/endoh1
2020/endoh2
2020/endoh3
2020/ferguson1
2020/ferguson2
2020/giles
2020/kurdyukov1
2020/kurdyukov2
2020/kurdyukov3
2020/kurdyukov4
2020/otterness
2020/tsoj
2020/yang</code></pre>
<h2 id="dir"><code>dir</code></h2>
<p>A <code>dir</code> is a POSIX safe string that holds an entry.</p>
<p>A <code>dir</code> is a string that matches this regexp:</p>
<pre><code> ^[a-z][0-9a-z.-]*$</code></pre>
<p>Each <code>entry</code> is under its own individual directory. This directory
is directly under a <code>year</code> directory.</p>
<div id="entry-id">
<h3 id="entry_id"><code>entry_id</code></h3>
</div>
<p>A string that identifies the winning entry. The string is of the form:</p>
<pre><code> year_dir</code></pre>
<!--
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/
-->
<!-- AFTER: last line of markdown file: bin/README.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"><h3>Copyright &copy; 1984-2024 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%2Fioccc-src.github.io%2Ftemp-test-ioccc%2Fbin%2Findex.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 -->