We rename `bin/gen-top-md2html.sh` to `bin/gen-top-html.sh`. Modified the `bin/gen-top-html.sh` tool to build `archive/historic/index.html` from `archive/historic/README.md`. In `bin/gen-top-html.sh` changed VERSION from "1.1 2024-02-28" to "1.2 2024-02-29". Renamed `make gen_top_md2html` to `gen_top_html` in the top level `Makefile`. Improved `archive/historic/README.md`. Updated `robots.txt` to include the Sitemap directive. Moved unused `valid-html401.png` to `png/valid-html401.png`. This png image may be used later. Performed `make gen_top_html` which rebuilt all top level HTML files as well as `bin/index.html` and `inc/index.html`.
677 lines
37 KiB
HTML
677 lines
37 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 -->
|
||
<!-- -->
|
||
<!-- !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -->
|
||
<!-- !!! 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/top.default.html -->
|
||
<!-- -->
|
||
<!-- The original markdown content was formed by the tool: bin/gen-top-html.sh -->
|
||
<!-- The HTML was converted from markdown by the tool: bin/md2html.sh -->
|
||
<!-- -->
|
||
<!-- START: this line starts content from: inc/head.default.html -->
|
||
|
||
<head>
|
||
<link rel="stylesheet" href="../ioccc.css">
|
||
<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>
|
||
<meta name="description" content="Tools used to build and maintain the IOCCC web site">
|
||
<meta name="keywords" content="IOCCC, tools, web site tools, bin">
|
||
</head>
|
||
|
||
<!-- END: this line ends content from: inc/head.default.html -->
|
||
<!-- 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/header.default.html -->
|
||
|
||
<div class="header">
|
||
<img src="../png/ioccc.png" alt="IOCCC image by Matt Zucker" width=300 height=110>
|
||
<h1>The International Obfuscated C Code Contest</h1>
|
||
<h2>IOCCC tools used build and maintain the IOCCC web site</h2>
|
||
</div>
|
||
|
||
<!-- END: this line ends content from: inc/header.default.html -->
|
||
<!-- START: this line starts content from: inc/begin-row.default.html -->
|
||
|
||
<div class="row">
|
||
|
||
<!-- END: this line ends content from: inc/begin-row.default.html -->
|
||
<!-- START: this line starts content from: inc/begin-leftcolumn.default.html -->
|
||
|
||
<div class="leftcolumn">
|
||
|
||
<!-- END: this line ends content from: inc/begin-leftcolumn.default.html -->
|
||
<!-- START: this line starts content from: inc/sidenav.default.html -->
|
||
|
||
<div class="sidenav">
|
||
<a href="#content">Jump to contents</a>
|
||
</div>
|
||
<hr>
|
||
<div class="sidenav">
|
||
<a href="../index.html">IOCCC Home</a>
|
||
<a href="../years.html">Winning Entries</a>
|
||
<a href="../authors.html">People who have won</a>
|
||
</div>
|
||
<hr>
|
||
<div class="sidenav">
|
||
<a href="../news.html">IOCCC News</a>
|
||
<a href="../faq.html#submit">How to enter the IOCCC</a>
|
||
<a href="../faq.html">FAQ</a>
|
||
</div>
|
||
<hr>
|
||
<div class="sidenav">
|
||
<a href="../bugs.html">Bugs & (mis)features</a>
|
||
<a href="../faq.html#fix_an_entry">Fixing IOCCC entries</a>
|
||
<a href="../faq.html#fix_web_site">Fixing the web site</a>
|
||
<a href="../faq.html#fix_author">Fixing author info</a>
|
||
<a href="../thanks-for-help.html">Thanks for the help</a>
|
||
</div>
|
||
<hr>
|
||
<div class="sidenav">
|
||
<a href="../judges.html">The IOCCC Judges</a>
|
||
<a href="../contact.html">Contacting the IOCCC</a>
|
||
</div>
|
||
<hr>
|
||
<div class="sidenav">
|
||
<a href="#top">Jump to top</a>
|
||
</div>
|
||
|
||
<!-- END: this line ends content from: inc/sidenav.default.html -->
|
||
<!-- START: this line starts content from: inc/end-leftcolumn.default.html -->
|
||
|
||
</div>
|
||
|
||
<!-- END: this line ends content from: inc/end-leftcolumn.default.html -->
|
||
<!-- START: this line starts content from: inc/begin-rightcolumn.default.html -->
|
||
|
||
<div class="rightcolumn">
|
||
|
||
<!-- END: this line ends content from: inc/begin-rightcolumn.default.html -->
|
||
<!-- START: this line starts content from: inc/before-content.default.html -->
|
||
|
||
<a name="content"></a>
|
||
|
||
<!-- 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 -->
|
||
|
||
<h1 id="bin">bin</h1>
|
||
<p>The directory holds <a href="README.md">bin</a> directory holds tools
|
||
that build files, such as HTML content, for the <a
|
||
href="https://www.ioccc.org">official IOCCC web site</a>.</p>
|
||
<p>For HTML content, the <a href="README.md">bin</a> directory tools
|
||
makes use of HTML fragments from the <a href="../inc/README.md">inc</a>
|
||
directory 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">bin tools</h2>
|
||
<h3 id="all-run.sh"><a href="all-run.sh">all-run.sh</a></h3>
|
||
<p>Run a command on all winning entries.</p>
|
||
<p>For example:</p>
|
||
<div class="sourceCode" id="cb1"><pre class="sourceCode sh"><code class="sourceCode bash"><span id="cb1-1"><a href="#cb1-1" aria-hidden="true" tabindex="-1"></a><span class="ex">bin/all-run.sh</span> <span class="at">-v</span> 3 bin/quick-readme2index.sh <span class="at">-v</span> 1</span></code></pre></div>
|
||
<p>Or for example:</p>
|
||
<div class="sourceCode" id="cb2"><pre class="sourceCode sh"><code class="sourceCode bash"><span id="cb2-1"><a href="#cb2-1" aria-hidden="true" tabindex="-1"></a><span class="ex">bin/all-run.sh</span> <span class="at">-v</span> 3 bin/readme2index.sh <span class="at">-v</span> 1</span></code></pre></div>
|
||
<h3 id="all-years.sh"><a href="all-years.sh">all-years.sh</a></h3>
|
||
<p>Run a command on all IOCCC years.</p>
|
||
<p>For example:</p>
|
||
<div class="sourceCode" id="cb3"><pre class="sourceCode sh"><code class="sourceCode bash"><span id="cb3-1"><a href="#cb3-1" aria-hidden="true" tabindex="-1"></a><span class="ex">bin/all-years.sh</span> <span class="at">-v</span> 1 bin/gen-year-index.sh <span class="at">-v</span> 1</span></code></pre></div>
|
||
<p>Or for example:</p>
|
||
<div class="sourceCode" id="cb4"><pre class="sourceCode sh"><code class="sourceCode bash"><span id="cb4-1"><a href="#cb4-1" aria-hidden="true" tabindex="-1"></a><span class="ex">bin/all-years.sh</span> <span class="at">-v</span> 1 bin/chk-entry.sh</span></code></pre></div>
|
||
<h3 id="chk-entry.sh"><a href="chk-entry.sh">chk-entry.sh</a></h3>
|
||
<p>Check of files required by an entry matches the entry’s manifest as
|
||
found in <code>.entry.json</code>.</p>
|
||
<p>For example:</p>
|
||
<div class="sourceCode" id="cb5"><pre class="sourceCode sh"><code class="sourceCode bash"><span id="cb5-1"><a href="#cb5-1" aria-hidden="true" tabindex="-1"></a><span class="ex">bin/chk-entry.sh</span> 2020/ferguson1</span></code></pre></div>
|
||
<h3 id="filelist.entry.json.awk"><a
|
||
href="filelist.entry.json.awk">filelist.entry.json.awk</a></h3>
|
||
<p>Generate the list of files in the entry’s manifest
|
||
<code>.entry.json</code>.</p>
|
||
<p>For example:</p>
|
||
<div class="sourceCode" id="cb6"><pre class="sourceCode sh"><code class="sourceCode bash"><span id="cb6-1"><a href="#cb6-1" aria-hidden="true" tabindex="-1"></a><span class="fu">awk</span> <span class="at">-f</span> bin/filelist.entry.json.awk 2020/ferguson1/.entry.json</span></code></pre></div>
|
||
<h3 id="gen-authors.sh"><a href="gen-authors.sh">gen-authors.sh</a></h3>
|
||
<p>Generate the top level <code>/authors.html</code> page.</p>
|
||
<p>Usage:</p>
|
||
<div class="sourceCode" id="cb7"><pre class="sourceCode sh"><code class="sourceCode bash"><span id="cb7-1"><a href="#cb7-1" aria-hidden="true" tabindex="-1"></a><span class="ex">bin/gen-authors.sh</span> <span class="at">-v</span> 1</span></code></pre></div>
|
||
<h3 id="gen-location.sh"><a
|
||
href="gen-location.sh">gen-location.sh</a></h3>
|
||
<p>Generate the top level <code>/location.html</code> page.</p>
|
||
<p>Usage:</p>
|
||
<div class="sourceCode" id="cb8"><pre class="sourceCode sh"><code class="sourceCode bash"><span id="cb8-1"><a href="#cb8-1" aria-hidden="true" tabindex="-1"></a><span class="ex">bin/gen-location.sh</span> <span class="at">-v</span> 1</span></code></pre></div>
|
||
<h3 id="gen-other-html.sh"><a
|
||
href="gen-other-html.sh">gen-other-html.sh</a></h3>
|
||
<p>Generate entry HTML files from markdown other than README.md to
|
||
index.html HTML files.</p>
|
||
<p>Usage:</p>
|
||
<div class="sourceCode" id="cb9"><pre class="sourceCode sh"><code class="sourceCode bash"><span id="cb9-1"><a href="#cb9-1" aria-hidden="true" tabindex="-1"></a><span class="ex">bin/gen-other-html.sh</span> <span class="at">-v</span> 1</span></code></pre></div>
|
||
<h3 id="gen-top-html.sh"><a
|
||
href="gen-top-html.sh">gen-top-html.sh</a></h3>
|
||
<p>Generate a number of top level HTML pages for the IOCCC web
|
||
sites.</p>
|
||
<p>Usage:</p>
|
||
<div class="sourceCode" id="cb10"><pre
|
||
class="sourceCode sh"><code class="sourceCode bash"><span id="cb10-1"><a href="#cb10-1" aria-hidden="true" tabindex="-1"></a><span class="ex">bin/gen-top-html.sh</span> <span class="at">-v</span> 1</span></code></pre></div>
|
||
<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="README.html">README.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="thanks-for-help.html">thanks-for-help.html</a></li>
|
||
</ul>
|
||
<h3 id="gen-year-index.sh"><a
|
||
href="gen-year-index.sh">gen-year-index.sh</a></h3>
|
||
<p>Generate an <code>index.html</code> page for an given IOCCC year.</p>
|
||
<p>Usage:</p>
|
||
<div class="sourceCode" id="cb11"><pre
|
||
class="sourceCode sh"><code class="sourceCode bash"><span id="cb11-1"><a href="#cb11-1" aria-hidden="true" tabindex="-1"></a><span class="ex">bin/gen-year-index.sh</span> <span class="at">-v</span> 1 2020</span></code></pre></div>
|
||
<h3 id="gen-years.sh"><a href="gen-years.sh">gen-years.sh</a></h3>
|
||
<p>Generate the top level <code>/years.html</code> page.</p>
|
||
<p>Usage:</p>
|
||
<div class="sourceCode" id="cb12"><pre
|
||
class="sourceCode sh"><code class="sourceCode bash"><span id="cb12-1"><a href="#cb12-1" aria-hidden="true" tabindex="-1"></a><span class="ex">bin/gen-years.sh</span> <span class="at">-v</span> 1</span></code></pre></div>
|
||
<h3 id="ioccc-status.sh"><a href="ioccc-status">ioccc-status.sh</a></h3>
|
||
<p>Updates the <a href="/status.json">status.json</a> file.</p>
|
||
<h3 id="manifest.entry.json.awk"><a
|
||
href="manifest.entry.json.awk">manifest.entry.json.awk</a></h3>
|
||
<p>Output manifest table from a entry .entry.json file.</p>
|
||
<h3 id="md2html.sh"><a href="md2html.sh">md2html.sh</a></h3>
|
||
<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">inc</a>
|
||
directory.</p>
|
||
<p>The <a href="../inc/md2html.cfg">../inc/md2html.cfg</a> configuration
|
||
file is used by <a href="md2html.sh">md2html.sh</a> to drive the
|
||
generation process.</p>
|
||
<h3 id="output-index-author.sh"><a
|
||
href="output-index-author.sh">output-index-author.sh</a></h3>
|
||
<p>Output author(s) Related HTML for for an entry’s index.html page.</p>
|
||
<h3 id="output-index-inventory.sh"><a
|
||
href="output-index-inventory.sh">output-index-inventory.sh</a></h3>
|
||
<p>Output the inventory in HTML form for an entry’s index.html page.</p>
|
||
<h3 id="output-year-index.sh"><a
|
||
href="output-year-index.sh">output-year-index.sh</a></h3>
|
||
<p>Output markdown of wining entry links for a given year.</p>
|
||
<h3 id="pandoc-wrapper.sh"><a
|
||
href="pandoc-wrapper.sh">pandoc-wrapper.sh</a></h3>
|
||
<p>Wrapper tool to run pandoc.</p>
|
||
<h3 id="quick-readme2index.sh"><a
|
||
href="quick-readme2index.sh">quick-readme2index.sh</a></h3>
|
||
<p>Runs <a href="readme2index.sh">readme2index.sh</a> 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.</p>
|
||
<p>While the <a href="readme2index.sh">readme2index.sh</a> take a few
|
||
seconds to run, 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 slightly longer <a
|
||
href="readme2index.sh">readme2index.sh</a> is run:</p>
|
||
<div class="sourceCode" id="cb13"><pre
|
||
class="sourceCode sh"><code class="sourceCode bash"><span id="cb13-1"><a href="#cb13-1" aria-hidden="true" tabindex="-1"></a><span class="ex">bin/all-run.sh</span> <span class="at">-v</span> 3 bin/quick-readme2index.sh <span class="at">-v</span> 1</span></code></pre></div>
|
||
<p><strong>NOTE</strong>: This command assumes that the relative
|
||
modification times for <code>index.hmtl</code>,
|
||
.entry.json<code>, and</code>README.md` are correct. If in doubt,
|
||
use:</p>
|
||
<div class="sourceCode" id="cb14"><pre
|
||
class="sourceCode sh"><code class="sourceCode bash"><span id="cb14-1"><a href="#cb14-1" aria-hidden="true" tabindex="-1"></a><span class="ex">bin/all-run.sh</span> <span class="at">-v</span> 3 bin/readme2index.sh <span class="at">-v</span> 1</span></code></pre></div>
|
||
<h3 id="readme2index.sh"><a
|
||
href="readme2index.sh">readme2index.sh</a></h3>
|
||
<p>Convert a entry README.md into entry directory index.html.</p>
|
||
<h3 id="sgi.sh"><a href="sgi.sh">sgi.sh</a></h3>
|
||
<p>Sort .gitignore content from stdin to stdout.</p>
|
||
<p>We sort with lines starting with # first. We sort with lines starting
|
||
with * second. We sort with lines that do not start with [#!*] third. We
|
||
sort with lines starting with ! fourth.</p>
|
||
<p>This tool is used by <a
|
||
href="sort.gitignore.sh">sort.gitignore.sh</a>.</p>
|
||
<h3 id="sort.gitignore.sh"><a
|
||
href="sort.gitignore.sh">sort.gitignore.sh</a></h3>
|
||
<p>Sort a .gitignore in a entry directory.</p>
|
||
<p>Usage:</p>
|
||
<div class="sourceCode" id="cb15"><pre
|
||
class="sourceCode sh"><code class="sourceCode bash"><span id="cb15-1"><a href="#cb15-1" aria-hidden="true" tabindex="-1"></a><span class="ex">bin/sort.gitignore.sh</span> <span class="at">-v</span> 1 YYYY/dir</span></code></pre></div>
|
||
<p>Suggested usage:</p>
|
||
<div class="sourceCode" id="cb16"><pre
|
||
class="sourceCode sh"><code class="sourceCode bash"><span id="cb16-1"><a href="#cb16-1" aria-hidden="true" tabindex="-1"></a><span class="ex">bin/all-run.sh</span> bin/sort.gitignore.sh <span class="at">-v</span> 1</span></code></pre></div>
|
||
<h3 id="subst.default.sh"><a
|
||
href="subst.default.sh">subst.default.sh</a></h3>
|
||
<p>Print default substitutions.</p>
|
||
<h3 id="subst.entry-index.sh"><a
|
||
href="subst.entry-index.sh">subst.entry-index.sh</a></h3>
|
||
<p>Print substitutions for a entry index.html.</p>
|
||
<h3 id="subst.entry-navbar.awk"><a
|
||
href="subst.entry-navbar.awk">subst.entry-navbar.awk</a></h3>
|
||
<p>Output substitutions for navbar on behalf of a entry.</p>
|
||
<h3 id="subst.year-index.sh"><a
|
||
href="subst.year-index.sh">subst.year-index.sh</a></h3>
|
||
<p>Print substitutions for a year level index.html.</p>
|
||
<h3 id="subst.year-navbar.awk"><a
|
||
href="subst.year-navbar.awk">subst.year-navbar.awk</a></h3>
|
||
<p>Output substitutions for navbar on behalf of a year level
|
||
index.html.</p>
|
||
<h2 id="tar-entry.sh"><a href="tar-entry.sh">tar-entry.sh</a></h2>
|
||
<p>Form a compress tarball for an entry.</p>
|
||
<p>Usage:</p>
|
||
<div class="sourceCode" id="cb17"><pre
|
||
class="sourceCode sh"><code class="sourceCode bash"><span id="cb17-1"><a href="#cb17-1" aria-hidden="true" tabindex="-1"></a><span class="ex">bin/tar-entry.sh</span> <span class="at">-v</span> 1 YYYY/dir</span></code></pre></div>
|
||
<p>Suggested usage:</p>
|
||
<div class="sourceCode" id="cb18"><pre
|
||
class="sourceCode sh"><code class="sourceCode bash"><span id="cb18-1"><a href="#cb18-1" aria-hidden="true" tabindex="-1"></a><span class="ex">bin/all-run.sh</span> <span class="at">-v</span> 3 bin/tar-entry.sh <span class="at">-v</span> 1 <span class="at">-W</span></span></code></pre></div>
|
||
<h2 id="tar-all.sh"><a href="tar-all.sh">tar-all.sh</a></h2>
|
||
<p>Form the compressed tarball for all IOCCC years and all IOCCC
|
||
entries.</p>
|
||
<p>Usage:</p>
|
||
<div class="sourceCode" id="cb19"><pre
|
||
class="sourceCode sh"><code class="sourceCode bash"><span id="cb19-1"><a href="#cb19-1" aria-hidden="true" tabindex="-1"></a><span class="ex">bin/tar-all.sh</span> <span class="at">-v</span> 1</span></code></pre></div>
|
||
<h2 id="tar-year.sh"><a href="tar-year.sh">tar-year.sh</a></h2>
|
||
<p>Form a compress tarball for an IOCCC year.</p>
|
||
<p>Usage:</p>
|
||
<div class="sourceCode" id="cb20"><pre
|
||
class="sourceCode sh"><code class="sourceCode bash"><span id="cb20-1"><a href="#cb20-1" aria-hidden="true" tabindex="-1"></a><span class="ex">bin/tar-year.sh</span> <span class="at">-v</span> 1 YYYY</span></code></pre></div>
|
||
<p>Suggested usage:</p>
|
||
<div class="sourceCode" id="cb21"><pre
|
||
class="sourceCode sh"><code class="sourceCode bash"><span id="cb21-1"><a href="#cb21-1" aria-hidden="true" tabindex="-1"></a><span class="ex">bin/all-years.sh</span> <span class="at">-v</span> 3 bin/tar-year.sh <span class="at">-v</span> 1 <span class="at">-W</span></span></code></pre></div>
|
||
<h1 id="how-ioccc-html-content-is-built"><a name="how"></a>How IOCCC
|
||
HTML content is built</h1>
|
||
<p>The <a href="md2html.sh">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/README.md">inc</a> directory.</p>
|
||
<p>Most HTML content is built from permanant 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="README.md">bin</a> directory 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/README.md">inc</a> directory, of the form:</p>
|
||
<pre><code>*.default.html</code></pre>
|
||
<p>By using command line options of the form</p>
|
||
<div class="sourceCode" id="cb23"><pre
|
||
class="sourceCode sh"><code class="sourceCode bash"><span id="cb23-1"><a href="#cb23-1" aria-hidden="true" tabindex="-1"></a><span class="ex">-H</span> phase=name</span></code></pre></div>
|
||
<p>where <code>phase</code> is the name of an HTML phase, a non-default
|
||
file may be used. For example:</p>
|
||
<div class="sourceCode" id="cb24"><pre
|
||
class="sourceCode sh"><code class="sourceCode bash"><span id="cb24-1"><a href="#cb24-1" aria-hidden="true" tabindex="-1"></a><span class="ex">-H</span> topnav=up2index</span></code></pre></div>
|
||
<p>will cause <a
|
||
href="../inc/topnav.up2index.html">inc/topnav.up2index.html</a> instead
|
||
of <a href="../inc/topnav.default.html">inc/topnav.default.html</a> to
|
||
be used during the <em>topnav</em> HTML phase.</p>
|
||
<p>If <em>name</em> is dot (i.e., “.”), then the given HTML phase is
|
||
skipped. For example:</p>
|
||
<div class="sourceCode" id="cb25"><pre
|
||
class="sourceCode sh"><code class="sourceCode bash"><span id="cb25-1"><a href="#cb25-1" aria-hidden="true" tabindex="-1"></a><span class="ex">-H</span> footer=.</span></code></pre></div>
|
||
<p>will cause no HTML content to be produced during the <em>footer</em>
|
||
HTML phase.</p>
|
||
<h2 id="html-phases"><a name="html"></a>HTML phases</h2>
|
||
<p>The following HTML phase files are used to build HTML content:</p>
|
||
<ol start="0" type="1">
|
||
<li>inc/top.default.html</li>
|
||
<li>inc/head.default.html</li>
|
||
<li>inc/body.default.html</li>
|
||
<li>inc/header.default.html</li>
|
||
<li>inc/topnav.default.html</li>
|
||
<li>inc/begin-row.default.html</li>
|
||
<li>inc/begin-leftcolumn.default.html</li>
|
||
<li>inc/sidenav.default.html</li>
|
||
<li>inc/end-leftcolumn.default.html</li>
|
||
<li>inc/begin-rightcolumn.default.html</li>
|
||
<li>inc/before-content.default.html</li>
|
||
</ol>
|
||
<p>Phases 11-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>inc/after-content.default.html</li>
|
||
<li>inc/end-rightcolumn.default.html</li>
|
||
<li>inc/end-row.default.html</li>
|
||
<li>inc/footer.default.html</li>
|
||
<li>inc/bottom.default.html</li>
|
||
</ol>
|
||
<p>Phases 35-39 are reserved for future use.</p>
|
||
<p>In the above HTML phase numbers, except during HTML phase numbers
|
||
20-29, symbols of the form %%TOKEN%% are substituted. Any %%TOKEN%%
|
||
printed by the ‘before tool’ (-b tool), the ‘pandoc wrapper tool’ (-p
|
||
tool), and the ‘after tool’ (-a tool) are ignored (i.e., not
|
||
substituted).</p>
|
||
<p>See the tool <a href="readme2index.sh">readme2index.sh</a> for an
|
||
example of how HTML phases are implemented.</p>
|
||
<h2
|
||
id="getopt-phase-processing-of-the-command-line"><a name="getopt"></a>Getopt
|
||
phase processing of the command line</h2>
|
||
<p>The command options are evaluated in the following getopt phases:</p>
|
||
<h3 id="getopt-phase-0">Getopt phase 0</h3>
|
||
<p>In getopt 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>In getopt phase 0 is the only getopt phase where “-d topdir” and “-c
|
||
md2html.cfg” may be used.</p>
|
||
<h3 id="getopt-phase-1">Getopt phase 1</h3>
|
||
<p>In getopt phase 1 we execute each -o “output tool” from getopt phase
|
||
0, parsing the output as a command line.</p>
|
||
<p>The -o “output tool” may be given optstr from “-O tool=optstr”,
|
||
followed by the phase 0 argument.</p>
|
||
<p>The -o “output tool” is not allowed to output another “-o tool”, nor
|
||
a “-O tool=optstr”. Instead an -o “output tool” may execute another -o
|
||
“output tool” merge the output into its own.</p>
|
||
<h3 id="getopt-phase-2">Getopt phase 2</h3>
|
||
<p>In getopt phase 2 we parse the “cfg_options” from the first
|
||
“md2html.cfg” line matched by saved argument.</p>
|
||
<p>The match is made with the (possibly modified) phase 0 argument.</p>
|
||
<h3 id="getopt-phase-3">Getopt phase 3</h3>
|
||
<p>In getopt phase 3 we execute each -o “output tool” from getopt phase
|
||
2, parsing the output as a command line.</p>
|
||
<p>The -o “output tool” may be given optstr from “-O tool=optstr”,
|
||
followed by the phase 0 argument.</p>
|
||
<p>The -o “output tool” is not allowed to output another “-o tool”, nor
|
||
a “-O tool=optstr”. Instead an -o “output tool” may execute another -o
|
||
“output tool” 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 ‘-H phase=name’, later ‘-H phase=name’ only
|
||
overrides an earlier use of ‘-H’ for the same ‘phase’ only. Also in the
|
||
case of ‘-s token=value’, later ‘-s token=value’ only overrides an
|
||
earlier use of ‘-s’ for the same ‘token’ only.</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>IMPORTANT: 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 topnav=top-of-site</code></pre>
|
||
<p>The “output tool” would output the following 4 lines:</p>
|
||
<pre><code>-s
|
||
TITLE='IOCCC entry locations'
|
||
-H
|
||
topnav=top-of-site</code></pre>
|
||
<p>The command line opions printed by an “output tool” are processed
|
||
after all command line options, and all options from a matching line
|
||
from the md2html.cfg file, and before any filename arguments on the
|
||
command line.</p>
|
||
<p>For exmaple:</p>
|
||
<pre><code>command [command_options ..] [cfg_options ..] [output_tool_options ..] [--] [filename_arg ..]</code></pre>
|
||
<p>Here the ‘command’ first processes any command line options, then it
|
||
processes ‘cfg_options’ obtained from this file from a 1st match of a
|
||
given file_glob, then it processes ‘output tool’ (i.e., -o tool) options
|
||
found in ‘command_options’, and ‘cfg_options’, then an optional – (end
|
||
of all options), then zero of more ‘filename_arg’ filename
|
||
arguments.</p>
|
||
<p>The ‘-o tool’ must NOT output any ‘-o tool’ options as ‘-o tool’ is
|
||
NOT RECURSIVE. A ‘-o tool’ is free, however, to execute other ‘-o tool’
|
||
output tools and merge the output from those tools into its own.</p>
|
||
<h3 id="special--e-exitcode-option">Special -E exitcode option</h3>
|
||
<p>When ‘-E exitcode’ is evaluated, the application will exit with the
|
||
‘exitcode’ value. If one wishes to also output a message to stderr, the
|
||
‘-e string’ must come BEFORE any ‘-E exitcode’ in the command line.</p>
|
||
<h3 id="substitution-tokens">Substitution tokens</h3>
|
||
<p>All tokens (i.e., strings of the form ‘%%token%%’) MUST be
|
||
substituted (by some -s token=value) in all HTML output, except during
|
||
phase numbers 20-29 (i.e., except ‘before tool’ output, pandoc wrapper
|
||
output, and except ‘after tool’ output), or command will exit non-zero,
|
||
unless -S is given. If -S is given, only a warning about un-substituted
|
||
tokens will be written to stderr.</p>
|
||
<p>The command line of tools in the <a href="README.md">bin</a>
|
||
directory, and perhaps modified via <a href="../inc/md2html.cfg">md2html
|
||
config file</a> file may change to using a different filename for a
|
||
given phase.</p>
|
||
<p>For example when forming the HTML from
|
||
<code>2020/ferguson2/chocolate-cake.md</code>, a different “topnav”
|
||
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="../inc/md2html.cfg">md2html config file</a> file that refers to
|
||
<code>2020/ferguson1/chocolate-cake.md</code> may specify use of
|
||
<code>topnav.up2index.html</code> instead of using the
|
||
<code>topnav.default.html</code> default.</p>
|
||
<p>The HTML phase may be skipped resulting in no HTML output during a
|
||
given phase. Furthermore, forming HTML content from a given markdown
|
||
file altogether.</p>
|
||
<p>See comments in the <a href="../inc/md2html.cfg">md2html config
|
||
file</a> file for details. See also, the tool <a
|
||
href="readme2index.sh">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
|
||
inc 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 web site</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 web
|
||
site</a>.</p>
|
||
<p>… and in particular files under <a href="../inc/README.md">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="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-do-we-do-not-use-certain-well-known-html-technologies">Why
|
||
do 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="README.md">bin</a>
|
||
directory when there other solutions available to form web pages.</p>
|
||
<h2 id="static-web-pages-only"><a name="static-only"></a>Static web
|
||
pages only</h2>
|
||
<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 web site</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 “#include” 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="#static-only">static web pages</a>, so use of
|
||
“back-end database” is not available to the IOCCC.</p>
|
||
<h2
|
||
id="we-cannot-use-non-github-web-servers"><a name="why-github"></a>We
|
||
cannot use non-GitHub web servers</h2>
|
||
<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 web site</a> is,
|
||
after all, primarily C source code with some supporting documentation.
|
||
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-tag">We cannot use the HTML object
|
||
tag</h2>
|
||
<p>The <em><</em> object <em>></em> HTML tag does not work for our
|
||
needs.</p>
|
||
<p>The browser context relationship between the HTML content holds the
|
||
HTML tag does not extend into the content that the tag includes. For
|
||
example, menu bars will not operate as specified by the <a
|
||
href="../ioccc.css">ioccc CSS</a>.</p>
|
||
<h2 id="we-cannot-use-the-html-embed-tag">We cannot use the HTML embed
|
||
tag</h2>
|
||
<p>The <em><</em> embed <em>></em> HTML tag does not work for our
|
||
needs.</p>
|
||
<p>This tag wants one to specify the <em>width</em> and <em>height</em>
|
||
in pixels. Use of a percentage is not officially supported even if some
|
||
browsers might do so. Our Responsive Web Design on the <a
|
||
href="../ioccc.css">ioccc CSS</a> 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 <em>width</em> and
|
||
<em>height</em> in pixels will not work well in all of those screen size
|
||
contexts.</p>
|
||
<h2 id="we-cannot-use-the-html-iframe-tag">We cannot use the HTML iframe
|
||
tag</h2>
|
||
<p>The <em><</em> iframe <em>></em> HTML tag does not work for our
|
||
needs.</p>
|
||
<p>This tag wants one to specify the <em>width</em> and <em>height</em>
|
||
in pixels. Use of a percentage is not officially supported even if some
|
||
browsers might do so. Our Responsive Web Design on the <a
|
||
href="../ioccc.css">ioccc CSS</a> 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 <em>width</em> and
|
||
<em>height</em> 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 web
|
||
site</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>.</p>
|
||
<p>For this reason, we cannot use JavaScript include HTML content.</p>
|
||
<h1 id="ioccc-terms"><a name="terms"></a>IOCCC terms</h1>
|
||
<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.</p>
|
||
<h2 id="author_handle"><code>author_handle</code></h2>
|
||
<p>An <code>author_handle</code> is string that refers to a given author
|
||
and is unique to the IOCCC. Each author has exactly one
|
||
<code>author_handle</code>.</p>
|
||
<p>For each <code>author_handle</code>, there will be a JSON file of the
|
||
form:</p>
|
||
<pre><code>author/author_handle.json</code></pre>
|
||
<p>Because the <code>author_handle</code> is used to form a JSON
|
||
filename, the string must be lower case POSIX safe string. Furthermore,
|
||
the <code>author_handle</code> must be an ASCII string that matches this
|
||
regexp:</p>
|
||
<pre class="re"><code>^[0-9a-z][0-9a-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/anon.c">2005/anon</a>.</p>
|
||
<p>Anonymous <code>author_handle</code>’s match this regexp:</p>
|
||
<pre class="re"><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 given IOCCC.</p>
|
||
<p>A <code>entry</code> has one more 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 a <code>entry</code> consists of files under a
|
||
entry’s directory, there are a few cases where a <code>entry</code>
|
||
directory contains subdirectories.</p>
|
||
<p>Use of subdirectories under a <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 <em>winner</em> was used in instead of
|
||
today’s term of <em>entry</em>.</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 <em><code>mock</code></em>. Non-numeric
|
||
<code>year</code> strings are lower case.</p>
|
||
<p>A <code>year</code> string matches this regexp:</p>
|
||
<pre class="re"><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>
|
||
<h2 id="year-1"><code>.year</code></h2>
|
||
<p>Each <code>year</code> will have a file directory under it named:</p>
|
||
<pre><code>.year</code></pre>
|
||
<p>The contents of the <code>.year</code> file is the year string of the
|
||
directory. For instance, <a href="/2020/.year">2020/.year</a> has the
|
||
string: <code>2020</code>.</p>
|
||
<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 class="re"><code>^[a-z][0-9a-z.-]*$</code></pre>
|
||
<p>Each
|
||
<code>_entry_ is under its own individual directory. This directory is directly under a</code>year`
|
||
directory.</p>
|
||
<h3 id="entry_id"><code>entry_id</code></h3>
|
||
<p>A string that identifies the winning entry. The string is of the
|
||
form:</p>
|
||
<pre><code>year_dir</code></pre>
|
||
|
||
<!-- 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 -->
|
||
|
||
<!-- END: this line ends content from: inc/after-content.default.html -->
|
||
<!-- START: this line starts content from: inc/end-rightcolumn.default.html -->
|
||
|
||
</div>
|
||
|
||
<!-- END: this line ends content from: inc/end-rightcolumn.default.html -->
|
||
<!-- START: this line starts content from: inc/end-row.default.html -->
|
||
|
||
</div>
|
||
|
||
<!-- END: this line ends content from: inc/end-row.default.html -->
|
||
<!-- START: this line starts content from: inc/footer.default.html -->
|
||
|
||
<div class="footer">
|
||
<hr>
|
||
<h2>Coda</h2>
|
||
<p><a href="https://validator.w3.org/nu/?doc=https%3A%2F%2Fioccc-src.github.io%2Ftemp-test-ioccc%2Flocation.html">Nu HTML check this web page</a></p>
|
||
<p><a href="#top">Jump to top</a> <a href="#content">Jump to Content</a> <a href="#inventory">Jump to Inventory</a></p>
|
||
</div>
|
||
|
||
<!-- END: this line ends content from: inc/footer.default.html -->
|
||
<!-- START: this line starts content from: inc/bottom.default.html -->
|
||
|
||
</body>
|
||
</html>
|
||
|
||
<!-- END: this line ends content from: inc/bottom.default.html -->
|