Fixed the alignment of an arrow in `markdown.md`. Fixed an HTML error, caught by `make quick_www`, in `bin/README.md`.
1162 lines
58 KiB
HTML
1162 lines
58 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="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">✓</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='IOCCC entry locations' -H navbar=top-of-site</code></pre>
|
||
<p>The “output tool” would output the following 4 lines:</p>
|
||
<pre><code> -s
|
||
TITLE='IOCCC entry locations'
|
||
-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><object></code> element</h2>
|
||
<p>The <code><object></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><embed></code> element</h2>
|
||
<p>The <code><embed></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><iframe></code> element</h2>
|
||
<p>The <code><iframe></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._+-]*$"</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="<!--sh-->"><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 © 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 -->
|