1688 lines
89 KiB
HTML
1688 lines
89 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">
|
||
Winning authors
|
||
</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 class="outfit-font">
|
||
<a href="../faq.html#fix_an_entry" class="sub-item-link">
|
||
Fixing entries
|
||
</a>
|
||
</div>
|
||
|
||
<div class="outfit-font">
|
||
<a href="../faq.html#fix_author" class="sub-item-link">
|
||
Updating author info
|
||
</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">
|
||
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/rules.html" class="sub-item-link">
|
||
IOCCC rules
|
||
</a>
|
||
</div>
|
||
|
||
<div class="outfit-font">
|
||
<a href="../next/guidelines.html" class="sub-item-link">
|
||
IOCCC guidelines
|
||
</a>
|
||
</div>
|
||
|
||
<div class="outfit-font">
|
||
<a href="../markdown.html" class="sub-item-link">
|
||
Markdown guidelines
|
||
</a>
|
||
</div>
|
||
|
||
<div class="outfit-font">
|
||
<a href="../SECURITY.html" class="sub-item-link">
|
||
Security policy
|
||
</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">
|
||
Frequently asked questions
|
||
</a>
|
||
</div>
|
||
|
||
<div class="outfit-font">
|
||
<a href="../quick-start.html#enter" class="sub-item-link">
|
||
Enter the IOCCC
|
||
</a>
|
||
</div>
|
||
|
||
<div class="outfit-font">
|
||
<a href="../faq.html#compiling" class="sub-item-link">
|
||
Compiling entries
|
||
</a>
|
||
</div>
|
||
|
||
<div class="outfit-font">
|
||
<a href="../faq.html#running_entries" class="sub-item-link">
|
||
Running entries
|
||
</a>
|
||
</div>
|
||
|
||
<div class="outfit-font">
|
||
<a href="../faq.html#help" class="sub-item-link">
|
||
How to help
|
||
</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">
|
||
Home page
|
||
</a>
|
||
</div>
|
||
|
||
<div class="outfit-font">
|
||
<a href="../social.html" class="sub-item-link">
|
||
IOCCC social media
|
||
</a>
|
||
</div>
|
||
|
||
<div class="outfit-font">
|
||
<a href="../about.html" class="sub-item-link">
|
||
About the IOCCC
|
||
</a>
|
||
</div>
|
||
|
||
<div class="outfit-font">
|
||
<a href="../judges.html" class="sub-item-link">
|
||
The judges
|
||
</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="../contact.html" class="sub-item-link">
|
||
Contact us
|
||
</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">
|
||
Winning authors
|
||
</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>
|
||
|
||
<a class="mobile-submenu-item" href="../faq.html#fix_an_entry">
|
||
Fixing entries
|
||
</a>
|
||
|
||
<a class="mobile-submenu-item" href="../faq.html#fix_author">
|
||
Updating author info
|
||
</a>
|
||
|
||
<a class="mobile-submenu-item" href="../thanks-for-help.html">
|
||
Thanks for the help
|
||
</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="../news.html">
|
||
News
|
||
</a>
|
||
|
||
<a class="mobile-submenu-item" href="../status.html">
|
||
Contest status
|
||
</a>
|
||
|
||
<a class="mobile-submenu-item" href="../next/rules.html">
|
||
IOCCC rules
|
||
</a>
|
||
|
||
<a class="mobile-submenu-item" href="../next/guidelines.html">
|
||
IOCCC guidelines
|
||
</a>
|
||
|
||
<a class="mobile-submenu-item" href="../markdown.html">
|
||
Markdown guidelines
|
||
</a>
|
||
|
||
<a class="mobile-submenu-item" href="../SECURITY.html">
|
||
Security policy
|
||
</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="../quick-start.html#enter">
|
||
Enter the IOCCC
|
||
</a>
|
||
|
||
<a class="mobile-submenu-item" href="../faq.html#compiling">
|
||
Compiling entries
|
||
</a>
|
||
|
||
<a class="mobile-submenu-item" href="../faq.html#running_entries">
|
||
Running entries
|
||
</a>
|
||
|
||
<a class="mobile-submenu-item" href="../faq.html#help">
|
||
How to help
|
||
</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">
|
||
Home page
|
||
</a>
|
||
|
||
<a class="mobile-submenu-item" href="../social.html">
|
||
IOCCC social media
|
||
</a>
|
||
|
||
<a class="mobile-submenu-item" href="../about.html">
|
||
About the IOCCC
|
||
</a>
|
||
|
||
<a class="mobile-submenu-item" href="../judges.html">
|
||
The judges
|
||
</a>
|
||
|
||
<a class="mobile-submenu-item" href="../contact.html">
|
||
Contact us
|
||
</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%2Fwww.ioccc.org%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>
|
||
<blockquote>
|
||
<p>“After 50+ years, the UNIX command line remains very powerful.” – Landon Noll</p>
|
||
<p>An answer to (Monty)? Pythonesque question of why these tools
|
||
weren’t written in a certain language. :-)</p>
|
||
</blockquote>
|
||
<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="https://github.com/ioccc-src/winner/blob/master/inc/index.html">inc directory</a> as well as various JSON
|
||
files and other content from the <a href="https://github.com/ioccc-src/winner">official IOCCC winner repo</a>.</p>
|
||
<h2 id="bin-tools-options"><a href="index.html">bin/</a> tools options</h2>
|
||
<p>With the exception of the <code>awk(1)</code> and <code>sed(1)</code> scripts, all the tools in this
|
||
directory support a number of options that can be used to get help, diagnose
|
||
problems, see progress etc. These options are described below.</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 (of the repo/website), 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 you want verbosity, say for debugging purposes or to see what is going on
|
||
more (than the default), 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/winner/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-about-some-of-the-common-options">Other notes about some of the common options</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/winner/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-jfmt">
|
||
<h3 id="all-jfmt.sh"><a href="https://github.com/ioccc-src/winner/blob/master/bin/all-jfmt.sh">all-jfmt.sh</a></h3>
|
||
</div>
|
||
<p>Canonically format all entry and author JSON files</p>
|
||
<p>Usage:</p>
|
||
<pre><code> bin/all-jfmt.sh -v 3</code></pre>
|
||
<p>Alternate usage:</p>
|
||
<pre><code> make all_jfmt</code></pre>
|
||
<div id="all-years">
|
||
<h3 id="all-years.sh"><a href="https://github.com/ioccc-src/winner/blob/master/bin/all-years.sh">all-years.sh</a></h3>
|
||
</div>
|
||
<p>Run a command on all IOCCC years.</p>
|
||
<p>Usage:</p>
|
||
<pre><code> bin/all-years.sh -v 1 bin/gen-year-index.sh -v 1</code></pre>
|
||
<p>If you wish to run instead, for example, <a href="#chk-entry">chk-entry.sh</a>, then do:</p>
|
||
<pre><code> bin/all-years.sh -v 1 bin/chk-entry.sh</code></pre>
|
||
<div id="all-run">
|
||
<h3 id="all-run.sh"><a href="https://github.com/ioccc-src/winner/blob/master/bin/all-run.sh">all-run.sh</a></h3>
|
||
</div>
|
||
<p>Run a command on all winning entries.</p>
|
||
<p>Usage:</p>
|
||
<pre><code> bin/all-run.sh -v 3 bin/quick-readme2index.sh -v 1</code></pre>
|
||
<p>If you wish to run instead, for example, <a href="#readme2index">readme2index.sh</a>, then
|
||
do:</p>
|
||
<pre><code> bin/all-run.sh -v 3 bin/readme2index.sh -v 1</code></pre>
|
||
<div id="chk-entry">
|
||
<h3 id="chk-entry.sh"><a href="https://github.com/ioccc-src/winner/blob/master/bin/chk-entry.sh">chk-entry.sh</a></h3>
|
||
</div>
|
||
<p>Check an entry directory to verify that all the files in its manifest
|
||
(<code>.entry.json</code>) exist in the git repo.</p>
|
||
<p>Usage:</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>:</p>
|
||
<pre><code> make verify_entry_files</code></pre>
|
||
<p><strong>NOTE</strong>: see the
|
||
FAQ on “<a href="../faq.html#entry_json">.entry.json files</a>”
|
||
for more details on <code>.entry.json</code> files.</p>
|
||
<div id="combine-author-handle">
|
||
<h3 id="combine_author_handle.sh"><a href="https://github.com/ioccc-src/winner/blob/master/bin/combine_author_handle.sh">combine_author_handle.sh</a></h3>
|
||
</div>
|
||
<p>Combine all author/author_handle.json files as single JSON file.</p>
|
||
<p>The purpose of this tool is to make looking for information across all
|
||
authors faster by temporarily forming them into a single JSON file.</p>
|
||
<p>Because <code>jsp(1)</code> open remembers the last copy of a given JSON member name.
|
||
As such, we change the JSON member name “winning_entry_set” into
|
||
a unique “winning_entry_set.FILENO” where FILENO is the file number.
|
||
This the JSON member value will be preserved across all files.</p>
|
||
<p>We also convert where FILENO is the file number and FILENAME is the filename:</p>
|
||
<pre><code> "sort_word" : "data",</code></pre>
|
||
<p>into:</p>
|
||
<pre><code> "sort_word.FILENO" : [
|
||
{
|
||
"sort_word" : "data FILENAME"
|
||
}
|
||
],</code></pre>
|
||
<p>This will allow <code>jsp(1)</code> to print sort_word values.</p>
|
||
<p>We also make sure that the last item from a given file ends in a comma (“,)”,
|
||
due to the bogosity of the so-called JSON spec.</p>
|
||
<p>Usage:</p>
|
||
<pre><code> bin/combine_author_handle.sh > combined_author_handle.json</code></pre>
|
||
<p><strong>NOTE</strong>: This tool assume that all JSON files have been formatted with the
|
||
<code>bin/jprint-wrapper.sh</code> tool. In particular the first line is just “{:,
|
||
and the last line is just”}” and each JSON element is on its own line.</p>
|
||
<p><strong>NOTE</strong>: see the
|
||
FAQ on “<a href="../faq.html#author_handle_json">author_handle.json</a>”
|
||
for more details on <code>author_handle.json</code> files.</p>
|
||
<div id="csv2entry">
|
||
<h3 id="csv2entry.sh"><a href="https://github.com/ioccc-src/winner/blob/master/bin/csv2entry.sh">csv2entry.sh</a></h3>
|
||
</div>
|
||
<p>Convert CSV files into <code>.entry.json</code> for all winning IOCCC entries.</p>
|
||
<p>This tool takes as input, the following CSV files:</p>
|
||
<ul>
|
||
<li><a href="#author_wins_csv">author_wins.csv</a> - <code>author_handle</code> followed by all their
|
||
<code>entry_id</code>s</li>
|
||
<li><a href="#manifest_csv">manifest.csv</a> - information about files under an entry</li>
|
||
<li><a href="#year_prize_csv">year_prize.csv</a> - <code>entry_id</code> followed by the entry’s award
|
||
title</li>
|
||
</ul>
|
||
<p>This tool updates <code>.entry.json</code> files entries whose content is modified.</p>
|
||
<p>Usage:</p>
|
||
<pre><code> bin/csv2entry.sh -v 1</code></pre>
|
||
<p>There is no requirement to sort the CSV files (say through the spreadsheet
|
||
application prior to exporting), convert them to UNIX format, or append a final
|
||
newline to the file.</p>
|
||
<p>This tool will canonicalize the CSV files before using them
|
||
as input. Thus, if one wishes to import the CSV file into
|
||
some spreadsheet such as the <a href="https://www.apple.com/macos">macOS</a>
|
||
<a href="https://www.apple.com/numbers/">Numbers</a> spreadsheet application,
|
||
modify the content and finally export back to the CSV file,
|
||
this tool will modify the CSV file (if needed) in order
|
||
to restore the CSV order and other canonicalizing processes.</p>
|
||
<p>This tool will flag as an error, any empty fields, fields that are
|
||
an unquoted <code>NULL</code> or <code>null</code>, fields that start with whitespace,
|
||
fields that end with whitespace, or fields that contain consecutive
|
||
whitespace characters.</p>
|
||
<p><strong>NOTE</strong>: see the
|
||
FAQ on “<a href="../faq.html#entry_json">.entry.json files</a>”
|
||
for more details on <code>.entry.json</code> files.</p>
|
||
<h4 id="internal-details-of-bincsv2entry.sh">Internal details of <code>bin/csv2entry.sh</code></h4>
|
||
<p>We first canonicalize the CSV files by replacing any “carriage
|
||
return line feeds” with “newlines”. We also make sure that the CSV
|
||
files end in a newline. We do this because some spreadsheet
|
||
applications, when exporting to a CSV file, do not do this.</p>
|
||
<p>We also sort the CSV files in the same way that <a href="#entry2csv">entry2csv</a> sorts
|
||
its CSV output files. We do this in case the CSV files were imported into a
|
||
spreadsheet where their order was changed before exporting. This means one is
|
||
free to order the CSV file content as you wish as this tool will reset these CSV
|
||
files.</p>
|
||
<p>Next this tool processes the non-CSV comment lines in
|
||
<a href="#manifest_csv">manifest.csv</a>. The 1st and 2nd fields of
|
||
<a href="#manifest_csv">manifest.csv</a> refer to entry YYYY and entry subdirectory (i.e.,
|
||
the <code>YYYY/dir</code> directory under the root of the git repository). From that list of
|
||
<code>YYYY/dir</code> IOCCC entry directories, we will create the <code>.entry.json</code> files. We
|
||
only modify those <code>.entry.json</code> files when their content changes.</p>
|
||
<p><strong>IMPORTANT NOTE</strong>: while this tool uses <code>jparse(1)</code> to verify that the modified
|
||
<code>.entry.json</code> contains valid JSON content, <strong>this tool does NOT perform ANY
|
||
semantic checks</strong>. For example, this tool does <strong>NOT</strong> verify that the manifest in
|
||
the <code>.entry.json</code> file matches the files in the <code>YYYY/dir directory</code>, or even
|
||
that the <code>.entry.json</code> contains a manifest (or any of the other required JSON
|
||
content). Another tool will be modified to do this, at a later date.</p>
|
||
<p><strong>NOTE</strong>: you can obtain <code>jparse(1)</code> from the which can be obtained from the
|
||
<a href="https://github.com/ioccc-src/mkiocccentry">mkiocccentry repo</a>’s copy of the
|
||
<a href="https://github.com/xexyl/jparse/">jparse repo</a>.</p>
|
||
<div id="cvt-submission">
|
||
<h3 id="cvt-submission.sh"><a href="https://github.com/ioccc-src/winner/blob/master/bin/cvt-submission.sh">cvt-submission.sh</a></h3>
|
||
</div>
|
||
<p>This tool is used by the <a href="../judges.html">Judges</a> as part of the final
|
||
steps to announce a new set of winning IOCCC entries.</p>
|
||
<p>Given a submission (that has won the IOCCC and thus will become an entry), with a <code>.auth.json</code>
|
||
and <code>.info.json</code>, we convert the <code>.auth.json</code> and <code>.info.json</code> into a new <code>.entry.json</code> file.</p>
|
||
<p><strong>NOTE</strong>: the <code>.auth.json</code> and <code>.info.json</code> files are formed by the
|
||
<code>mkiocccentry(1)</code> tool from the <a href="https://github.com/ioccc-src/mkiocccentry">mkiocccentry GitHub
|
||
repo</a> as part of packaging
|
||
submissions.</p>
|
||
<p>We will also form new <code>author/author_handle.json</code> (see the
|
||
FAQ on “<a href="../faq.html#author_json">author_handle.json files</a>”
|
||
for more information) and update <code>author/author_handle.json</code>
|
||
for <a href="../authors.html">authors</a> who previously won. See also the
|
||
FAQ on “<a href="../faq.html#author_handle_faq">author_handle</a>”.
|
||
See also the
|
||
FAQ on “<a href="../faq.html#entry_json">.entry.json</a>”.</p>
|
||
<p>Usage:</p>
|
||
<pre><code> bin/cvt-submission.sh -v 1 YYYY/dir</code></pre>
|
||
<p>Here, <code>YYYY/dir</code> is the path of the submission under the <code>YYYY</code> year directory.</p>
|
||
<p>This tool will form a compressed tarball of any files under <code>YYYY/dir</code>
|
||
that could be modified or removed by this tool (unless <code>-N</code> is used in which
|
||
case this tool does nothing). The compressed tarball, formed by default
|
||
under the <code>/var/tmp</code> directory, may contain such as:</p>
|
||
<ul>
|
||
<li><code>YYYY/dir/.info.json</code></li>
|
||
<li><code>YYYY/dir/.auth.json</code></li>
|
||
<li><code>YYYY/dir/remarks.md</code></li>
|
||
<li><code>YYYY/dir/README.md</code></li>
|
||
<li><code>YYYY/dir/index.md</code></li>
|
||
<li><code>YYYY/dir/YYYY_dir.tar.bz2</code></li>
|
||
<li><code>author/author_handle.json</code> (could be more than one file)</li>
|
||
</ul>
|
||
<p>Only those files that exist will be put into the compressed tarball.
|
||
The compressed tarball formed (by default under the <code>/var/tmp</code> directory)
|
||
is of the following form:</p>
|
||
<blockquote>
|
||
<p>YYYY_dir.mods.YYYYMMDD.hhmmss.tar.bz2</p>
|
||
</blockquote>
|
||
<p>Here “<code>YYYYMMDD.hhmmss</code>” is a date and timestamp from when the tool was executed.</p>
|
||
<p>The purpose of this compressed tarball is to allow the files in the
|
||
entry directory (that could be modified or removed by this tool)
|
||
to be restored as follows:</p>
|
||
<pre><code> tar -jxvf /var/tmp/YYYY_dir.mods.YYYYMMDD.hhmmss.tar.bz2 YYYY/dir</code></pre>
|
||
<p>One may also restore modified <code>author/author_handle.json</code> files using:</p>
|
||
<pre><code> tar -jxvf /var/tmp/YYYY_dir.mods.YYYYMMDD.hhmmss.tar.bz2 author</code></pre>
|
||
<p>This tool will form <code>YYYY/dir/README.md</code> if needed, from <code>YYYY/dir/remarks.md</code>,
|
||
<code>template/entry/README.md.head</code>, and <code>template/entry/README.md.tail</code>.</p>
|
||
<p><strong>NOTE</strong>: This interactive tool (unless <code>-i input_data</code> is used) does
|
||
<strong>NOT</strong> perform all of the steps needed to make a directory for a new winning
|
||
IOCCC entry. For example, files such as <code>YYYY/dir/README.md</code> and/or <code>YYYY/dir/index.html</code>
|
||
might contain “<em>triple X</em>” comments, indicating where the <a href="../judges.html">Judges</a>
|
||
need to add content. Moreover, the <code>Makefile</code> and <code>.gitignore</code> files
|
||
need to be examined for suitability, etc.</p>
|
||
<p><strong>HINT</strong>: Executing this tool on your submission will <strong>NOT</strong> make you an IOCCC winner. :-)</p>
|
||
<div id="entry2csv">
|
||
<h3 id="entry2csv.sh"><a href="https://github.com/ioccc-src/winner/blob/master/bin/entry2csv.sh">entry2csv.sh</a></h3>
|
||
</div>
|
||
<p>This tool takes as input, all entry <code>.entry.json</code> files
|
||
and updates 3 CSV files:</p>
|
||
<ul>
|
||
<li><a href="#author_wins_csv">author_wins.csv</a> - each <code>author_handle</code> followed by their <code>entry_id</code>s</li>
|
||
<li><a href="#manifest_csv">manifest.csv</a> - information about all files in all entries</li>
|
||
<li><a href="#year_prize_csv">year_prize.csv</a> - each <code>entry_id</code> followed by the entry’s award title</li>
|
||
</ul>
|
||
<p>The CSV files are written in a canonical UNIX format form.</p>
|
||
<p>Only those CSV files files whose content is modified are written.</p>
|
||
<h4 id="internal-details-of-binentry2csv.sh">Internal details of <code>bin/entry2csv.sh</code></h4>
|
||
<p>We generate CSV files from the <code>.entry.json</code> files from winning
|
||
IOCCC entries listed under years listed in the <code>.top</code> file,
|
||
and in subdirectories listed in the <code>YYYY/.year</code> file for the
|
||
given year. Only those entries so listed are processed.</p>
|
||
<p>All IOCCC entry directories must have a <code>.path</code> file that lists
|
||
the path of the entry’s directory from the <code>TOPDIR</code>.</p>
|
||
<p><strong>IMPORTANT NOTE</strong>: when adding new IOCCC winning entries, the <code>.top</code> file
|
||
<strong>MUST</strong> be updated, and the new IOCCC year <code>YYYY/.year</code> files <strong>MUST</strong>
|
||
reference the directory of the new IOCCC entries. Each entry directory <strong>MUST</strong>
|
||
also contain a <code>.path</code> file that contains the path of the IOCCC entry directory
|
||
from the <code>TOPDIR</code>.</p>
|
||
<div id="filelist-entry-json-awk">
|
||
<h3 id="filelist.entry.json.awk"><a href="https://github.com/ioccc-src/winner/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>Usage:</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="html-sed">
|
||
<h3 id="html.sed"><a href="https://github.com/ioccc-src/winner/blob/master/bin/html.sed">html.sed</a></h3>
|
||
</div>
|
||
<p>Translates certain characters in their corresponding HTML entities. For example
|
||
<code><</code> is converted to <code>&lt;</code> and <code>></code> is converted to <code>&gt;</code>. This is important to
|
||
satisfy html lints.</p>
|
||
<p>This script is used in <a href="#md2html">md2html.sh</a> via
|
||
<a href="#output-index-inventory">output-index-inventory.sh</a> and
|
||
<a href="#subst-entry-index">subst.entry-index.sh</a>.</p>
|
||
<p>Usage:</p>
|
||
<pre><code> cmd | sed -f bin/html.sed
|
||
|
||
sed -f bin/html.sed file > output
|
||
|
||
sed -i -f bin/html.sed file</code></pre>
|
||
<div id="find-missing-links">
|
||
<h3 id="find-missing-links.sh"><a href="https://github.com/ioccc-src/winner/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, it checks on
|
||
links to local files.</p>
|
||
<p>This tool does <strong>NOT</strong> check links in a given place in a file, it
|
||
checks that local files linked by markdown actually exist.</p>
|
||
<p>This tool does <strong>NOT</strong> check HTML file links, it 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 notwithstanding), otherwise this tool will exit non-zero.</p>
|
||
<p><strong>NOTE</strong>: 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>:</p>
|
||
<pre><code> make find_missing_links</code></pre>
|
||
<div id="find-invalid-json">
|
||
<h3 id="find-invalid-json.sh"><a href="https://github.com/ioccc-src/winner/blob/master/bin/find-invalid-json.sh">find-invalid-json.sh</a></h3>
|
||
</div>
|
||
<p>This script uses the <code>jparse(1)</code> tool, which can be obtained from the
|
||
<a href="https://github.com/ioccc-src/mkiocccentry">mkiocccentry repo</a>’s copy of the
|
||
<a href="https://github.com/xexyl/jparse/">jparse repo</a>, and searches for any invalid
|
||
JSON files in the tree.</p>
|
||
<p>This is important because the IOCCC makes extensive use of JSON.</p>
|
||
<p>Usage:</p>
|
||
<pre><code> bin/find-invalid-json.sh -v 1</code></pre>
|
||
<p>If no invalid JSON files are found, this tool exits 0 with no output
|
||
(debug messages notwithstanding), otherwise this tool will exit non-zero.</p>
|
||
<p>We recommend that this tool be invoked via the top level <code>Makefile</code>:</p>
|
||
<pre><code> make find_invalid_json</code></pre>
|
||
<div id="format-headers">
|
||
<h3 id="format-headers.sh"><a href="https://github.com/ioccc-src/winner/blob/master/bin/format-headers.sh">format-headers.sh</a></h3>
|
||
</div>
|
||
<p>Format select headers and preceding empty lines in entry README.md files.</p>
|
||
<p>Usage:</p>
|
||
<pre><code> bin/format-headers.sh</code></pre>
|
||
<div id="gen-authors">
|
||
<h3 id="gen-authors.sh"><a href="https://github.com/ioccc-src/winner/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>:</p>
|
||
<pre><code> make gen_authors</code></pre>
|
||
<div id="gen-location">
|
||
<h3 id="gen-location.sh"><a href="https://github.com/ioccc-src/winner/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>:</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/winner/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>:</p>
|
||
<pre><code> make gen_other_html</code></pre>
|
||
<div id="gen-readme">
|
||
<h3 id="gen-readme.sh"><a href="https://github.com/ioccc-src/winner/blob/master/bin/gen-readme.sh">gen-readme.sh</a></h3>
|
||
</div>
|
||
<p>Generate a <code>README.md</code> file a submission’s <code>remarks.md</code> and the
|
||
template files in <a href="https://github.com/ioccc-src/winner/blob/master/template/entry/README.md.head">template/entry/README.md.head</a>
|
||
and <a href="https://github.com/ioccc-src/winner/blob/master/template/entry/README.md.tail">template/entry/README.md.tail</a>.</p>
|
||
<p>Usage:</p>
|
||
<pre><code> bin/gen-readme.sh -v 1 YYYY template/entry/README.md.head YYYY/dir/remarks.md template/entry/README.md.tail YYYY/dir/README.md</code></pre>
|
||
<p>While this tool is used by <a href="#cvt-submission">cvt-submission</a>, it may also
|
||
be used by hand by the <a href="../judges.html">Judges</a> during the final judging rounds.</p>
|
||
<div id="gen-sitemap">
|
||
<h3 id="gen-sitemap.sh"><a href="https://github.com/ioccc-src/winner/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>:</p>
|
||
<pre><code> make gen_sitemap</code></pre>
|
||
<div id="gen-status">
|
||
<h3 id="gen-status.sh"><a href="https://github.com/ioccc-src/winner/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/winner/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>:</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/winner/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="https://github.com/ioccc-src/winner/blob/master/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>:</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/winner/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>:</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/winner/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>:</p>
|
||
<pre><code> make gen_years</code></pre>
|
||
<div id="jfmt-wrapper">
|
||
<h3 id="jfmt-wrapper.sh"><a href="https://github.com/ioccc-src/winner/blob/master/bin/jfmt-wrapper.sh">jfmt-wrapper.sh</a></h3>
|
||
</div>
|
||
<p>The <a href="https://github.com/ioccc-src/winner/blob/master/bin/jfmt-wrapper.sh">jfmt-wrapper.sh</a> tool is a wrapper
|
||
tool for <code>jfmt(1)</code>, a tool that will format a JSON file into a canonical style.</p>
|
||
<p><strong>NOTE</strong>: As of 2024 Oct 08 the <code>jfmt(1)</code> tool has not been written,
|
||
so <a href="https://github.com/ioccc-src/winner/blob/master/bin/jfmt-wrapper.sh">jfmt-wrapper.sh</a> uses the
|
||
<code>JSONPath.sh(1)</code> tool from the recently forked and modified
|
||
<a href="https://github.com/lcn2/JSONPath.sh">JSONPath.sh tool</a>.</p>
|
||
<p>Usage:</p>
|
||
<pre><code> bin/jfmt-wrapper.sh .entry.json</code></pre>
|
||
<div id="jprint-wrapper">
|
||
<h3 id="jprint-wrapper.sh"><a href="https://github.com/ioccc-src/winner/blob/master/bin/jprint-wrapper.sh">jprint-wrapper.sh</a></h3>
|
||
</div>
|
||
<p>The <a href="https://github.com/ioccc-src/winner/blob/master/bin/jprint-wrapper.sh">jprint-wrapper.sh</a> tool is a wrapper
|
||
tool for <code>jprint(1)</code>, a tool that will format JSON in a canonical style
|
||
to stdout.</p>
|
||
<p><strong>NOTE</strong>: <code>jprint(1)</code> is a planned tool based on <code>jfmt(1)</code>.
|
||
As of 2024 Oct 08 that tool has not been written, so
|
||
<a href="https://github.com/ioccc-src/winner/blob/master/bin/jprint-wrapper.sh">jprint-wrapper.sh</a> uses
|
||
the <code>JSONPath.sh(1)</code> tool from the recently forked and modified
|
||
<a href="https://github.com/lcn2/JSONPath.sh">JSONPath.sh tool</a>.</p>
|
||
<p>Usage:</p>
|
||
<pre><code> bin/jprint-wrapper.sh .entry.json</code></pre>
|
||
<p>Or use in a pipe:</p>
|
||
<pre><code> cat .info.json | bin/jprint-wrapper.sh</code></pre>
|
||
<div id="jval-wrapper">
|
||
<h3 id="jval-wrapper.sh"><a href="https://github.com/ioccc-src/winner/blob/master/bin/jval-wrapper.sh">jval-wrapper.sh</a></h3>
|
||
</div>
|
||
<p>The <a href="https://github.com/ioccc-src/winner/blob/master/bin/jval-wrapper.sh">jval-wrapper.sh</a> tool is a wrapper
|
||
tool for <code>jval(1)</code>, a tool that will output a JSON value using the
|
||
XPath for JSON mechanism. For information in XPath for JSON see:</p>
|
||
<ul>
|
||
<li><a href="https://goessner.net/articles/JsonPath/">https://goessner.net/articles/JsonPath/</a></li>
|
||
<li><a href="https://jsonpath.com">https://jsonpath.com</a></li>
|
||
<li><a href="https://github.com/lcn2/JSONPath.sh?tab=readme-ov-file#jsonpath-patterns-and-extensions">https://github.com/lcn2/JSONPath.sh?tab=readme-ov-file#jsonpath-patterns-and-extensions</a></li>
|
||
</ul>
|
||
<p><strong>NOTE</strong>: As of 2024 Oct 08 the <code>jval(1)</code> tool has not been written,
|
||
so <a href="https://github.com/ioccc-src/winner/blob/master/bin/jval-wrapper.sh">jval-wrapper.sh</a> uses the
|
||
<code>jsp(1)</code> tool from <a href="https://github.com/kjozsa/jsp">https://github.com/kjozsa/jsp</a>
|
||
or if not found, the <code>JSONPath.sh(1)</code> tool from the recently forked and modified
|
||
<a href="https://github.com/lcn2/JSONPath.sh">JSONPath.sh tool</a>.</p>
|
||
<p>Usage:</p>
|
||
<pre><code> bin/jval-wrapper.sh [-b] [-q] [-T] file.json [pattern]
|
||
|
||
-b print only values (def: print both JSON member and JSON value)
|
||
-q remove enclosing double quotes (def: keep any enclosing double quotes)
|
||
-T trim all newlines (def: do not)
|
||
|
||
file.json JSON file to process, - ==> read stdin
|
||
pattern Xpath for JSON query pattern</code></pre>
|
||
<p>For example:</p>
|
||
<pre><code> bin/jval-wrapper.sh 1984/mullender/.entry.json '$.award'
|
||
bin/jval-wrapper.sh 1984/mullender/.entry.json '$..author_handle'
|
||
|
||
bin/jval-wrapper.sh 1984/mullender/.entry.json '$.manifest[2]'
|
||
bin/jval-wrapper.sh -q 1984/mullender/.entry.json '$.manifest[2]'
|
||
|
||
bin/jval-wrapper.sh -b 1984/mullender/.entry.json '$.manifest[2].entry_text'
|
||
bin/jval-wrapper.sh -b -q 1984/mullender/.entry.json '$.manifest[2].inventory_order'
|
||
|
||
bin/jval-wrapper.sh author/Anton_Algmyr.json '$.full_name'
|
||
bin/jval-wrapper.sh -q -T author/Anton_Algmyr.json '$.full_name' | jstrdecode -</code></pre>
|
||
<p><strong>NOTE</strong>: With <code>jstrdecode(1)</code> version 1.2.3 or better, one can use <code>jstrdecode -N</code>
|
||
and not have to use <code>-T</code> with <code>bin/jval-wrapper.sh</code>.</p>
|
||
<div id="manifest-csv-entry">
|
||
<h3 id="manifest.csv.entry.awk"><a href="https://github.com/ioccc-src/winner/blob/master/bin/manifest.csv.entry.awk">manifest.csv.entry.awk</a></h3>
|
||
</div>
|
||
<p>Output <code>manifest.csv</code> from a entry’s manifest as found in its <code>.entry.json</code> file.</p>
|
||
<pre><code> awk -f bin/manifest.csv.entry.awk YYYY/dir/.entry.json</code></pre>
|
||
<div id="manifest-csv-json">
|
||
<h3 id="binmanifest.entry.json.awk"><a href="https://github.com/ioccc-src/winner/blob/master/bin/manifest.entry.json.awk">bin/manifest.entry.json.awk</a></h3>
|
||
</div>
|
||
<p>Output manifest table from an entry’s <code>.entry.json</code> file.</p>
|
||
<pre><code> awk -v github=REPO_URL -f bin/manifest.entry.json.awk YYYY/dir/.entry.json</code></pre>
|
||
<div id="md2html-cfg">
|
||
<h3 id="md2html.cfg"><a href="https://github.com/ioccc-src/winner/blob/master/bin/md2html.cfg">md2html.cfg</a></h3>
|
||
</div>
|
||
<p>This is a configuration file for the <a href="index.html#md2html">md2html</a> tool.
|
||
Although a configuration file it is also something of a script file.</p>
|
||
<p>To not down descend into the depths of <code>pandoc(1)</code> and to have to explain how
|
||
this file can change all the HTML files, we advise you to let
|
||
<a href="https://www.glyphweb.com/arda/s/smaug.html">Smaug</a> (the dragon of
|
||
<a href="https://www.glyphweb.com/arda/e/erebor.html">Erebor</a> famously visited by a
|
||
<a href="https://www.glyphweb.com/arda/h/hobbits.html">Hobbit</a> called <a href="https://www.glyphweb.com/arda/b/bilbobaggins.html">Bilbo
|
||
Baggins</a> and 13
|
||
<a href="https://www.glyphweb.com/arda/d/dwarves.html">Dwarves</a> in the
|
||
<a href="https://www.glyphweb.com/arda/t/thirdage.html">T.A.</a> 2941 or 1341
|
||
in the <a href="https://www.glyphweb.com/arda/s/shirereckoning.html">Shire-reckoning</a>)), slumber as
|
||
“<code>here be dragons</code>”. If you still need convincing, we wish to remind you of <a href="https://www.glyphweb.com/arda/b/bilbobaggins.html">Bilbo
|
||
Baggins</a>’ famous words:</p>
|
||
<blockquote>
|
||
<p>“Never laugh at live dragons,
|
||
<a href="https://www.glyphweb.com/arda/b/bilbobaggins.html">Bilbo</a> you fool!” he said to himself, and it
|
||
became a favourite saying of his later, and passed into a proverb.</p>
|
||
</blockquote>
|
||
<div id="md2html">
|
||
<h3 id="md2html.sh"><a href="https://github.com/ioccc-src/winner/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="https://github.com/ioccc-src/winner/blob/master/inc/index.html">inc directory</a>.</p>
|
||
<p>The <a href="index.html#md2html_cfg">md2html.cfg</a> configuration file is
|
||
used by <a href="https://github.com/ioccc-src/winner/blob/master/bin/md2html.sh">md2html.sh</a> to drive the generation process.</p>
|
||
<div id="new-dir">
|
||
<h3 id="new-dir.sh"><a href="https://github.com/ioccc-src/winner/blob/master/bin/new-dir.sh">new-dir.sh</a></h3>
|
||
</div>
|
||
<p>This tool is used by the <a href="../judges.html">Judges</a> as one of the
|
||
steps needed to announce a new winning IOCCC entry.</p>
|
||
<p>Usage:</p>
|
||
<pre><code> mkdir -p YYYY/dir
|
||
bin/new-dir.sh YYYY/dir</code></pre>
|
||
<p>Here, <code>YYYY/dir</code> must be the path to the winning IOCCC entry.</p>
|
||
<p><strong>NOTE</strong>: This tool does <strong>NOT</strong> perform all of the steps needed
|
||
to make a directory a new winning IOCCC entry. It only starts the
|
||
framework for doing so, creating a situation where the
|
||
<a href="#cvt-submission">cvt-submission</a> tool be be run.</p>
|
||
<p>This tool can modify the top level <code>.allyear</code> file, and <code>YYYY/Makefile</code> files.</p>
|
||
<p><strong>NOTE</strong>: This tool assumes that <a href="#new-year">new-year.sh</a> was executed to create
|
||
the prerequisite <code>YYYY</code> directory and related files.</p>
|
||
<p><strong>HINT</strong>: Executing this tool on your submission will <strong>NOT</strong> make you an IOCCC winner. :-)</p>
|
||
<div id="new-year">
|
||
<h3 id="new-year.sh"><a href="https://github.com/ioccc-src/winner/blob/master/bin/new-year.sh">new-year.sh</a></h3>
|
||
</div>
|
||
<p>This tool is used by the <a href="../judges.html">Judges</a> as part of the final
|
||
steps to announce a new set of winning IOCCC entries.</p>
|
||
<p>This tool may modify the top level <code>.top</code> and <code>Makefile</code> files.
|
||
It will form <code>YYYY/Makefile</code> and/or <code>YYYY/.year</code> if needed.
|
||
It will form <code>YYYY/README.md</code> if needed, from <code>template/README.md.year</code>.</p>
|
||
<p><strong>NOTE</strong>: This tool does <strong>NOT</strong> perform all of the steps needed to make a new IOCCC year directory.
|
||
For example, files such as <code>YYYY/README.md</code> and/or <code>YYYY/index.html</code>
|
||
might contain “<em>triple X</em>” comments indicating where the
|
||
<a href="../judges.html">Judges</a> need to add content.</p>
|
||
<p>Usage:</p>
|
||
<pre><code> bin/new-year.sh -v 1 YYYY</code></pre>
|
||
<p>Here, <code>YYYY</code> must be a new 4-digit (happy :-)) new IOCCC year.</p>
|
||
<div id="othermd2html">
|
||
<h3 id="othermd2html.sh"><a href="https://github.com/ioccc-src/winner/blob/master/bin/othermd2html.sh">othermd2html.sh</a></h3>
|
||
</div>
|
||
<p>Convert a non-README.md file in an entry to HTML.</p>
|
||
<p>Usage:</p>
|
||
<pre><code> bin/othermd2html.sh YYYY/dir/pathto.md</code></pre>
|
||
<p>For example:</p>
|
||
<pre><code> bin/othermd2html.sh -v 1 2020/ferguson1/chocolate-cake.md</code></pre>
|
||
<p>The <a href="#othermd2html">othermd2html.sh</a> tool is used by
|
||
<a href="#gen-other-html">gen-other-html.sh</a>.</p>
|
||
<div id="output-index-author">
|
||
<h3 id="output-index-author.sh"><a href="https://github.com/ioccc-src/winner/blob/master/bin/output-index-author.sh">output-index-author.sh</a></h3>
|
||
</div>
|
||
<p>Output an 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/winner/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/winner/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/winner/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-year-index">
|
||
<h3 id="output-year-index.sh"><a href="https://github.com/ioccc-src/winner/blob/master/bin/output-year-index.sh">output-year-index.sh</a></h3>
|
||
</div>
|
||
<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 the <a href="../1984/index.html#inventory">1984
|
||
inventory</a>.</p>
|
||
<p>This tool is used in the <a href="https://github.com/ioccc-src/winner/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="pandoc-wrapper">
|
||
<h3 id="pandoc-wrapper.sh"><a href="https://github.com/ioccc-src/winner/blob/master/bin/pandoc-wrapper.sh">pandoc-wrapper.sh</a></h3>
|
||
</div>
|
||
<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/winner/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>:</p>
|
||
<pre><code> make quick_readme2index</code></pre>
|
||
<div id="readme2index">
|
||
<h3 id="readme2index.sh"><a href="https://github.com/ioccc-src/winner/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>:</p>
|
||
<pre><code> make entry_index</code></pre>
|
||
<div id="sgi">
|
||
<h3 id="sgi.sh"><a href="https://github.com/ioccc-src/winner/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/winner/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>:</p>
|
||
<pre><code> make sort_gitignore</code></pre>
|
||
<div id="status2html">
|
||
<h3 id="status2html.sh"><a href="https://github.com/ioccc-src/winner/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="subst-default">
|
||
<h3 id="subst.default.sh"><a href="https://github.com/ioccc-src/winner/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/winner/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/winner/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/winner/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/winner/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/winner/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/winner/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/winner/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/winner/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/winner/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>:</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/winner/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>:</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/winner/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>:</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 website</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="https://github.com/ioccc-src/winner/blob/master/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="https://github.com/ioccc-src/winner/blob/master/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="https://github.com/ioccc-src/winner/blob/master/inc/navbar.up2index.html">inc/navbar.up2index.html</a>
|
||
instead of <a href="https://github.com/ioccc-src/winner/blob/master/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="https://github.com/ioccc-src/winner/blob/master/inc/top.default.html">inc/top.default.html</a></li>
|
||
<li><a href="https://github.com/ioccc-src/winner/blob/master/inc/head.default.html">inc/head.default.html</a></li>
|
||
<li><a href="https://github.com/ioccc-src/winner/blob/master/inc/body.default.html">inc/body.default.html</a></li>
|
||
<li><a href="https://github.com/ioccc-src/winner/blob/master/inc/topbar.default.html">inc/topbar.default.html</a></li>
|
||
<li><a href="https://github.com/ioccc-src/winner/blob/master/inc/header.default.html">inc/header.default.html</a></li>
|
||
<li><a href="https://github.com/ioccc-src/winner/blob/master/inc/navbar.default.html">inc/navbar.default.html</a></li>
|
||
<li><a href="https://github.com/ioccc-src/winner/blob/master/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="https://github.com/ioccc-src/winner/blob/master/inc/after-content.default.html">inc/after-content.default.html</a></li>
|
||
<li><a href="https://github.com/ioccc-src/winner/blob/master/inc/footer.default.html">inc/footer.default.html</a></li>
|
||
<li><a href="https://github.com/ioccc-src/winner/blob/master/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/winner/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/winner/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/winner/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/winner/blob/master/bin/md2html.cfg">md2html config file</a>
|
||
that refers to
|
||
<a href="https://github.com/ioccc-src/winner/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/winner/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>… and in particular files under <a href="https://github.com/ioccc-src/winner/blob/master/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/winner/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 the <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 new IOCCC winning 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 website</a>
|
||
(except for some mobile devices for the menu).</p>
|
||
<p>For this reason, we cannot use JavaScript to 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 that forms the
|
||
<a href="https://www.ioccc.org">official IOCCC website</a>.</p>
|
||
<h2 id="author"><code>author</code></h2>
|
||
<p>An <strong>individual</strong> who was won at least one winning IOCCC <a href="#entry">entry</a>.</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 <a href="#author">author</a> and <strong>is unique to the
|
||
IOCCC</strong>. Each <a href="#author">author</a> 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 <a href="#author">author</a>’s <code>author_handle</code>.</p>
|
||
<p>Because the <code>author_handle</code> is used to form a JSON filename, the string <strong>MUST</strong> be
|
||
a POSIX safe string with the addition of <code>+</code> (for technical reasons beyond this
|
||
document). In particular, the <code>author_handle</code> <strong>MUST</strong> 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 <a href="#author">author</a>. While
|
||
there is an algorithm that maps the name of the <a href="#author">author</a> (which may contain any UTF-8
|
||
characters) into a default <code>author_handle</code> string, those who submit to the IOCCC
|
||
are free to choose a different <code>author_handle</code> string if they so desire.</p>
|
||
<p><strong>NOTE</strong>: an <a href="#author">author</a> who has won a <a href="../years.html">previous IOCCC</a>
|
||
<strong>is encouraged to reuse their <code>author_handle</code></strong> so that new winning
|
||
<a href="#entry">entries</a> can be associated with the same <a href="#author">author</a>.</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 is more than one anonymous author in a given
|
||
year.</p>
|
||
<p><strong>NOTE</strong>: 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 <a href="#submission">submission</a> 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 entries that used them.</p>
|
||
<p><strong>HISTORICAL NOTE</strong>: in the past, the term <code>winner</code> was used in instead of
|
||
today’s term of <code>entry</code>.</p>
|
||
<h2 id="submission"><code>submission</code></h2>
|
||
<p>In the past, the IOCCC used the term <a href="#entry">entry</a> for both a hopeful
|
||
<a href="#submission">submission</a> and a <a href="#entry">winning entry</a>. It was decided,
|
||
however, in 2024, to remove this ambiguity by introducing the term
|
||
<a href="#submission">submission</a>. This does mean that if one wishes to win the IOCCC they
|
||
must submit to the <a href="../judges.html">Judges</a>! :-)</p>
|
||
<h2 id="submitter"><code>submitter</code></h2>
|
||
<p>A person who submits a <a href="#submission">submission</a>.</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 (hence <code>mock</code> and not <code>MOCK</code>).</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> (<code>1984</code>, <code>1985</code>, …, <code>2020</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 <a href="#year">year</a> directory will have a file under it named <code>.year</code>.</p>
|
||
<p>The content of each <code>.year</code> file is the <a href="#year">year string</a> of that year’s winning
|
||
<a href="#entry">entries’</a> (directory names). For instance, <a href="https://github.com/ioccc-src/winner/blob/master/2020/.year">2020/.year</a>
|
||
lists, one directory per line, the directories of the winning entries of
|
||
<a href="../2020/index.html">2020</a>. For instance, for <a href="../2020/index.html">2020</a>:</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 (directory name) 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 <a href="#entry">entry</a> is under its own individual directory. This directory
|
||
is directly under a <a href="#year">year</a> directory.</p>
|
||
<div id="entry-id">
|
||
<h3 id="entry_id"><code>entry_id</code></h3>
|
||
</div>
|
||
<p>A string that identifies <a href="#entry">winning entries</a>. The string is of the form:</p>
|
||
<pre><code> year_dir</code></pre>
|
||
<p>where <code>year</code> is the <a href="#year">year</a> and <code>dir</code> is the <a href="#dir">dir</a>.</p>
|
||
<p>For instance, the <code>entry_id</code> for <a href="../2020/endoh2/index.html">2020/endoh2</a>
|
||
is:</p>
|
||
<pre><code> 2020_endoh2</code></pre>
|
||
<div id="csv">
|
||
<h1 id="csv-files">CSV Files</h1>
|
||
</div>
|
||
<p>The <code>bin/csv2entry.sh</code> and <code>bin/entry2csv.sh</code> tools use the below
|
||
three CSV files. In the case of <code>bin/entry2csv.sh</code>, these CSV files
|
||
are created / updated; in the case of <code>bin/csv2entry.sh</code>, these
|
||
CSV files are used as input.</p>
|
||
<div id="author_wins_csv">
|
||
<h2 id="author_wins.csv"><code>author_wins.csv</code></h2>
|
||
</div>
|
||
<p>A CSV file exported from a spreadsheet, one line per <a href="#author">author</a>.</p>
|
||
<p>The first field is an <a href="#author-handle">author_handle</a>.</p>
|
||
<p>The other fields are the <a href="#entry-id">entry_id</a>s of all <code>YYYY/dir</code>
|
||
<a href="#entry">entries</a> won by the <a href="#author">author</a>.</p>
|
||
<div id="manifest_csv">
|
||
<h2 id="manifest.csv"><code>manifest.csv</code></h2>
|
||
</div>
|
||
<p>A CSV file exported from a spreadsheet that contains information about files in
|
||
<code>YYYY/dir</code> entry directories under year directories. This file has the
|
||
following fields:</p>
|
||
<ol type="1">
|
||
<li><p><code>year</code>:</p>
|
||
<p>IOCCC year as a 4-character string. Normally this would be a 4 digit year string,
|
||
however it may also be a string such as “mock”.</p>
|
||
<p>NOTE: If year begins with <code>#</code>, then <code>dir</code> (see below) is a comment, and the
|
||
rest of the row is to be ignored. Rows of this form do <strong>NOT</strong> contain
|
||
manifest information for a file.</p></li>
|
||
<li><p><code>dir</code>:</p>
|
||
<p>Directory name (number of the IOCCC year).</p></li>
|
||
<li><p><code>path</code>:</p>
|
||
<p>Path under the IOCCC/directory. In a few cases this is a path,
|
||
not just a simple filename under the IOCCC/directory.</p></li>
|
||
<li><p><code>inventory_order</code>:</p>
|
||
<p>This number is the rank showing the order that this file is to be listed in
|
||
the list of files for the given entry in the <code>index.html</code> file.</p>
|
||
<p>If the number is under 10 digits, then the given file
|
||
is considered a primary file when listed in the inventory
|
||
of files for a given winning <code>YYYY/dir</code> entry.</p>
|
||
<p>If the number is 10 digits or more, then the given file
|
||
is considered a secondary file when listed in the inventory
|
||
of files for a given winning <code>YYYY/dir</code> entry. We recommend using the
|
||
value <code>4294967295</code> (<code>2^32-1</code>) for secondary files.</p></li>
|
||
<li><p><code>OK_to_edit</code>:</p>
|
||
<p>If the value is <code>true</code>, then the file is one that may be
|
||
edited directly.</p>
|
||
<p>If the value is <code>false</code>, then the file should <strong>NOT</strong> be
|
||
edited, because the given file is generated by a tool.
|
||
One should <strong>NOT</strong> modify such a file directly, but
|
||
instead modify source files (i.e., markdown files,
|
||
JSON files, etc.)</p></li>
|
||
<li><p><code>display_as</code>:</p>
|
||
<p>The type of given file (e.g. C, JSON, shellscript etc.)</p>
|
||
<p><strong>NOTE</strong>: these are lower case words.</p></li>
|
||
<li><p><code>display_via_github</code>:</p>
|
||
<p>If <code>true</code>, then the contents of the file should be viewed
|
||
via the GitHub repo.</p>
|
||
<p>If <code>false</code>, then the contents of the file should be viewed
|
||
in the web browser directly. In some cases this may
|
||
result in the file being downloaded instead of being displayed.</p></li>
|
||
<li><p><code>entry_text</code>:</p>
|
||
<p>Any text that should be displayed at the end of line in <code>index.html</code>
|
||
(with a preceding ” - “), or <code>null</code> if no such text is to be displayed.</p></li>
|
||
</ol>
|
||
<p><strong>NOTE</strong>: Cells containing <code>true</code> or <code>false</code> are JSON booleans.</p>
|
||
<p><strong>NOTE</strong>: All other cells are JSON strings that need to be double quoted (in the
|
||
JSON files), including the year.</p>
|
||
<p><strong>NOTE</strong>: Do not put commas, or quotes, or newlines in fields as these are bound
|
||
to cause problems.</p>
|
||
<div id="year_prize_csv">
|
||
<h2 id="year_prize.csv"><code>year_prize.csv</code></h2>
|
||
</div>
|
||
<p>A CSV spreadsheet, one line per <code>YYYY/dir</code> entry directory.</p>
|
||
<p>The first field is an <a href="#entry-id">entry_id</a>.</p>
|
||
<p>The second field is the name of the award for a given <code>YYYY/dir</code> entry.</p>
|
||
<!--
|
||
|
||
Copyright © 1984-2025 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-2025 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-2025 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%2Fwww.ioccc.org%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 -->
|