The sections have been modified a fair amount. The Entries menu has been extended to have: Fixing entries, Updating author info, Thanks for the help. The first two were moved from FAQ and the last one from About. The rationale for these, in order: entries and authors have to do with entries and most of the help involves entries. It also has to do with website but in 'about' it does not seem the right place, unless maybe it is renamed to 'Credits' or something (I am not suggesting this one way or the other). This one is debatable but that was the rationale. The Status menu has been extended to have: Markdown guidelines and Security policy. The rationale is that the markdown guidelines are part of contest guidelines and the security policy is about the status of the entries and how if there are any security problems they will not be addressed (instead of about the IOCCC). The FAQ was extended to have: Compiling entries, Running entries, How to help. The reason to not have compiling and running entries under Entries is because this is 'how to' and also the menu was too long. How to help seems like a good idea under FAQ too (was in About). About was extended to have the new 'about.html' page (from about.md). This is a rare case where a new file is useful as it fits under 'About'. The menu now is: Home page, About the IOCCC, The Judges, Contact us. I was pondering the 'About [the IOCCC]' at the top and also naming it 'About us' but it seemed like a link to index.html was necessary and as for 'about us' it seemed less clear as to whether it was about the judges or the contest itself. The FAQ has been updated slightly for this. After further inspection the bin/index.html and the inc/index.html links were removed from the about section. With these changes, renaming an item or slight reordering notwithstanding, I believe that #2006 is probably in good shape.
1645 lines
87 KiB
HTML
1645 lines
87 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 class="outfit-font">
|
||
<a href="../thanks-for-help.html" class="sub-item-link">
|
||
Thanks for the help
|
||
</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/index.html" class="sub-item-link">
|
||
Rules and 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="../faq.html#submit" class="sub-item-link">
|
||
How to enter
|
||
</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="../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="../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/index.html">
|
||
Rules and 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="../faq.html#submit">
|
||
How to enter
|
||
</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="../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%2Fioccc-src.github.io%2Ftemp-test-ioccc%2Fbin%2Findex.html">✓</a>
|
||
</div>
|
||
|
||
<!-- END: this line ends content from: inc/navbar.empty.html -->
|
||
<!-- START: this line starts content from: inc/before-content.default.html -->
|
||
|
||
<div class="content" id="content">
|
||
|
||
<!-- END: this line ends content from: inc/before-content.default.html -->
|
||
<!-- START: this line starts content for HTML phase 21 by: bin/pandoc-wrapper.sh via bin/md2html.sh -->
|
||
|
||
<!-- BEFORE: 1st line of markdown file: bin/README.md -->
|
||
<h1 id="bin">bin</h1>
|
||
<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="../inc/index.html">inc directory</a> as well as various JSON
|
||
files and other content from the <a href="https://github.com/ioccc-src/temp-test-ioccc">IOCCC GitHub
|
||
repo</a>.</p>
|
||
<h2 id="bin-tools"><a href="index.html">bin/</a> tools</h2>
|
||
<p>All tools in this directory support a number of options that can be used to get
|
||
help, diagnose problems, see progress etc. These options are as follows:</p>
|
||
<h3 id="get-help-usage-string-of-a-tool">Get help / usage string of a tool</h3>
|
||
<p>If you need to remember the syntax of the tool or get certain notes about
|
||
different options, you can use the <code>-h</code> option.</p>
|
||
<p>For instance if you want help on the <a href="index.html#all-run">all-run.sh</a> tool
|
||
from the root directory (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, you should use the <code>-v level</code> option. For instance if you wish to
|
||
see what is going on with the
|
||
<a href="index.html#quick-readme2index">quick-readme2index.sh</a> tool, you might do:</p>
|
||
<pre><code> bin/quick-readme2index.sh -v 3</code></pre>
|
||
<p>to set the verbosity level to <code>3</code>. The default for verbosity is <code>0</code>, no
|
||
verbosity, though using the <a href="https://github.com/ioccc-src/temp-test-ioccc/blob/master/Makefile">top level Makefile</a> will,
|
||
for some tools, set a verbosity level.</p>
|
||
<h3 id="get-version-string-of-a-tool">Get version string of a tool</h3>
|
||
<p>If you just want to know what version the tool is, you can use the <code>-V</code> option.
|
||
For instance to see what version the <a href="index.html#chk-entry">chk-entry.sh</a> tool
|
||
is, you would do:</p>
|
||
<pre><code> bin/chk-entry.sh -V</code></pre>
|
||
<h3 id="other-notes-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/temp-test-ioccc/blob/master/bin/md2html.cfg">bin/md2html.cfg</a> file but some of these tools can
|
||
be directly invoked as well, should you wish to see their output or if you have
|
||
some odd need to do so.</p>
|
||
<div id="all-jfmt">
|
||
<h3 id="all-jfmt.sh"><a href="https://github.com/ioccc-src/temp-test-ioccc/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/temp-test-ioccc/blob/master/bin/all-years.sh">all-years.sh</a></h3>
|
||
</div>
|
||
<p>Run a command on all IOCCC years.</p>
|
||
<p>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/temp-test-ioccc/blob/master/bin/all-run.sh">all-run.sh</a></h3>
|
||
</div>
|
||
<p>Run a command on all winning entries.</p>
|
||
<p>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="all-years">
|
||
<h3 id="all-years.sh-1"><a href="https://github.com/ioccc-src/temp-test-ioccc/blob/master/bin/all-years.sh">all-years.sh</a></h3>
|
||
</div>
|
||
<p>Run a command on all IOCCC years.</p>
|
||
<p>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="chk-entry">
|
||
<h3 id="chk-entry.sh"><a href="https://github.com/ioccc-src/temp-test-ioccc/blob/master/bin/chk-entry.sh">chk-entry.sh</a></h3>
|
||
</div>
|
||
<p>Check an entry directory to verify that 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/temp-test-ioccc/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/temp-test-ioccc/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/temp-test-ioccc/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 (<code><!--XXXX--></code>), 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/temp-test-ioccc/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/temp-test-ioccc/blob/master/bin/filelist.entry.json.awk">filelist.entry.json.awk</a></h3>
|
||
</div>
|
||
<p>Generate a list of files in an entry’s manifest (the <code>.entry.json</code> file).</p>
|
||
<p>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="find-missing-links">
|
||
<h3 id="find-missing-links.sh"><a href="https://github.com/ioccc-src/temp-test-ioccc/blob/master/bin/find-missing-links.sh">find-missing-links.sh</a></h3>
|
||
</div>
|
||
<p>Find all markdown links to local files that do not exist.</p>
|
||
<p>This tool does <strong>NOT</strong> check that a remote URL exists, 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/temp-test-ioccc/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/temp-test-ioccc/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/temp-test-ioccc/blob/master/bin/gen-authors.sh">gen-authors.sh</a></h3>
|
||
</div>
|
||
<p>Generate the top level <a href="../authors.html">authors.html</a> page.</p>
|
||
<p>Usage:</p>
|
||
<pre><code> bin/gen-authors.sh -v 1</code></pre>
|
||
<p>We recommend that this tool be invoked via the top level <code>Makefile</code>:</p>
|
||
<pre><code> make gen_authors</code></pre>
|
||
<div id="gen-location">
|
||
<h3 id="gen-location.sh"><a href="https://github.com/ioccc-src/temp-test-ioccc/blob/master/bin/gen-location.sh">gen-location.sh</a></h3>
|
||
</div>
|
||
<p>Generate the top level <a href="../location.html">location.html</a> page.</p>
|
||
<p>Usage:</p>
|
||
<pre><code> bin/gen-location.sh -v 1</code></pre>
|
||
<p>We recommend that this tool be invoked via the top level <code>Makefile</code>:</p>
|
||
<pre><code> make gen_location</code></pre>
|
||
<div id="gen-other-html">
|
||
<h3 id="gen-other-html.sh"><a href="https://github.com/ioccc-src/temp-test-ioccc/blob/master/bin/gen-other-html.sh">gen-other-html.sh</a></h3>
|
||
</div>
|
||
<p>Generate the HTML files (other than the README.md to index.html files) from
|
||
markdown files, of all entries.</p>
|
||
<p>Usage:</p>
|
||
<pre><code> bin/gen-other-html.sh -v 1</code></pre>
|
||
<p>We recommend that this tool be invoked via the top level <code>Makefile</code>:</p>
|
||
<pre><code> make gen_other_html</code></pre>
|
||
<div id="gen-sitemap">
|
||
<h3 id="gen-sitemap.sh"><a href="https://github.com/ioccc-src/temp-test-ioccc/blob/master/bin/gen-sitemap.sh">gen-sitemap.sh</a></h3>
|
||
</div>
|
||
<p>Generate an XML sitemap for the IOCCC website.</p>
|
||
<p>Usage:</p>
|
||
<pre><code> bin/gen-sitemap.sh -v 1</code></pre>
|
||
<p>This would generate the <a href="../sitemap.xml">sitemap.xml</a> file.</p>
|
||
<p>We recommend that this tool be invoked via the top level <code>Makefile</code>:</p>
|
||
<pre><code> make gen_sitemap</code></pre>
|
||
<div id="gen-status">
|
||
<h3 id="gen-status.sh"><a href="https://github.com/ioccc-src/temp-test-ioccc/blob/master/bin/gen-status.sh">gen-status.sh</a></h3>
|
||
</div>
|
||
<p>Generate <a href="../status.json">status.json</a> according to the modification date of
|
||
<a href="https://github.com/ioccc-src/temp-test-ioccc/blob/master/news.md">news.md</a> and/or whether the <code>contest_status</code> is changed
|
||
at the command line.</p>
|
||
<p>Without an argument, the <code>contest_status</code> is unchanged.</p>
|
||
<p>Usage:</p>
|
||
<pre><code> bin/gen-status.sh -v 1</code></pre>
|
||
<p>To force the <code>contest_status</code> to be closed:</p>
|
||
<pre><code> bin/gen-status.sh -v 1 closed</code></pre>
|
||
<p>To force the <code>contest_status</code> to be open:</p>
|
||
<pre><code> bin/gen-status.sh -v 1 open</code></pre>
|
||
<p>To see other valid statuses:</p>
|
||
<pre><code> bin/gen-status -h</code></pre>
|
||
<p>We recommend that this tool be invoked via the top level <code>Makefile</code>:</p>
|
||
<pre><code> make gen_status</code></pre>
|
||
<p>unless the <code>contest_status</code> is to be changed, but since only the judges should
|
||
do that, that is not a problem.</p>
|
||
<div id="gen-top-html">
|
||
<h3 id="gen-top-html.sh"><a href="https://github.com/ioccc-src/temp-test-ioccc/blob/master/bin/gen-top-html.sh">gen-top-html.sh</a></h3>
|
||
</div>
|
||
<p>Generate a number of top level HTML pages for the IOCCC websites.</p>
|
||
<p>Usage:</p>
|
||
<pre><code> bin/gen-top-html.sh -v 1</code></pre>
|
||
<p>Examples of top level HTML pages built by this tool include:</p>
|
||
<ul>
|
||
<li><a href="../CODE_OF_CONDUCT.html">CODE_OF_CONDUCT.html</a></li>
|
||
<li><a href="../archive/historic/index.html">archive/historic/index.html</a></li>
|
||
<li><a href="../bin/index.html">bin/index.html</a></li>
|
||
<li><a href="../bugs.html">bugs.html</a></li>
|
||
<li><a href="../contact.html">contact.html</a></li>
|
||
<li><a href="../faq.html">faq.html</a></li>
|
||
<li><a href="../inc/index.html">inc/index.html</a></li>
|
||
<li><a href="../index.html">index.html</a></li>
|
||
<li><a href="../judges.html">judges.html</a></li>
|
||
<li><a href="../news.html">news.html</a></li>
|
||
<li><a href="../thanks-for-help.html">thanks-for-help.html</a></li>
|
||
</ul>
|
||
<p>We recommend that this tool be invoked via the top level <code>Makefile</code>:</p>
|
||
<pre><code> make gen_top_html</code></pre>
|
||
<div id="gen-year-index">
|
||
<h3 id="gen-year-index.sh"><a href="https://github.com/ioccc-src/temp-test-ioccc/blob/master/bin/gen-year-index.sh">gen-year-index.sh</a></h3>
|
||
</div>
|
||
<p>Generate an <code>index.html</code> page for a given IOCCC year.</p>
|
||
<p>Usage:</p>
|
||
<pre><code> bin/gen-year-index.sh -v 1 2020</code></pre>
|
||
<p>This would create the <a href="../2020/index.html">2020/index.html</a> file.</p>
|
||
<p>We recommend that this tool be invoked via the top level <code>Makefile</code>:</p>
|
||
<pre><code> make gen_year_index</code></pre>
|
||
<p>which will create the <code>index.html</code> for every IOCCC year (<code>1984/index.html</code>,
|
||
<code>1985/index.html</code> etc.).</p>
|
||
<div id="gen-years">
|
||
<h3 id="gen-years.sh"><a href="https://github.com/ioccc-src/temp-test-ioccc/blob/master/bin/gen-years.sh">gen-years.sh</a></h3>
|
||
</div>
|
||
<p>Generate the top level <a href="../years.html">years.html</a> page.</p>
|
||
<p>Usage:</p>
|
||
<pre><code> bin/gen-years.sh -v 1</code></pre>
|
||
<p>We recommend that this tool be invoked via the top level <code>Makefile</code>:</p>
|
||
<pre><code> make gen_years</code></pre>
|
||
<div id="jfmt-wrapper">
|
||
<h3 id="jfmt-wrapper.sh"><a href="https://github.com/ioccc-src/temp-test-ioccc/blob/master/bin/jfmt-wrapper.sh">jfmt-wrapper.sh</a></h3>
|
||
</div>
|
||
<p>The <a href="https://github.com/ioccc-src/temp-test-ioccc/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/temp-test-ioccc/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/temp-test-ioccc/blob/master/bin/jprint-wrapper.sh">jprint-wrapper.sh</a></h3>
|
||
</div>
|
||
<p>The <a href="https://github.com/ioccc-src/temp-test-ioccc/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/temp-test-ioccc/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/temp-test-ioccc/blob/master/bin/jval-wrapper.sh">jval-wrapper.sh</a></h3>
|
||
</div>
|
||
<p>The <a href="https://github.com/ioccc-src/temp-test-ioccc/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/temp-test-ioccc/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/temp-test-ioccc/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/temp-test-ioccc/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/temp-test-ioccc/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/temp-test-ioccc/blob/master/bin/md2html.sh">md2html.sh</a></h3>
|
||
</div>
|
||
<p>This is the primary tool that forms IOCCC generated HTML content from
|
||
markdown files (permanent markdown files or temporarily generated
|
||
markdown files) and HTML fragments from the <a href="../inc/index.html">inc directory</a>.</p>
|
||
<p>The <a href="index.html#md2html_cfg">md2html.cfg</a> configuration file is
|
||
used by <a href="https://github.com/ioccc-src/temp-test-ioccc/blob/master/bin/md2html.sh">md2html.sh</a> to drive the generation process.</p>
|
||
<div id="new-dir">
|
||
<h3 id="new-dir.sh"><a href="https://github.com/ioccc-src/temp-test-ioccc/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/temp-test-ioccc/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 (<code><!-- XXX --></code>) 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/temp-test-ioccc/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/temp-test-ioccc/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/temp-test-ioccc/blob/master/bin/md2html.cfg">bin/md2html.cfg</a> file as part of
|
||
the <a href="index.html#md2html">md2html tool</a>.</p>
|
||
<div id="output-index-inventory">
|
||
<h3 id="output-index-inventory.sh"><a href="https://github.com/ioccc-src/temp-test-ioccc/blob/master/bin/output-index-inventory.sh">output-index-inventory.sh</a></h3>
|
||
</div>
|
||
<p>Output the inventory in HTML form for an entry’s index.html page. For an example
|
||
inventory, see the <a href="../1984/anonymous/index.html#inventory">inventory in
|
||
1984/anonymous</a>.</p>
|
||
<p>This tool is used in the <a href="https://github.com/ioccc-src/temp-test-ioccc/blob/master/bin/md2html.cfg">bin/md2html.cfg</a> file as part of
|
||
the <a href="index.html#md2html">md2html tool</a>.</p>
|
||
<div id="output-year-index">
|
||
<h3 id="output-year-index.sh"><a href="https://github.com/ioccc-src/temp-test-ioccc/blob/master/bin/output-year-index.sh">output-year-index.sh</a></h3>
|
||
</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/temp-test-ioccc/blob/master/bin/md2html.cfg">bin/md2html.cfg</a> file as part of
|
||
the <a href="index.html#md2html">md2html tool</a>.</p>
|
||
<div id="pandoc-wrapper">
|
||
<h3 id="pandoc-wrapper.sh"><a href="https://github.com/ioccc-src/temp-test-ioccc/blob/master/bin/pandoc-wrapper.sh">pandoc-wrapper.sh</a></h3>
|
||
</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/temp-test-ioccc/blob/master/bin/quick-readme2index.sh">quick-readme2index.sh</a></h3>
|
||
</div>
|
||
<p>Build an entry’s <code>index.html</code> file if the entry directory
|
||
does not have a non-empty <code>index.hmtl</code> file, or if either
|
||
<code>.entry.json</code> or <code>README.md</code> is newer than the <code>index.hmtl</code> file.</p>
|
||
<p>This is useful when only a few entries have been
|
||
modified (resulting in an updated <code>.entry.json</code> file)
|
||
or if the <code>README.md</code> of a few entries have been changed: while the
|
||
<a href="index.html#readme2index">readme2index.sh</a> script takes a few seconds
|
||
to run for a few entries, when applied to 300+ entries, the extra time can add
|
||
up.</p>
|
||
<p>If only a few <code>index.hmtl</code> files need updating, then
|
||
this command will only briefly pause while the
|
||
<a href="index.html#readme2index">readme2index.sh</a> can take much longer.</p>
|
||
<p>Usage:</p>
|
||
<pre><code> # For all entries:
|
||
bin/all-run.sh -v 3 bin/quick-readme2index.sh -v 1
|
||
|
||
# For an individual entry:
|
||
bin/quick-readme2index.sh -v 1 2020/ferguson2</code></pre>
|
||
<p><strong>NOTE</strong>: This command assumes that the relative
|
||
modification times for <code>README.md</code>, <code>.entry.json</code>,
|
||
and <code>index.html</code> are correct. If in doubt, use
|
||
<a href="index.html#readme2index">readme2index.sh</a>.</p>
|
||
<p>We recommend that this tool be invoked via the top level <code>Makefile</code>:</p>
|
||
<pre><code> make quick_readme2index</code></pre>
|
||
<div id="readme2index">
|
||
<h3 id="readme2index.sh"><a href="https://github.com/ioccc-src/temp-test-ioccc/blob/master/bin/readme2index.sh">readme2index.sh</a></h3>
|
||
</div>
|
||
<p>Convert an entry’s <code>README.md</code> into its <code>index.html</code> file.</p>
|
||
<p>Usage:</p>
|
||
<pre><code> bin/readme2index.sh -v 3 1984/mullender</code></pre>
|
||
<p>To build <code>index.html</code> files for all entries:</p>
|
||
<pre><code> bin/all-run.sh -v 3 bin/readme2index.sh -v 1</code></pre>
|
||
<p>We recommend that this tool be invoked via the top level <code>Makefile</code>:</p>
|
||
<pre><code> make entry_index</code></pre>
|
||
<div id="sgi">
|
||
<h3 id="sgi.sh"><a href="https://github.com/ioccc-src/temp-test-ioccc/blob/master/bin/sgi.sh">sgi.sh</a></h3>
|
||
</div>
|
||
<p>Sort <code>.gitignore</code> content from <code>stdin</code> to <code>stdout</code>.</p>
|
||
<p>We sort with lines starting with <code>#</code> first.
|
||
We sort with lines starting with <code>*</code> second.
|
||
We sort with lines that do not start with <code>[#!*]</code> third.
|
||
We sort with lines starting with <code>!</code> fourth.</p>
|
||
<p>This tool is used by <a href="index.html#sort-gitignore">sort.gitignore.sh</a>.</p>
|
||
<div id="sort-gitignore">
|
||
<h3 id="sort.gitignore.sh"><a href="https://github.com/ioccc-src/temp-test-ioccc/blob/master/bin/sort.gitignore.sh">sort.gitignore.sh</a></h3>
|
||
</div>
|
||
<p>Sort a <code>.gitignore</code> in a entry directory.</p>
|
||
<p>Usage:</p>
|
||
<pre><code> bin/sort.gitignore.sh -v 1 YYYY/dir</code></pre>
|
||
<p>Suggested usage (for all <code>.gitignore</code> files):</p>
|
||
<pre><code> bin/all-run.sh bin/sort.gitignore.sh -v 1</code></pre>
|
||
<p>We recommend that this tool be invoked via the top level <code>Makefile</code>:</p>
|
||
<pre><code> make sort_gitignore</code></pre>
|
||
<div id="status2html">
|
||
<h3 id="status2html.sh"><a href="https://github.com/ioccc-src/temp-test-ioccc/blob/master/bin/status2html.sh">status2html.sh</a></h3>
|
||
</div>
|
||
<p>Convert <a href="../status.json">status.json</a> into HTML.</p>
|
||
<p>This tool is a ‘before tool’ (<code>-b tool</code>) that is intended
|
||
to be used by <a href="index.html#gen-status">gen-status.sh</a>.</p>
|
||
<div id="subst-default">
|
||
<h3 id="subst.default.sh"><a href="https://github.com/ioccc-src/temp-test-ioccc/blob/master/bin/subst.default.sh">subst.default.sh</a></h3>
|
||
</div>
|
||
<p>Print default substitutions.</p>
|
||
<p>This tool is used in the <a href="https://github.com/ioccc-src/temp-test-ioccc/blob/master/bin/md2html.cfg">bin/md2html.cfg</a> file.</p>
|
||
<div id="subst-entry-index">
|
||
<h3 id="subst.entry-index.sh"><a href="https://github.com/ioccc-src/temp-test-ioccc/blob/master/bin/subst.entry-index.sh">subst.entry-index.sh</a></h3>
|
||
</div>
|
||
<p>Print substitutions for an entry’s <code>index.html</code>.</p>
|
||
<p>This tool is used in the <a href="https://github.com/ioccc-src/temp-test-ioccc/blob/master/bin/md2html.cfg">bin/md2html.cfg</a> file.</p>
|
||
<div id="subst-entry-navbar-awk">
|
||
<h3 id="subst.entry-navbar.awk"><a href="https://github.com/ioccc-src/temp-test-ioccc/blob/master/bin/subst.entry-navbar.awk">subst.entry-navbar.awk</a></h3>
|
||
</div>
|
||
<p>Output substitutions for <code>navbar</code> on behalf of an entry.</p>
|
||
<p>This tool is used in <a href="index.html#subst-entry-index">subst.entry-index.sh</a>.</p>
|
||
<div id="subst-year-index">
|
||
<h3 id="subst.year-index.sh"><a href="https://github.com/ioccc-src/temp-test-ioccc/blob/master/bin/subst.year-index.sh">subst.year-index.sh</a></h3>
|
||
</div>
|
||
<p>Print substitutions for a year level <code>index.html</code>.</p>
|
||
<p>This tool is used in the <a href="https://github.com/ioccc-src/temp-test-ioccc/blob/master/bin/md2html.cfg">bin/md2html.cfg</a> file.</p>
|
||
<div id="subst-year-navbar-awk">
|
||
<h3 id="subst.year-navbar.awk"><a href="https://github.com/ioccc-src/temp-test-ioccc/blob/master/bin/subst.year-navbar.awk">subst.year-navbar.awk</a></h3>
|
||
</div>
|
||
<p>Output substitutions for <code>navbar</code> on behalf of a year level <code>index.html</code>.</p>
|
||
<p>This tool is used in <a href="index.html#subst-year-index">subst.year-index.sh</a>.</p>
|
||
<div id="tar-entry">
|
||
<h2 id="tar-entry.sh"><a href="https://github.com/ioccc-src/temp-test-ioccc/blob/master/bin/tar-entry.sh">tar-entry.sh</a></h2>
|
||
</div>
|
||
<p>Form a compressed tarball for an entry.</p>
|
||
<p>Usage:</p>
|
||
<pre><code> bin/tar-entry.sh -v 1 YYYY/dir</code></pre>
|
||
<p>Suggested usage:</p>
|
||
<pre><code> bin/all-run.sh -v 3 bin/tar-entry.sh -v 1 -W</code></pre>
|
||
<div id="tar-year">
|
||
<h2 id="tar-year.sh"><a href="https://github.com/ioccc-src/temp-test-ioccc/blob/master/bin/tar-year.sh">tar-year.sh</a></h2>
|
||
</div>
|
||
<p>Form a compressed tarball for an IOCCC year.</p>
|
||
<p>Usage:</p>
|
||
<pre><code> bin/tar-year.sh -v 1 YYYY</code></pre>
|
||
<p>Suggested usage:</p>
|
||
<pre><code> bin/all-years.sh -v 3 bin/tar-year.sh -v 1 -W</code></pre>
|
||
<p>We recommend that this tool be invoked via the top level <code>Makefile</code>:</p>
|
||
<pre><code> make form_year_tarball</code></pre>
|
||
<div id="untar-entry">
|
||
<h2 id="untar-entry.sh"><a href="https://github.com/ioccc-src/temp-test-ioccc/blob/master/bin/untar-entry.sh">untar-entry.sh</a></h2>
|
||
</div>
|
||
<p>Untar an entry’s compressed tarball.</p>
|
||
<p>Usage:</p>
|
||
<pre><code> bin/untar-entry.sh -v 1 YYYY/dir</code></pre>
|
||
<p>Suggested usage:</p>
|
||
<pre><code> bin/all-run.sh -v 3 bin/untar-entry.sh -v 1</code></pre>
|
||
<p>We recommend that this tool be invoked via the top level <code>Makefile</code>:</p>
|
||
<pre><code> make untar_entry_tarball</code></pre>
|
||
<div id="untar-year">
|
||
<h2 id="untar-year.sh"><a href="https://github.com/ioccc-src/temp-test-ioccc/blob/master/bin/untar-year.sh">untar-year.sh</a></h2>
|
||
</div>
|
||
<p>Untar an IOCCC year’s compressed tarball.</p>
|
||
<p>Usage:</p>
|
||
<pre><code> bin/untar-year.sh -v 1 YYYY</code></pre>
|
||
<p>Suggested usage:</p>
|
||
<pre><code> bin/all-years.sh -v 3 bin/untar-year.sh -v 1</code></pre>
|
||
<p>We recommend that this tool be invoked via the top level <code>Makefile</code>:</p>
|
||
<pre><code> make untar_year_tarball</code></pre>
|
||
<div id="how">
|
||
<h1 id="how-ioccc-html-content-is-built">How IOCCC HTML content is built</h1>
|
||
</div>
|
||
<p>The <a href="index.html#md2html">md2html.sh</a> tool is the primary tool that
|
||
is used to form all IOCCC related HTML pages for the <a href="https://www.ioccc.org">official IOCCC web
|
||
site</a>.</p>
|
||
<p>Nearly all IOCCC related HTML pages are built from markdown files,
|
||
from either permanent markdown files or temporary generated markdown files,
|
||
as well as HTML fragments from the <a href="../inc/index.html">inc directory</a>.</p>
|
||
<p>Most HTML content is built from permanent markdown files, such as a <code>README.md</code>
|
||
markdown file found in each entry directory. Some HTML content are generated
|
||
from temporary markdown files. These temporary markdown files are produced by
|
||
tools in the <a href="index.html">bin directory</a> and exist only while the tool is running.</p>
|
||
<p>In addition to converting markdown to HTML, the canonical way that HTML content is
|
||
built uses, by default, files from the <a href="../inc/index.html">inc directory</a>, of
|
||
the file name form:</p>
|
||
<pre><code> *.default.html</code></pre>
|
||
<p>By using command line options of the form:</p>
|
||
<pre><code> -H phase=name</code></pre>
|
||
<p>where <code>phase</code> is the name of an HTML phase,
|
||
a non-default file may be used. For example:</p>
|
||
<pre><code> -H navbar=up2index</code></pre>
|
||
<p>will cause <a href="../inc/navbar.up2index.html">inc/navbar.up2index.html</a>
|
||
instead of <a href="../inc/navbar.default.html">inc/navbar.default.html</a> to be
|
||
used during the <em>navbar</em> HTML phase.</p>
|
||
<p>If <code>name</code> is dot (i.e., <code>.</code>), then the given HTML phase is skipped.
|
||
For example:</p>
|
||
<pre><code> -H footer=.</code></pre>
|
||
<p>will cause no HTML content to be produced during the <code>footer</code> HTML phase.</p>
|
||
<div id="html">
|
||
<h2 id="html-phases">HTML phases</h2>
|
||
</div>
|
||
<p>The following HTML phase files are used to build HTML content:</p>
|
||
<ol start="0" type="1">
|
||
<li><a href="../inc/top.default.html">inc/top.default.html</a></li>
|
||
<li><a href="../inc/head.default.html">inc/head.default.html</a></li>
|
||
<li><a href="../inc/body.default.html">inc/body.default.html</a></li>
|
||
<li><a href="../inc/topbar.default.html">inc/topbar.default.html</a></li>
|
||
<li><a href="../inc/header.default.html">inc/header.default.html</a></li>
|
||
<li><a href="../inc/navbar.default.html">inc/navbar.default.html</a></li>
|
||
<li><a href="../inc/before-content.default.html">inc/before-content.default.html</a></li>
|
||
</ol>
|
||
<p>Phases 7-19 are reserved for future use.</p>
|
||
<ol start="20" type="1">
|
||
<li>((insert ‘before tool’ output))</li>
|
||
<li>((insert ‘pandoc wrapper tool’ output))</li>
|
||
<li>((insert ‘after tool’ output))</li>
|
||
</ol>
|
||
<p>Phases 23-29 are reserved for future use.</p>
|
||
<ol start="30" type="1">
|
||
<li><a href="../inc/after-content.default.html">inc/after-content.default.html</a></li>
|
||
<li><a href="../inc/footer.default.html">inc/footer.default.html</a></li>
|
||
<li><a href="../inc/bottom.default.html">inc/bottom.default.html</a></li>
|
||
</ol>
|
||
<p>Phases 33-39 are reserved for future use.</p>
|
||
<p>In all of the above HTML phase numbers, symbols of the form <code>%%TOKEN%%</code> are
|
||
substituted.</p>
|
||
<p>Substitutions of the form <code>%%TOKEN%%</code> are performed on included HTML content,
|
||
content generated by the ‘before tool’ (<code>-b tool</code>),
|
||
content generated by the ‘after tool’ (<code>-a tool</code>),
|
||
as well as the markdown content given to the <code>pandoc wrapper tool</code> (<code>-p tool</code>).</p>
|
||
<p>It is an error, unless <code>-S</code> is given, for any phase, except phases HTML
|
||
20-29, to not substitute all <code>%%TOKEN%%</code>s. For phases HTML 20-29, any
|
||
<code>%%TOKEN%%</code> that is not substituted are passed thru without substitution.</p>
|
||
<p>See the tool <a href="index.html#readme2index">readme2index.sh</a> for an example of
|
||
how HTML phases are implemented.</p>
|
||
<div id="getopt">
|
||
<h2 id="getopt-phase-processing-of-the-command-line">getopt phase processing of the command line</h2>
|
||
</div>
|
||
<p>The command options are evaluated in the following <code>getopt</code> phases:</p>
|
||
<div id="getopt-0">
|
||
<h3 id="getopt-phase-0"><code>getopt</code> phase 0</h3>
|
||
</div>
|
||
<p>In <code>getopt</code> phase 0 we parse command line options and save all arguments for the
|
||
end of the final command line.</p>
|
||
<p>Depending on the program, the argument at the end is directory under topdir, or
|
||
it is a file under topdir.</p>
|
||
<p><code>getopt</code> phase 0 is the only <code>getopt</code> phase where <code>-d topdir</code> and <code>-c md2html.cfg</code> may be used.</p>
|
||
<div id="getopt-1">
|
||
<h3 id="getopt-phase-1"><code>getopt</code> phase 1</h3>
|
||
</div>
|
||
<p>In <code>getopt</code> phase 1 we execute each <code>-o "output tool"</code> from <code>getopt</code> phase 0,
|
||
parsing the output as a command line.</p>
|
||
<p>The <code>-o "output tool"</code> may be given <code>optstr</code> from <code>"-O tool=optstr"</code>, followed
|
||
by the phase 0 argument.</p>
|
||
<p>The <code>-o "output tool"</code> is not allowed to output another <code>"-o tool"</code> or a <code>"-O tool=optstr"</code>. Instead a <code>-o "output tool"</code> may execute another <code>-o "output tool"</code> and merge the output into its own.</p>
|
||
<div id="getopt-2">
|
||
<h3 id="getopt-phase-2"><code>getopt</code> phase 2</h3>
|
||
</div>
|
||
<p>In <code>getopt</code> phase 2 we parse the <code>cfg_options</code> from the first <code>md2html.cfg</code> line
|
||
matched by a saved argument.</p>
|
||
<p>The match is made with the (possibly modified) phase 0 argument.</p>
|
||
<div id="getopt-3">
|
||
<h3 id="getopt-phase-3"><code>getopt</code> phase 3</h3>
|
||
</div>
|
||
<p>In <code>getopt</code> phase 3 we execute each <code>-o "output tool"</code> from <code>getopt</code> phase 2,
|
||
parsing the output as a command line.</p>
|
||
<p>The <code>-o "output tool"</code> may be given <code>optstr</code> from <code>"-O tool=optstr"</code>, followed
|
||
by the phase 0 argument.</p>
|
||
<p>The <code>-o "output tool"</code> is not allowed to output another <code>"-o tool"</code> or a <code>"-O tool=optstr"</code>. Instead a <code>-o "output tool"</code> may execute another <code>-o "output tool"</code> and merge the output into its own.</p>
|
||
<h3 id="command-line-option-order">Command line option order</h3>
|
||
<p>Most command line options override earlier copies of the same option. However
|
||
in the case of <code>-H phase=name</code>, a later <code>-H phase=name</code> only overrides an
|
||
earlier use of <code>-H</code> for the same <code>phase</code> <em>only</em>. Also in the case of <code>-s token=value</code>, a later <code>-s token=value</code> only overrides an earlier use of <code>-s</code> for
|
||
the same <code>token</code> <em>only</em>.</p>
|
||
<h3 id="output-tools">Output tools</h3>
|
||
<p>An “output tool” may be used to add certain additional command line options to be processed.</p>
|
||
<p><strong>IMPORTANT</strong>: An “output tool” will print each command line option / argument on a separate line.
|
||
So for example, if an “output tool” wishes to convey:</p>
|
||
<pre><code> -s TITLE='IOCCC entry locations' -H navbar=top-of-site</code></pre>
|
||
<p>The “output tool” would output the following 4 lines:</p>
|
||
<pre><code> -s
|
||
TITLE='IOCCC entry locations'
|
||
-H
|
||
navbar=top-of-site</code></pre>
|
||
<p>The command line options printed by an “output tool” are processed
|
||
after all command line options, and all options from a matching
|
||
line from the <a href="https://github.com/ioccc-src/temp-test-ioccc/blob/master/bin/md2html.cfg">md2html.cfg</a> file, and before any filename arguments
|
||
on the command line.</p>
|
||
<p>For example:</p>
|
||
<pre><code> command [command_options ..] [cfg_options ..] [output_tool_options ..] [--] [filename_arg ..]</code></pre>
|
||
<p>Here the <code>command</code> first processes any command line options, then it processes
|
||
<code>cfg_options</code> obtained from this file from a first match of a given <code>file_glob</code>,
|
||
then it processes <code>output tool</code> (i.e., <code>-o tool</code>) options found in
|
||
<code>command_options</code>, and <code>cfg_options</code>, then an optional <code>--</code> (end of all
|
||
options), then zero of more <code>filename_arg</code> filename arguments.</p>
|
||
<p>The <code>-o tool</code> must <strong>NOT</strong> output any <code>-o tool</code> options as <code>-o tool</code> is <strong>NOT
|
||
RECURSIVE</strong>. A <code>-o tool</code> is free, however, to execute other <code>-o tool</code> output
|
||
tools and merge the output from those tools into its own.</p>
|
||
<div id="special-exit-code">
|
||
<h3 id="special--e-exitcode-option">Special <code>-E exitcode</code> option</h3>
|
||
</div>
|
||
<p>When <code>-E exitcode</code> is evaluated, the application will exit with the <code>exitcode</code>
|
||
value. If one wishes to also output a message to <code>stderr</code>, the <code>-e string</code> must
|
||
come <strong>BEFORE</strong> any <code>-E exitcode</code> in the command line.</p>
|
||
<h3 id="substitution-tokens">Substitution tokens</h3>
|
||
<p>All tokens (i.e., strings of the form <code>%%token%%</code>) <strong>MUST</strong> be substituted (by
|
||
some <code>-s token=value</code>) in all HTML output, except during phase numbers 20-29
|
||
(i.e., except <code>before tool</code> output, pandoc wrapper output, and <code>after tool</code>
|
||
output), or the command will exit non-zero, unless <code>-S</code> is given. If <code>-S</code> is
|
||
given, only a warning about non-substituted tokens will be written to <code>stderr</code>.</p>
|
||
<p>The command line of tools in the <a href="index.html">bin directory</a>, and perhaps
|
||
modified via the <a href="https://github.com/ioccc-src/temp-test-ioccc/blob/master/bin/md2html.cfg">md2html config file</a> may change to using a
|
||
different filename for a given phase.</p>
|
||
<p>For example when forming the HTML from
|
||
<a href="https://github.com/ioccc-src/temp-test-ioccc/blob/master/2020/ferguson1/chocolate-cake.md">2020/ferguson1/chocolate-cake.md</a>,
|
||
a different <code>navbar</code> navigation bar is needed. So instead of the
|
||
usual top navigation bar that normally directs people to the previous
|
||
entry for the year, or go up to the year page, or to the next entry
|
||
for the year, a top navigation bar to just go up to the entry’s
|
||
main page is needed. A line in the <a href="https://github.com/ioccc-src/temp-test-ioccc/blob/master/bin/md2html.cfg">md2html config file</a>
|
||
that refers to
|
||
<a href="https://github.com/ioccc-src/temp-test-ioccc/blob/master/2020/ferguson1/chocolate-cake.md">2020/ferguson1/chocolate-cake.md</a> may
|
||
specify use of <code>navbar.up2index.html</code> (as <code>navbar.up2index</code>)instead of using the
|
||
<code>navbar.default.html</code> (<code>navbar.default.html</code>) default.</p>
|
||
<p>The HTML phase may be skipped resulting in no HTML output during a given phase
|
||
and furthermore, forming no HTML content from a given markdown file altogether.</p>
|
||
<p>See comments in the <a href="https://github.com/ioccc-src/temp-test-ioccc/blob/master/bin/md2html.cfg">md2html config file</a> for details.
|
||
See also, the tool <a href="index.html#readme2index">readme2index.sh</a> for an example of
|
||
how such command lines are used.</p>
|
||
<h1 id="use-caution-when-modifying-inc-files">Use CAUTION when modifying <code>inc/</code> files</h1>
|
||
<p>Some of the files under this directory are used to form <strong>MOST</strong> of the HTML content
|
||
on the <a href="https://www.ioccc.org">official IOCCC website</a>.</p>
|
||
<p>These files are used to form <strong>MOST</strong> of the HTML content
|
||
on the <a href="https://ioccc-src.github.io/temp-test-ioccc/">experimental website</a>.</p>
|
||
<p>… and in particular files under <a href="../inc/index.html">inc</a> that are of the form
|
||
(called default HTML files) …:</p>
|
||
<pre><code> *.default.html</code></pre>
|
||
<p>… contain default content used to form IOCCC HTML / IOCCC web pages.</p>
|
||
<p>Instead of editing the default HTML files in order to fix a special web page,
|
||
consider making a copy of the default file and modifying the <a href="https://github.com/ioccc-src/temp-test-ioccc/blob/master/bin/md2html.cfg">md2html config
|
||
file</a> to refer to the copy instead. That way your special case
|
||
situation will not impact <strong>MOST</strong> of the HTML content.</p>
|
||
<h1 id="why-we-do-not-use-certain-well-known-html-technologies">Why we do not use certain well-known HTML technologies</h1>
|
||
<p>You may wonder why we need these files in the first place. You may wonder why
|
||
we even need the tools in the <a href="index.html">bin</a> directory when there other
|
||
solutions available to form web pages.</p>
|
||
<div id="static-only">
|
||
<h2 id="static-web-pages-only">Static web pages only</h2>
|
||
</div>
|
||
<p>Here are some reasons why we are using these files and
|
||
special tools to create HTML content / IOCCC web pages:</p>
|
||
<p>We host <a href="https://www.ioccc.org">official IOCCC website</a> via <a href="https://pages.github.com">GitHub
|
||
pages</a>. As of the time this file written, <strong>only
|
||
static web pages are supported</strong>.</p>
|
||
<h2 id="we-cannot-use-server-side-include">We cannot use server side include</h2>
|
||
<p>We use <a href="#static-only">static web pages</a>, so use of “server side include” is not
|
||
available to the IOCCC.</p>
|
||
<p>For example, Apache SSI <code>#include</code> does not work on <a href="https://pages.github.com">GitHub
|
||
pages</a>.</p>
|
||
<h2 id="we-cannot-use-a-back-end-database">We cannot use a back-end database</h2>
|
||
<p>We use <a href="index.html#static-only">static web pages</a>, so use of a “back-end database” is not
|
||
available to the IOCCC.</p>
|
||
<div id="why-github">
|
||
<h2 id="we-cannot-use-non-github-web-servers">We cannot use non-GitHub web servers</h2>
|
||
</div>
|
||
<p>The <a href="https://pages.github.com">GitHub pages</a> have the distributed server capacity needed to handle
|
||
the <strong>huge download volume</strong> or <a href="https://en.wikipedia.org/wiki/Slashdot_effect">Slashdot effect</a>
|
||
that happens when 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 web
|
||
site</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/temp-test-ioccc/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-2024 by Landon Curt Noll. All Rights Reserved.
|
||
|
||
You are free to share and adapt this file under the terms of this license:
|
||
|
||
Creative Commons Attribution-ShareAlike 4.0 International (CC BY-SA 4.0)
|
||
|
||
For more information, see:
|
||
|
||
https://creativecommons.org/licenses/by-sa/4.0/
|
||
|
||
-->
|
||
<!-- AFTER: last line of markdown file: bin/README.md -->
|
||
|
||
<!-- END: this line ends content for HTML phase 21 by: bin/pandoc-wrapper.sh via bin/md2html.sh -->
|
||
<!-- START: this line starts content from: inc/after-content.default.html -->
|
||
|
||
</div>
|
||
|
||
<!-- END: this line ends content from: inc/after-content.default.html -->
|
||
<!-- START: this line starts content from: inc/footer.default.html -->
|
||
|
||
<!--
|
||
|
||
Copyright © 1984-2024 by Landon Curt Noll. All Rights Reserved.
|
||
|
||
You are free to share and adapt this file under the terms of this license:
|
||
|
||
Creative Commons Attribution-ShareAlike 4.0 International (CC BY-SA 4.0)
|
||
|
||
For more information, see:
|
||
|
||
https://creativecommons.org/licenses/by-sa/4.0/
|
||
|
||
-->
|
||
|
||
<div class="footer">
|
||
|
||
<div id="copyright"><h3>Copyright © 1984-2024 by Landon Curt Noll:
|
||
<a href="https://creativecommons.org/faq/#what-does-some-rights-reserved-mean"
|
||
target="_blank"
|
||
rel="license noopener noreferrer">Some Rights Reserved</a></h3>
|
||
<p>
|
||
This work is <b>licensed by Landon Curt Noll</b> under
|
||
<b><a href="https://creativecommons.org/licenses/by-sa/4.0/?ref=chooser-v1"
|
||
target="_blank"
|
||
rel="license noopener noreferrer"
|
||
style="display:inline-block;">CC BY-SA 4.0</a></b>.
|
||
<img style="height:22px!important;margin-left:3px;vertical-align:text-bottom;"
|
||
src="../png/cc.png"
|
||
alt="cc inside circle symbol">
|
||
<img style="height:22px!important;margin-left:3px;vertical-align:text-bottom;"
|
||
src="../png/by.png"
|
||
alt="person inside circle symbol">
|
||
<img style="height:22px!important;margin-left:3px;vertical-align:text-bottom;"
|
||
src="../png/sa.png"
|
||
alt="arrow looping back on itself inside circle symbol"><br>
|
||
You should <b>carefully review</b> the
|
||
<b><a href="https://creativecommons.org/licenses/by-sa/4.0/legalcode.en"
|
||
target="_blank"
|
||
rel="license noopener noreferrer">CC BY-SA 4.0 LEGAL CODE</a></b>
|
||
before using the licensed material.<br>
|
||
You may wish to review the
|
||
<b><a href="../license.html"
|
||
target="_blank"
|
||
rel="license noopener noreferrer">highlights of some of the key features and terms</a></b>
|
||
of <b>CC BY-SA 4.0</b>.<br>
|
||
</p>
|
||
</div>
|
||
|
||
<div id="coda"><h3>Coda</h3>
|
||
<p>
|
||
<a href="https://validator.w3.org/nu/?doc=https%3A%2F%2Fioccc-src.github.io%2Ftemp-test-ioccc%2Fbin%2Findex.html" rel="nofollow">Nu HTML check this web page</a><br>
|
||
<a href="#top">Jump to top</a> <a href="#content">Jump to Content</a>
|
||
</p>
|
||
</div>
|
||
|
||
</div>
|
||
|
||
<!-- END: this line ends content from: inc/footer.default.html -->
|
||
<!-- START: this line starts content from: inc/bottom.default.html -->
|
||
|
||
</body>
|
||
</html>
|
||
|
||
<!-- END: this line ends content from: inc/bottom.default.html -->
|