Fix `bin/gen_top_html` to generate the proper Nu HTML check URLs. Changed `bin/gen_top_html` VERSION from "1.3 2024-04-14" to "1.4 2024-04-15". Remove improper "xmlns:cc="http://creativecommons.org/ns#" from `inc/inc/footer.default.html`. Run `make gen_top_html` to perform the above and test under macOS. TODO: If this is successful, rebuild all other constructed HTML files.
699 lines
40 KiB
HTML
699 lines
40 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">
|
||
<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 web site">
|
||
<meta name="keywords" content="IOCCC, tools, web site 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/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/topnav.default.html -->
|
||
|
||
<div class="topnav">
|
||
|
||
</div>
|
||
|
||
<!-- END: this line ends content from: inc/topnav.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>
|
||
<a href="../location.html">Location of authors</a>
|
||
</div>
|
||
<hr>
|
||
<div class="sidenav">
|
||
<a href="../news.html">IOCCC News</a>
|
||
<a href="../status.html">Contest status</a>
|
||
<a href="../next/index.html">Rules and Guidelines</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 <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 web site</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>
|
||
<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>
|
||
<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>
|
||
<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>
|
||
<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>
|
||
<p>We recommend that this tool be invoked via the top level <code>Makefile</code>:</p>
|
||
<pre><code>make verify_entry_files</code></pre>
|
||
<h3 id="chk-entry.sh"><a href="chk-entry.sh">chk-entry.sh</a></h3>
|
||
<p>Check that files required by an entry match the entry’s manifest as found in
|
||
<code>.entry.json</code>.</p>
|
||
<p>For example:</p>
|
||
<pre><code>bin/chk-entry.sh 2020/ferguson1</code></pre>
|
||
<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>
|
||
<pre><code>awk -f bin/filelist.entry.json.awk 2020/ferguson1/.entry.json</code></pre>
|
||
<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>
|
||
<pre><code>bin/gen-authors.sh -v 1</code></pre>
|
||
<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>
|
||
<pre><code>bin/gen-location.sh -v 1</code></pre>
|
||
<h3 id="gen-other-html.sh"><a href="gen-other-html.sh">gen-other-html.sh</a></h3>
|
||
<p>Generate entry HTML files (other than README.md to index.html) from markdown
|
||
files.</p>
|
||
<p>Usage:</p>
|
||
<pre><code>bin/gen-other-html.sh -v 1</code></pre>
|
||
<h3 id="gen-sitemap.sh"><a href="gen-sitemap.sh">gen-sitemap.sh</a></h3>
|
||
<p>Generate an XML sitemap for the IOCCC web site.</p>
|
||
<p>Usage:</p>
|
||
<pre><code>bin/gen-sitemap.sh -v 1</code></pre>
|
||
<p>We recommend that this tool be invoked via the top level <code>Makefile</code>:</p>
|
||
<pre><code>make gen_sitemap</code></pre>
|
||
<h3 id="gen-status.sh"><a href="gen-status.sh">gen-status.sh</a></h3>
|
||
<p>Generate <code>status.json</code> according to the modification dates of <code>status.json</code>
|
||
and <code>news.html</code>.</p>
|
||
<p>Without 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>:</p>
|
||
<pre><code>make gen_status</code></pre>
|
||
<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>
|
||
<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="../thanks-for-help.html">thanks-for-help.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>:</p>
|
||
<pre><code>make gen_top_html</code></pre>
|
||
<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>
|
||
<pre><code>bin/gen-year-index.sh -v 1 2020</code></pre>
|
||
<p>We recommend that this tool be invoked via the top level <code>Makefile</code>:</p>
|
||
<pre><code>make gen_year_index</code></pre>
|
||
<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>
|
||
<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>:</p>
|
||
<pre><code>make gen_years</code></pre>
|
||
<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/index.html">inc directory</a>.</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 or authors’ related HTML details 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>Builds 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>index.html</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>index.html</code> of a few entries has 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>
|
||
<pre><code>bin/all-run.sh -v 3 bin/quick-readme2index.sh -v 1</code></pre>
|
||
<p><strong>NOTE</strong>: This command assumes that the relative
|
||
modification times for <code>index.hmtl</code>, <code>.entry.json</code>,
|
||
and <code>index.html</code> are correct. If in doubt, use:</p>
|
||
<p>We recommend that this tool be invoked via the top level <code>Makefile</code>:</p>
|
||
<pre><code>make quick_entry_index</code></pre>
|
||
<h3 id="readme2index.sh"><a href="readme2index.sh">readme2index.sh</a></h3>
|
||
<p>Convert an entry README.md into entry directory index.html.</p>
|
||
<pre><code>bin/all-run.sh -v 3 bin/readme2index.sh -v 1</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>:</p>
|
||
<pre><code>make entry_index</code></pre>
|
||
<h3 id="status2html.sh"><a href="status2html.sh">status2html.sh</a></h3>
|
||
<p>Convert <code>status.json</code> into HTML.</p>
|
||
<p>This tool is a ‘before tool’ (-b tool) that is intended
|
||
to be used by <code>bin/gen-status.sh</code>.</p>
|
||
<h3 id="sgi.sh"><a href="sgi.sh">sgi.sh</a></h3>
|
||
<p>Sort .gitignore 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="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>
|
||
<pre><code>bin/sort.gitignore.sh -v 1 YYYY/dir</code></pre>
|
||
<p>Suggested usage:</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>:</p>
|
||
<pre><code>make sort_gitignore</code></pre>
|
||
<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 an 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 an 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 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>
|
||
<h2 id="tar-year.sh"><a href="tar-year.sh">tar-year.sh</a></h2>
|
||
<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>:</p>
|
||
<pre><code>make form_year_tarball</code></pre>
|
||
<h2 id="untar-entry.sh"><a href="untar-entry.sh">untar-entry.sh</a></h2>
|
||
<p>Untar an entry’s a 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>:</p>
|
||
<pre><code>make untar_entry_tarball</code></pre>
|
||
<h2 id="untar-year.sh"><a href="untar-year.sh">untar-year.sh</a></h2>
|
||
<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>:</p>
|
||
<pre><code>make untar_year_tarball</code></pre>
|
||
<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/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 topnav=up2index</code></pre>
|
||
<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 <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>
|
||
<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 <code>%%TOKEN%%</code> are substituted.</p>
|
||
<p>Any <code>%%TOKEN%%</code> printed by the ‘before tool’ (<code>-b tool</code>), the ‘pandoc wrapper
|
||
tool’ (<code>-p tool</code>), and the ‘after tool’ (<code>-a tool</code>) 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><code>getopt</code> phase processing of the command line</h2>
|
||
<p>The command options are evaluated in the following <code>getopt</code> phases:</p>
|
||
<h3 id="getopt-phase-0"><code>getopt</code> phase 0</h3>
|
||
<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>
|
||
<h3 id="getopt-phase-1"><code>getopt</code> phase 1</h3>
|
||
<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>
|
||
<h3 id="getopt-phase-2"><code>getopt</code> phase 2</h3>
|
||
<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>
|
||
<h3 id="getopt-phase-3"><code>getopt</code> phase 3</h3>
|
||
<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>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 options printed by an “output tool” are processed
|
||
after all command line options, and all options from a matching
|
||
line from the <code>md2html.cfg</code> 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 NOT output any <code>-o tool</code> options as <code>-o tool</code> is NOT
|
||
RECURSIVE. 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>
|
||
<h3 id="special--e-exitcode-option">Special <code>-E exitcode</code> option</h3>
|
||
<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="../inc/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="/2020/ferguson1/chocolate-cake.md">2020/ferguson1/chocolate-cake.md</a>,
|
||
a different <code>topnav</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="../inc/md2html.cfg">md2html config file</a>
|
||
that refers to
|
||
<a href="/2020/ferguson1/chocolate-cake.md">2020/ferguson1/chocolate-cake.md</a> may
|
||
specify use of <code>topnav.up2index.html</code> (as <code>topnav.up2index</code>)instead of using the
|
||
<code>topnav.default.html</code> (<code>topnav.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="../inc/md2html.cfg">md2html config file</a> 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/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="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>
|
||
<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 a “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 (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 <a href="../ioccc.css">ioccc.css</a> 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>
|
||
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>
|
||
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 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. In that case we might use the word
|
||
<code>authors</code>.</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 <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/anon.c">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 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 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>
|
||
<h2 id="year-1"><code>.year</code></h2>
|
||
<p>Each <code>year</code> directory will have a file 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><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>
|
||
<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>
|
||
<!--
|
||
|
||
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/
|
||
|
||
-->
|
||
|
||
<!-- 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 -->
|
||
|
||
<!--
|
||
|
||
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">
|
||
<h2><a name="copyright"></a>Copyright and CC BY-SA 4.0 License</h2>
|
||
<p>All IOCCC content including this file and web page are:</p>
|
||
<b> Copyright © 1984-2024 by Landon Curt Noll. <a href="https://creativecommons.org/faq/#what-does-some-rights-reserved-mean">Some Rights Reserved</a>.</b>
|
||
<p>This work is licensed by Landon Curt Noll under:</p>
|
||
<p><b><a href="https://creativecommons.org/licenses/by-sa/4.0/?ref=chooser-v1"
|
||
target="_blank" rel="license noopener noreferrer" style="display:inline-block;"> CC BY-SA 4.0
|
||
<img style="height:22px!important;margin-left:3px;vertical-align:text-bottom;"
|
||
src="../png/cc.png"
|
||
alt="cc inside circle symbol">
|
||
<img style="height:22px!important;margin-left:3px;vertical-align:text-bottom;"
|
||
src="../png/by.png"
|
||
alt="person inside circle symbol">
|
||
<img style="height:22px!important;margin-left:3px;vertical-align:text-bottom;"
|
||
src="../png/sa.png"
|
||
alt="arrow looping back on itself inside circle symbol">
|
||
</a></b></p>
|
||
<p>The <b>CC BY-SA 4.0 LEGAL CODE</b> for this license is found under:</p>
|
||
<p> <b><a href="https://creativecommons.org/licenses/by-sa/4.0/legalcode.en">
|
||
https://creativecommons.org/licenses/by-sa/4.0/legalcode.en</a></b></p>
|
||
<p>You should <b>carefully review</b> all of the terms and conditions of the
|
||
<a href="https://creativecommons.org/licenses/by-sa/4.0/legalcode.en">actual license</a>
|
||
before using the licensed material.</p>
|
||
<p>You may wish to review the <b><a href="../license.html">highlights of some of the key
|
||
features and terms</a></b> of the <a href="https://creativecommons.org/licenses/by-sa/4.0/legalcode.en">actual license</a>.</p>
|
||
<h2>Coda</h2>
|
||
<p><a href="https://validator.w3.org/nu/?doc=https%3A%2F%2Fioccc-src.github.io%2Ftemp-test-ioccc%2Fbin%2Findex.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 -->
|