mirror/ioccc
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Merge pull request #2602 from xexyl/entry-json-faq

Browse Source
This commit is contained in:
Landon Curt Noll authored and GitHub committed 2024-07-26 22:12:48 -07:00
2 parents 9f7f389695 15713291d3
commit fb2d5ba8a3
4 files changed
+811 -45
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

bin/README.md
+43 -19
View File
@@ -25,7 +25,7 @@ If you need to remember the syntax of the tool or get certain notes about
different options, you can use the `-h` option.
For instance if you want help on the [all-run.sh](index.html#all-run) tool
from the root directory, you would do:
from the root directory (of the repo/website), you would do:
``` <!---sh-->
@@ -35,7 +35,7 @@ from the root directory, you would do:
### Set verbosity level of a tool
If, however, you want verbosity, say for debugging purposes or to see what is
If you want verbosity, say for debugging purposes or to see what is
going on more, you should use the `-v level` option. For instance if you wish to
see what is going on with the
[quick-readme2index.sh](index.html#quick-readme2index) tool, you might do:
@@ -61,7 +61,7 @@ is, you would do:
```
### Other notes
### Other notes about some of the common options
These options, and especially `-h` and `-v level`, can be very useful to get
basic usage information and to see what is going on when the tool is running.
@@ -70,16 +70,16 @@ you go through each tool, if you need to understand more of it, we recommend
that you use the `-h` option on it first.
There are some scripts that are invoked by the
[bin/md2html.cfg](%%REPO_URL%%/bin/md2html.cfg) 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.
[bin/md2html.cfg](%%REPO_URL%%/bin/md2html.cfg) 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.
<div id="add-dir">
### [add-dir.sh](%%REPO_URL%%/bin/add-dir.sh)
</div>
This tool is used my the [Judges](../judges.html) as part of the final
This tool is used by the [Judges](../judges.html) as part of the final
steps to announce a new winning IOCCC entry.
Usage:
@@ -89,7 +89,7 @@ Usage:
bin/add-dir.sh YYYY/dir
```
Here, `YYYY/dir` must the path to the winning IOCCC entry.
Here, `YYYY/dir` must be the path to the winning IOCCC entry.
<div id="all-run">
@@ -134,8 +134,8 @@ Alternate usage:
### [chk-entry.sh](%%REPO_URL%%/bin/chk-entry.sh)
</div>
Check an entry directory to verify that both the files in its manifest
(`.entry.json`) exist and that no other files exist.
Check an entry directory to verify that all the files in its manifest
(`.entry.json`) exist in the git repo.
Usage:
@@ -150,6 +150,9 @@ the top level `Makefile`:
make verify_entry_files
```
**NOTE**: see the
FAQ on "[.entry.json files](../faq.html#entry_json)"
for more details on `.entry.json` files.
<div id="csv2entry">
### [csv2entry.sh](%%REPO_URL%%/bin/csv2entry.sh)
@@ -173,8 +176,9 @@ Usage:
bin/csv2entry.sh -v 1
```
There is no requirement to sort the CSV files, nor convert
them to UNIX format, nor append a final newline to the file.
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.
This tool will canonicalize the CSV files before using them
as input. Thus, if one wishes to import the CSV file into
@@ -189,6 +193,10 @@ an unquoted `NULL` or `null`, fields that start with whitespace,
fields that end with whitespace, or fields that contain consecutive
whitespace characters.
**NOTE**: see the
FAQ on "[.entry.json files](../faq.html#entry_json)"
for more details on `.entry.json` files.
#### Internal details of `bin/csv2entry.sh`
@@ -222,13 +230,29 @@ content).
### [cvt-submission.sh](%%REPO_URL%%/bin/cvt-submission.sh)
</div>
Given a submission (that has won the IOCCC), with a `.auth.json`
and `.info.json` and NO `.entry.json` file, we convert the
This tool is used by the [Judges](../judges.html) as part of the final
steps to announce a new set of winning IOCCC entries.
Given a submission (that has won the IOCCC and thus will become an entry), with a `.auth.json`
and `.info.json` and **NO** `.entry.json` file (since it just won), we convert the
`.auth.json` and `.info.json` into a new `.entry.json` file.
We will also form, as needed, new `author/author_handle.json`
files for new authors, and update `author/author_handle.json`
for authors who won previously.
This tool will, given a submission that has won the IOCCC (and thus will become a published entry), with
a `.auth.json` and `.info.json` and NO `.entry.json` file (since it's new), we
convert the `.auth.json` and `.info.json` into a new `.entry.json` file.
**NOTE**: the `.auth.json` and `.info.json` files are formed by the
`mkiocccentry(1)` tool from the [mkiocccentry GitHub
repo](https://github.com/ioccc-src/mkiocccentry) as part of packaging
submissions.
We will also form new `author/author_handle.json` (see the
FAQ on "[author_handle.json files](../faq.html#author_json)"
for more information) and update `author/author_handle.json`
for [authors](../authors.html) who previously won. See also the
FAQ on "[author_handle](../faq.html#author_handle_faq)".
See also the
FAQ on "[.entry.json](../faq.html#entry_json)".
Usage:
@@ -237,7 +261,7 @@ Usage:
```
Here, `YYYY/dir` is the path of the submission under the `YYYY`
year directory.
year directory. For instance
<div id="entry2csv">
@@ -598,7 +622,7 @@ the [md2html tool](index.html#md2html).
### [new-year.sh](%%REPO_URL%%/bin/new-year.sh)
</div>
This tool is used my the [Judges](../judges.html) as part of the final
This tool is used by the [Judges](../judges.html) as part of the final
steps to announce a new set of winning IOCCC entries.
Usage:
bin/index.html
+39 -19
View File
@@ -407,10 +407,10 @@ help, diagnose problems, see progress etc. These options are as follows:</p>
<p>If you need to remember the syntax of the tool or get certain notes about
different options, you can use the <code>-h</code> option.</p>
<p>For instance if you want help on the <a href="index.html#all-run">all-run.sh</a> tool
from the root directory, you would do:</p>
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, however, you want verbosity, say for debugging purposes or to see what is
<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>
@@ -423,25 +423,25 @@ for some tools, set a verbosity level.</p>
For instance to see what version the <a href="index.html#chk-entry">chk-entry.sh</a> tool
is, you would do:</p>
<pre><code> bin/chk-entry.sh -V</code></pre>
<h3 id="other-notes">Other notes</h3>
<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>
<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="add-dir">
<h3 id="add-dir.sh"><a href="https://github.com/ioccc-src/temp-test-ioccc/blob/master/bin/add-dir.sh">add-dir.sh</a></h3>
</div>
<p>This tool is used my the <a href="../judges.html">Judges</a> as part of the final
<p>This tool is used by the <a href="../judges.html">Judges</a> as part of the final
steps to announce a new winning IOCCC entry.</p>
<p>Usage:</p>
<pre><code> mkdir -p YYYY/dir
bin/add-dir.sh YYYY/dir</code></pre>
<p>Here, <code>YYYY/dir</code> must the path to the winning IOCCC entry.</p>
<p>Here, <code>YYYY/dir</code> must be the path to the winning IOCCC entry.</p>
<div id="all-run">
<h3 id="all-run.sh"><a href="https://github.com/ioccc-src/temp-test-ioccc/blob/master/bin/all-run.sh">all-run.sh</a></h3>
</div>
@@ -461,13 +461,16 @@ steps to announce a new winning IOCCC entry.</p>
<div id="chk-entry">
<h3 id="chk-entry.sh"><a href="https://github.com/ioccc-src/temp-test-ioccc/blob/master/bin/chk-entry.sh">chk-entry.sh</a></h3>
</div>
<p>Check an entry directory to verify that both the files in its manifest
(<code>.entry.json</code>) exist and that no other files exist.</p>
<p>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="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>
@@ -483,8 +486,9 @@ title</li>
<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, nor convert
them to UNIX format, nor append a final newline to the file.</p>
<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>
@@ -496,6 +500,9 @@ to restore the CSV order and other canonicalizing processes.</p>
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
@@ -521,16 +528,29 @@ content).</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>Given a submission (that has won the IOCCC), with a <code>.auth.json</code>
and <code>.info.json</code> and NO <code>.entry.json</code> file, we convert the
<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> and <strong>NO</strong> <code>.entry.json</code> file (since it just won), we convert the
<code>.auth.json</code> and <code>.info.json</code> into a new <code>.entry.json</code> file.</p>
<p>We will also form, as needed, new <code>author/author_handle.json</code>
files for new authors, and update <code>author/author_handle.json</code>
for authors who won previously.</p>
<p>This tool will, given a submission that has won the IOCCC (and thus will become a published entry), with
a <code>.auth.json</code> and <code>.info.json</code> and NO <code>.entry.json</code> file (since it’s new), 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>
year directory. For instance</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>
@@ -729,7 +749,7 @@ the <a href="index.html#md2html">md2html tool</a>.</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 my the <a href="../judges.html">Judges</a> as part of the final
<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>Usage:</p>
<pre><code> bin/new-year.sh -v 1 YYYY</code></pre>
faq.html
+330 -3
View File
@@ -389,7 +389,7 @@
<!-- BEFORE: 1st line of markdown file: faq.md -->
<h1 id="faq-table-of-contents">FAQ Table of Contents</h1>
<p>This is FAQ version <strong>28.0.1 2024-07-25</strong>.</p>
<p>This is FAQ version <strong>28.0.2 2024-07-26</strong>.</p>
<h2 id="section-0---submitting-entries-to-a-new-ioccc">Section 0 - <a href="#faq0">Submitting entries to a new IOCCC</a></h2>
<ul>
<li><a class="normal" href="#faq0_0">0.0 - How may I enter the IOCCC?</a></li>
@@ -490,6 +490,7 @@ other inconsistencies with the original entry?</a></li>
<li><a class="normal" href="#faq6_14">6.14 - How do I set certain tabstops for viewing source code in vi(m)?</a></li>
<li><a class="normal" href="#faq6_15">6.15 - How do the menus on the website work and what can I do if they don’t work?</a></li>
<li><a class="normal" href="#faq6_16">6.16 - How do I find more information about a winning author of an entry?</a></li>
<li><a class="normal" href="#faq6_17">6.17 - What is a <code>.entry.json</code> file and how is it used?</a></li>
</ul>
<h1 id="the-ioccc-faq">The IOCCC FAQ</h1>
<div id="faq0">
@@ -2716,9 +2717,11 @@ it like:</p>
<p>though of course for both you may specify a rule or rules to run.</p>
<div id="faq3_20">
<div id="entry_downloads">
<div id="tarball">
<h3 id="how-do-i-download-individual-winning-entries-or-all-winning-entries-of-a-given-year">3.20 - How do I download individual winning entries or all winning entries of a given year?</h3>
</div>
</div>
</div>
<p>Although one can clone the entire <a href="https://github.com/ioccc-src/winner">winner
repo</a> to get the entire website and all
entries, we also provide, as a convenience, a way to download individual entries
@@ -3572,8 +3575,8 @@ FAQ on “<a href="#author_handle_faq">author handle</a>”
for more information about an author handles.</p>
<h4 id="author_handle.json-json-file-contents"><code>author_handle.json</code> JSON file contents</h4>
<p>The syntax of a <code>author_handle.json</code> follows the <em>So-called JSON spec</em>.
See <a href="https://github.com/ioccc-src/mkiocccentry/blob/master/jparse/json_index.html#so_called_json_spec">json_index.html</a>
for information on the <em>So-called JSON spec</em>.</p>
See <a href="https://www.json.org/json-en.html" class="uri">https://www.json.org/json-en.html</a> for information on the <em>So-called JSON
spec</em>.</p>
<p>A good way to understand the JSON file contents of a <code>author_handle.json</code> file
is to look at an example, the <code>author_handle.json</code> file for Yusuke Endoh:</p>
<pre><code> author/Yusuke_Endoh.json</code></pre>
@@ -4309,6 +4312,330 @@ JSON files.</p>
<p>Of course if you know the author’s name you can go directly to
<a href="authors.html">authors.html</a> and click on their surname’s/last name’s/second
name’s initial and then scroll down (if necessary) to the author in question.</p>
<div id="faq6_17">
<div id="entry_json">
<h3 id="faq-6.17-what-is-a-.entry.json-file-and-how-is-they-used">FAQ 6.17: What is a <code>.entry.json</code> file and how is they used?</h3>
</div>
</div>
<p><strong>TL:DR</strong>: The contents of this JSON file contain information about each winning
entry in JSON format.</p>
<p>Each winning entry has a <code>.entry.json</code> file that includes data in JSON format
about the entry. We describe the fields below in order to help you understand
its contents.</p>
<p>This file is created by the <a href="bin/index.html#cvt-submission">cvt-submission.sh</a>
tool as part of the final steps to announce a new set of winning IOCCC entries.</p>
<p>Each winning entry has its own <code>.entry.json</code> filename of the form:</p>
<pre><code> YYYY/winner/.entry.json</code></pre>
<p>where <em>winner</em> is the entry directory name, usually the name of the author.</p>
<p><strong>IMPORTANT NOTE</strong>: this file should <strong>NOT</strong> be manually modified! It is created
by the <a href="bin/index.html#csv2entry">csv2entry</a> tool when updating the manifest.</p>
<h4 id="entry.json-json-file-contents"><code>.entry.json</code> JSON file contents</h4>
<p>The syntax of a <code>.entry.json</code> follows the <em>So-called JSON spec</em>.
See <a href="https://www.json.org/json-en.html" class="uri">https://www.json.org/json-en.html</a> for information on the <em>So-called JSON
spec</em>.</p>
<p>A good way to understand the JSON file contents of a <code>.entry.json</code> file
is to look at an example, for instance the
<a href="https://github.com/ioccc-src/temp-test-ioccc/blob/master/1984/laman/.entry.json">1984/laman/.entry.json</a> file, as
it is shorter than some of the others.</p>
<p>As of <em>Fri 26 Jul 2024 17:29:15 UTC</em>, it contains:</p>
<pre><code> {
&quot;no_comment&quot; : &quot;mandatory comment: because comments were removed from the original JSON spec&quot;,
&quot;entry_JSON_format_version&quot; : &quot;1.1 2024-02-11&quot;,
&quot;award&quot; : &quot;Third Place&quot;,
&quot;year&quot; : 1984,
&quot;dir&quot; : &quot;laman&quot;,
&quot;entry_id&quot; : &quot;1984_laman&quot;,
&quot;author_set&quot; : [
{ &quot;author_handle&quot; : &quot;Mike_Laman&quot; }
],
&quot;manifest&quot; : [
{
&quot;file_path&quot; : &quot;laman.c&quot;,
&quot;inventory_order&quot; : 20,
&quot;OK_to_edit&quot; : true,
&quot;display_as&quot; : &quot;c&quot;,
&quot;display_via_github&quot; : true,
&quot;entry_text&quot; : &quot;entry source code&quot;
},
{
&quot;file_path&quot; : &quot;Makefile&quot;,
&quot;inventory_order&quot; : 30,
&quot;OK_to_edit&quot; : true,
&quot;display_as&quot; : &quot;makefile&quot;,
&quot;display_via_github&quot; : true,
&quot;entry_text&quot; : &quot;entry Makefile&quot;
},
{
&quot;file_path&quot; : &quot;laman.orig.c&quot;,
&quot;inventory_order&quot; : 50,
&quot;OK_to_edit&quot; : false,
&quot;display_as&quot; : &quot;c&quot;,
&quot;display_via_github&quot; : true,
&quot;entry_text&quot; : &quot;original source code&quot;
},
{
&quot;file_path&quot; : &quot;try.sh&quot;,
&quot;inventory_order&quot; : 100,
&quot;OK_to_edit&quot; : true,
&quot;display_as&quot; : &quot;shellscript&quot;,
&quot;display_via_github&quot; : true,
&quot;entry_text&quot; : &quot;script to try entry&quot;
},
{
&quot;file_path&quot; : &quot;1984_laman.tar.bz2&quot;,
&quot;inventory_order&quot; : 1415926535,
&quot;OK_to_edit&quot; : false,
&quot;display_as&quot; : &quot;tbz2&quot;,
&quot;display_via_github&quot; : false,
&quot;entry_text&quot; : &quot;download entry tarball&quot;
},
{
&quot;file_path&quot; : &quot;.entry.json&quot;,
&quot;inventory_order&quot; : 4000000000,
&quot;OK_to_edit&quot; : true,
&quot;display_as&quot; : &quot;json&quot;,
&quot;display_via_github&quot; : true,
&quot;entry_text&quot; : &quot;entry summary and manifest in JSON&quot;
},
{
&quot;file_path&quot; : &quot;.gitignore&quot;,
&quot;inventory_order&quot; : 4000000000,
&quot;OK_to_edit&quot; : true,
&quot;display_as&quot; : &quot;gitignore&quot;,
&quot;display_via_github&quot; : true,
&quot;entry_text&quot; : &quot;list of files that should not be committed under git&quot;
},
{
&quot;file_path&quot; : &quot;.path&quot;,
&quot;inventory_order&quot; : 4000000000,
&quot;OK_to_edit&quot; : false,
&quot;display_as&quot; : &quot;path&quot;,
&quot;display_via_github&quot; : true,
&quot;entry_text&quot; : &quot;directory path from top level directory&quot;
},
{
&quot;file_path&quot; : &quot;README.md&quot;,
&quot;inventory_order&quot; : 4000000000,
&quot;OK_to_edit&quot; : true,
&quot;display_as&quot; : &quot;markdown&quot;,
&quot;display_via_github&quot; : true,
&quot;entry_text&quot; : &quot;markdown source for this web page&quot;
},
{
&quot;file_path&quot; : &quot;index.html&quot;,
&quot;inventory_order&quot; : 4294967295,
&quot;OK_to_edit&quot; : false,
&quot;display_as&quot; : &quot;html&quot;,
&quot;display_via_github&quot; : false,
&quot;entry_text&quot; : &quot;this web page&quot;
}
]
}
</code></pre>
<div id="walk_through_entry_json">
<h5 id="walk-through-of-a-.entry.json-file">Walk through of a <code>.entry.json</code> file</h5>
</div>
<p>We now will walk through the above JSON document looking at all the JSON
members:</p>
<h5 id="no_comment-1"><code>no_comment</code></h5>
<pre><code> &quot;no_comment&quot; : &quot;mandatory comment: because comments were removed from the original JSON spec&quot;,</code></pre>
<p>Because the authors of the so-called JSON spec removed the ability to use comments in JSON
(for reason(s) that seem to be less than credible), the IOCCC mandates this <em>JSON member</em>
be present in all IOCCC related JSON files.</p>
<p>There <strong>MUST</strong> be one and only one <code>no_comment</code> <em>JSON member</em> and the <em>JSON value</em> <strong>MUST</strong>
be the exact <em>JSON string</em> as shown above.</p>
<h5 id="entry_json_format_version"><code>entry_JSON_format_version</code></h5>
<pre><code> &quot;entry_JSON_format_version&quot; : &quot;1.1 2024-02-11&quot;,</code></pre>
<p>This <em>JSON member</em> holds the format version of the <code>.entry.json</code> JSON file.</p>
<p>There <strong>MUST</strong> be one and only one <code>entry_JSON_format_version</code>
<em>JSON member</em> and the <em>JSON value</em> <strong>MUST</strong> be a <em>JSON string</em>.</p>
<p>This is <strong>NOT</strong> the version of the contents!</p>
<p>The <code>entry_JSON_format_version</code> would only changed when the overall format
of the these files is modified: and then only those who maintain the
<a href="https://www.ioccc.org">official IOCCC website</a> would be the one to do this
in conjunction with changes to <a href="bin/index.html">bin directory tools</a>.</p>
<h5 id="award"><code>award</code></h5>
<pre><code> &quot;award&quot; : &quot;Third Place&quot;,</code></pre>
<p>This JSON string is the award title of the entry which the <a href="judges.html">Judges</a>
decide/decided when it becomes/became a winning entry.</p>
<h5 id="year"><code>year</code></h5>
<pre><code> &quot;year&quot; : 1984,</code></pre>
<p>This JSON number is the year the contest ran, ended or was announced in.</p>
<h5 id="dir"><code>dir</code></h5>
<pre><code> &quot;dir&quot; : &quot;laman&quot;,</code></pre>
<p>This JSON string is the subdirectory of the entry, <strong>under</strong> the year directory,
in this case <a href="1984/index.html">1984</a>. With the above member, <code>year</code>, and this
one, one can determine the directory of the entry, here being
<a href="1984/laman/index.html">1984/laman</a>.</p>
<h5 id="entry_id-1"><code>entry_id</code></h5>
<pre><code> &quot;entry_id&quot; : &quot;1984_laman&quot;,</code></pre>
<p>This is the ID of the entry in question and corresponds to the <code>entry_id</code> in the
<code>author/author_handle.json</code> file.</p>
<p>See
FAQ on “<a href="#author_handle_faq">author handle</a>”
for more information about author handles.</p>
<p>See
FAQ on “<a href="#author_json">author_handle.json</a>”
for information about the contents of these JSON file and
how they are used.</p>
<h5 id="author_set"><code>author_set</code></h5>
<pre><code> &quot;author_set&quot; : [
{ &quot;author_handle&quot; : &quot;Mike_Laman&quot; }
],</code></pre>
<p>This JSON <strong>array</strong> has a list of <code>author_handle</code>s that indicate who won this
entry.</p>
<p>That <em>JSON member</em> holds the author handle of the author.</p>
<p>In most cases there is only one <code>author_handle</code> in a <code>.entry.json</code> file but in
some there is more than one.</p>
<p>See
FAQ on “<a href="#author_handle_faq">author handle</a>”
for more information about an author handles.</p>
<p>Normally the <code>author_handle</code> <em>JSON value</em> should <strong>NOT</strong> be changed
<strong>unless there is a strong reason to do so</strong>. If the <em>JSON value</em>
changes, then all of the <code>.entry.json</code> files for all of this author’s
winning IOCCC entries should also be changed. The <code>author_handle</code>
<em>JSON value</em> must match the basename (without the leading path and
without the trailing <code>.json</code>) of the <code>author_handle.json</code> file. So
a change of <code>author_handle</code> <em>JSON value</em> would also require the
<code>author_handle.json</code> file to also be renamed.</p>
<p>The full name of an author may use non-ASCII characters so long as the
full name is properly encoded as a <em>JSON string</em>.</p>
<h5 id="manifest"><code>manifest</code></h5>
<p>Finally there is the manifest JSON <strong>array</strong> that lists the files of the winning
entry. Because each array member (a file) has the same fields we will only list
one of the files in the manifest, providing comments about each field. After
that we will list some files that are mandatory files, also with comments.</p>
<p>There <strong>MUST</strong> be one and only one <code>manifest</code> <em>JSON member</em> and the <em>JSON value</em>
<strong>MUST</strong> be a <em>JSON</em> array.</p>
<p>A shortened manifest for our example entry is:</p>
<pre><code> &quot;manifest&quot; : [
{
&quot;file_path&quot; : &quot;laman.c&quot;,
&quot;inventory_order&quot; : 20,
&quot;OK_to_edit&quot; : true,
&quot;display_as&quot; : &quot;c&quot;,
&quot;display_via_github&quot; : true,
&quot;entry_text&quot; : &quot;entry source code&quot;
}
]</code></pre>
<p>Now we will describe each field of each file in the manifest:</p>
<ul>
<li><code>file_path</code> (string)
<ul>
<li>This <em>JSON</em> <strong>string</strong> is the name of the file in question.</li>
</ul></li>
<li><code>inventory_order</code> (number)
<ul>
<li>This <em>JSON</em> <strong>number</strong> decides which file list in the <code>index.html</code> file this
file is listed and its order in that list. The details are beyond the scope
of this document and it is only necessary to understand this if you are
adding a file to the manifest. However as the <a href="judges.html">Judges</a> are the
ones who will be doing this this need not concern you.</li>
</ul></li>
<li><code>OK_to_edit</code> (boolean)
<ul>
<li>This <em>JSON</em> <strong>boolean</strong> indicates whether this file may be edited or not. An
example file that can be edited is the winning source code; an example that
would be <code>false</code> is the original source code file (see below for details on
this).</li>
</ul></li>
<li><code>display_as</code> (string)
<ul>
<li>This <em>JSON</em> <strong>string</strong> describes what kind of file it is and in particular
how to <strong>display</strong> it. An entry source code file would be (all strings are
lower case) <code>c</code>, a shell script would be <code>shellscript</code> and a <code>Makefile</code>
would be <code>makefile</code>, for three examples of others. As updating the manifest
is mostly a task for the <a href="judges.html">Judges</a> you need not concern yourself
with all the different names.</li>
</ul></li>
<li><code>display_via_github</code> (boolean)
<ul>
<li>This <em>JSON</em> <strong>boolean</strong> indicates whether the file should be viewed at
(that is linked to) GitHub or not. A good reason it might be viewed at
GitHub is for syntax highlighting or if it should not be downloaded but
would likely be downloaded by the browser otherwise.</li>
</ul></li>
<li><code>entry_text</code> (string)
<ul>
<li>This <em>JSON</em> <strong>string</strong> is a short string that gives a summary of what the
file is, for purposes of the file lists in the <code>index.html</code> inventory.</li>
</ul></li>
</ul>
<p>Now that we have discussed the <em>JSON members</em> of each file in the <code>manifest</code> we
will give a list of <strong>MANDATORY</strong> files (for winning entry source code the names
will depend on the year).</p>
<ul>
<li><p>the entry source code</p>
<ul>
<li>This file is typically called <code>winner.c</code>, where <code>winner</code> is as described
above, or <code>prog.c</code> (for later years). The <code>entry_text</code> is always <code>"entry source code"</code>.</li>
</ul></li>
<li><p>the entry Makefile</p>
<ul>
<li>This is the submission’s Makefile <strong>modified</strong> by the <a href="judges.html">Judges</a>,
should the submission win. The <code>entry_text</code> is always <code>"entry Makefile"</code> and
the <code>file_path</code> is <strong>ALWAYS</strong> <code>"Makefile"</code>.</li>
</ul></li>
<li><p>the original source code file</p>
<ul>
<li>This is the entry source code file that was submitted and that won. This
will be named either <code>winner.orig.c</code> or <code>prog.orig.c</code>, depending on the
year. This file may <strong>NOT</strong> be modified. The <code>entry_text</code> for this file is
always <code>"original source code"</code>.</li>
</ul></li>
<li><p>the <a href="#tarball">entry tarball</a></p>
<ul>
<li>This is the tarball of just the top level Makefile (and those included by
it) and the entry itself, for convenience. It is named in the form of
<code>YYYY_winner.tar.bz2</code>. For instance, for <a href="1984/laman/index.html">1984/laman</a>
it is called <code>1984_laman.tar.bz2</code>. This file is <strong>NOT</strong> displayed via
GitHub. The <code>entry_text</code> is always <code>download entry tarball</code> as it is a file
that is to be downloaded, should one wish to.</li>
</ul></li>
<li><p><a href="#entry_json">.entry.json</a> file</p>
<ul>
<li>This is the file we’re currently discussing, the <code>.entry.json</code> file. The
<code>entry_text</code> is always <code>"entry summary and manifest in JSON"</code> and the
<code>file_path</code> is <strong>ALWAYS</strong> <code>".entry.json"</code>.</li>
</ul></li>
<li><p><code>.gitignore</code></p>
<ul>
<li>The list of files that should not be committed under git. Its <code>entry_text</code>
is always <code>"list of files that should not be committed under git"</code> and the
<code>file_path</code> is <strong>ALWAYS</strong> <code>".gitignore"</code>.</li>
</ul></li>
<li><p><code>.path</code></p>
<ul>
<li>This file contains the path to the entry subdirectory from the top level
directory. For instance for <a href="1984/laman/index.html">1984/laman</a> it is
<code>"1984/laman"</code>. This file’s <code>entry_text</code> is always <code>"directory path from top level directory"</code> and the <code>file_path</code> is <strong>ALWAYS</strong> <code>".path"</code>.</li>
</ul></li>
<li><p><code>README.md</code></p>
<ul>
<li>This file is the markdown source file for the <code>index.html</code> file. Its
<code>entry_text</code> is always <code>"markdown source for this web page"</code> (because it is
listed in <code>index.html</code>) and the <code>file_path</code> is <strong>ALWAYS</strong> <code>"README.md"</code>
(renamed from the <code>remarks.md</code> provided in submissions).</li>
</ul>
<p>In most cases, if the entry has other html files then they are also formed
from markdown files and the <code>entry_text</code> will be similar; the <code>file_path</code> in
these cases will be the same as the html file except it will have the
extension <code>.md</code>.</p></li>
<li><p><code>index.html</code></p>
<ul>
<li>This is the main page of the entry, formed from the <code>README.md</code> file. Its
<code>entry_text</code> is always <code>"this web page"</code> and its <code>file_path</code> is <strong>ALWAYS</strong>
<code>"index.html"</code>.</li>
</ul></li>
</ul>
<p>If the entry has an alternate source code file, often it will be in the form of
<code>"winner.alt.c"</code> or <code>"prog.alt.c"</code>; this is also what the <code>file_path</code> will be.
The <code>entry_text</code> will typically (not always but almost always) be <code>"alternate source code"</code>.</p>
<p>Many entries have a script (or scripts) for the <code>Try</code> section in their index.html file.
Usually this is called <code>try.sh</code> for the entry and <code>try.alt.sh</code> for the alternate
source code (if there is an alternate version). Some, however, have another file
name. The <code>entry_text</code> for the <code>try</code> scripts will be <code>script to try entry</code> or
something along those lines.</p>
<hr style="width:10%;text-align:left;margin-left:0">
<p>Jump to: <a href="#">top</a></p>
<!--
faq.md
+399 -4
View File
@@ -1,6 +1,6 @@
# FAQ Table of Contents
This is FAQ version **28.0.1 2024-07-25**.
This is FAQ version **28.0.2 2024-07-26**.
## Section 0 - [Submitting entries to a new IOCCC](#faq0)
@@ -102,11 +102,11 @@ other inconsistencies with the original entry?](#faq4_3)
- <a class="normal" href="#faq6_14">6.14 - How do I set certain tabstops for viewing source code in vi&#x28;m&#x29;?</a>
- <a class="normal" href="#faq6_15">6.15 - How do the menus on the website work and what can I do if they don't work?</a>
- <a class="normal" href="#faq6_16">6.16 - How do I find more information about a winning author of an entry?</a>
- <a class="normal" href="#faq6_17">6.17 - What is a `.entry.json` file and how is it used?</a>
# The IOCCC FAQ
<div id="faq0">
## Section 0: Submitting entries to a new IOCCC
</div>
@@ -3079,9 +3079,11 @@ though of course for both you may specify a rule or rules to run.
<div id="faq3_20">
<div id="entry_downloads">
<div id="tarball">
### 3.20 - How do I download individual winning entries or all winning entries of a given year?
</div>
</div>
</div>
Although one can clone the entire [winner
repo](https://github.com/ioccc-src/winner) to get the entire website and all
@@ -4245,8 +4247,8 @@ for more information about an author handles.
#### `author_handle.json` JSON file contents
The syntax of a `author_handle.json` follows the _So-called JSON spec_.
See [json_index.html](https://github.com/ioccc-src/mkiocccentry/blob/master/jparse/json_index.html#so_called_json_spec)
for information on the _So-called JSON spec_.
See <https://www.json.org/json-en.html> for information on the _So-called JSON
spec_.
A good way to understand the JSON file contents of a `author_handle.json` file
is to look at an example, the `author_handle.json` file for Yusuke Endoh:
@@ -5399,6 +5401,399 @@ Of course if you know the author's name you can go directly to
[authors.html](authors.html) and click on their surname's/last name's/second
name's initial and then scroll down (if necessary) to the author in question.
<div id="faq6_17">
<div id="entry_json">
### FAQ 6.17: What is a `.entry.json` file and how is they used?
</div>
</div>
**TL:DR**: The contents of this JSON file contain information about each winning
entry in JSON format.
Each winning entry has a `.entry.json` file that includes data in JSON format
about the entry. We describe the fields below in order to help you understand
its contents.
This file is created by the [cvt-submission.sh](bin/index.html#cvt-submission)
tool as part of the final steps to announce a new set of winning IOCCC entries.
Each winning entry has its own `.entry.json` filename of the form:
```
YYYY/winner/.entry.json
```
where _winner_ is the entry directory name, usually the name of the author.
**IMPORTANT NOTE**: this file should **NOT** be manually modified! It is created
by the [csv2entry](bin/index.html#csv2entry) tool when updating the manifest.
#### `.entry.json` JSON file contents
The syntax of a `.entry.json` follows the _So-called JSON spec_.
See <https://www.json.org/json-en.html> for information on the _So-called JSON
spec_.
A good way to understand the JSON file contents of a `.entry.json` file
is to look at an example, for instance the
[1984/laman/.entry.json](%%REPO_URL%%/1984/laman/.entry.json) file, as
it is shorter than some of the others.
As of _Fri 26 Jul 2024 17:29:15 UTC_, it contains:
``` <!---json-->
{
"no_comment" : "mandatory comment: because comments were removed from the original JSON spec",
"entry_JSON_format_version" : "1.1 2024-02-11",
"award" : "Third Place",
"year" : 1984,
"dir" : "laman",
"entry_id" : "1984_laman",
"author_set" : [
{ "author_handle" : "Mike_Laman" }
],
"manifest" : [
{
"file_path" : "laman.c",
"inventory_order" : 20,
"OK_to_edit" : true,
"display_as" : "c",
"display_via_github" : true,
"entry_text" : "entry source code"
},
{
"file_path" : "Makefile",
"inventory_order" : 30,
"OK_to_edit" : true,
"display_as" : "makefile",
"display_via_github" : true,
"entry_text" : "entry Makefile"
},
{
"file_path" : "laman.orig.c",
"inventory_order" : 50,
"OK_to_edit" : false,
"display_as" : "c",
"display_via_github" : true,
"entry_text" : "original source code"
},
{
"file_path" : "try.sh",
"inventory_order" : 100,
"OK_to_edit" : true,
"display_as" : "shellscript",
"display_via_github" : true,
"entry_text" : "script to try entry"
},
{
"file_path" : "1984_laman.tar.bz2",
"inventory_order" : 1415926535,
"OK_to_edit" : false,
"display_as" : "tbz2",
"display_via_github" : false,
"entry_text" : "download entry tarball"
},
{
"file_path" : ".entry.json",
"inventory_order" : 4000000000,
"OK_to_edit" : true,
"display_as" : "json",
"display_via_github" : true,
"entry_text" : "entry summary and manifest in JSON"
},
{
"file_path" : ".gitignore",
"inventory_order" : 4000000000,
"OK_to_edit" : true,
"display_as" : "gitignore",
"display_via_github" : true,
"entry_text" : "list of files that should not be committed under git"
},
{
"file_path" : ".path",
"inventory_order" : 4000000000,
"OK_to_edit" : false,
"display_as" : "path",
"display_via_github" : true,
"entry_text" : "directory path from top level directory"
},
{
"file_path" : "README.md",
"inventory_order" : 4000000000,
"OK_to_edit" : true,
"display_as" : "markdown",
"display_via_github" : true,
"entry_text" : "markdown source for this web page"
},
{
"file_path" : "index.html",
"inventory_order" : 4294967295,
"OK_to_edit" : false,
"display_as" : "html",
"display_via_github" : false,
"entry_text" : "this web page"
}
]
}
```
<div id="walk_through_entry_json">
##### Walk through of a `.entry.json` file
</div>
We now will walk through the above JSON document looking at all the JSON
members:
##### `no_comment`
``` <!--- json-->
"no_comment" : "mandatory comment: because comments were removed from the original JSON spec",
```
Because the authors of the so-called JSON spec removed the ability to use comments in JSON
(for reason(s) that seem to be less than credible), the IOCCC mandates this _JSON member_
be present in all IOCCC related JSON files.
There **MUST** be one and only one `no_comment` _JSON member_ and the _JSON value_ **MUST**
be the exact _JSON string_ as shown above.
##### `entry_JSON_format_version`
``` <!---json-->
"entry_JSON_format_version" : "1.1 2024-02-11",
```
This _JSON member_ holds the format version of the `.entry.json` JSON file.
There **MUST** be one and only one `entry_JSON_format_version`
_JSON member_ and the _JSON value_ **MUST** be a _JSON string_.
This is **NOT** the version of the contents!
The `entry_JSON_format_version` would only changed when the overall format
of the these files is modified: and then only those who maintain the
[official IOCCC website](https://www.ioccc.org) would be the one to do this
in conjunction with changes to [bin directory tools](bin/index.html).
##### `award`
``` <!---json-->
"award" : "Third Place",
```
This JSON string is the award title of the entry which the [Judges](judges.html)
decide/decided when it becomes/became a winning entry.
##### `year`
``` <!---json-->
"year" : 1984,
```
This JSON number is the year the contest ran, ended or was announced in.
##### `dir`
``` <!---json-->
"dir" : "laman",
```
This JSON string is the subdirectory of the entry, **under** the year directory,
in this case [1984](1984/index.html). With the above member, `year`, and this
one, one can determine the directory of the entry, here being
[1984/laman](1984/laman/index.html).
##### `entry_id`
``` <!---json-->
"entry_id" : "1984_laman",
```
This is the ID of the entry in question and corresponds to the `entry_id` in the
`author/author_handle.json` file.
See
FAQ on "[author handle](#author_handle_faq)"
for more information about author handles.
See
FAQ on "[author_handle.json](#author_json)"
for information about the contents of these JSON file and
how they are used.
##### `author_set`
``` <!---json-->
"author_set" : [
{ "author_handle" : "Mike_Laman" }
],
```
This JSON **array** has a list of `author_handle`s that indicate who won this
entry.
That _JSON member_ holds the author handle of the author.
In most cases there is only one `author_handle` in a `.entry.json` file but in
some there is more than one.
See
FAQ on "[author handle](#author_handle_faq)"
for more information about an author handles.
Normally the `author_handle` _JSON value_ should **NOT** be changed
**unless there is a strong reason to do so**. If the _JSON value_
changes, then all of the `.entry.json` files for all of this author's
winning IOCCC entries should also be changed. The `author_handle`
_JSON value_ must match the basename (without the leading path and
without the trailing `.json`) of the `author_handle.json` file. So
a change of `author_handle` _JSON value_ would also require the
`author_handle.json` file to also be renamed.
The full name of an author may use non-ASCII characters so long as the
full name is properly encoded as a _JSON string_.
##### `manifest`
Finally there is the manifest JSON **array** that lists the files of the winning
entry. Because each array member (a file) has the same fields we will only list
one of the files in the manifest, providing comments about each field. After
that we will list some files that are mandatory files, also with comments.
There **MUST** be one and only one `manifest` _JSON member_ and the _JSON value_
**MUST** be a _JSON_ array.
A shortened manifest for our example entry is:
``` <!---json-->
"manifest" : [
{
"file_path" : "laman.c",
"inventory_order" : 20,
"OK_to_edit" : true,
"display_as" : "c",
"display_via_github" : true,
"entry_text" : "entry source code"
}
]
```
Now we will describe each field of each file in the manifest:
- `file_path` (string)
* This _JSON_ **string** is the name of the file in question.
- `inventory_order` (number)
* This _JSON_ **number** decides which file list in the `index.html` file this
file is listed and its order in that list. The details are beyond the scope
of this document and it is only necessary to understand this if you are
adding a file to the manifest. However as the [Judges](judges.html) are the
ones who will be doing this this need not concern you.
- `OK_to_edit` (boolean)
* This _JSON_ **boolean** indicates whether this file may be edited or not. An
example file that can be edited is the winning source code; an example that
would be `false` is the original source code file (see below for details on
this).
- `display_as` (string)
* This _JSON_ **string** describes what kind of file it is and in particular
how to **display** it. An entry source code file would be (all strings are
lower case) `c`, a shell script would be `shellscript` and a `Makefile`
would be `makefile`, for three examples of others. As updating the manifest
is mostly a task for the [Judges](judges.html) you need not concern yourself
with all the different names.
- `display_via_github` (boolean)
* This _JSON_ **boolean** indicates whether the file should be viewed at
(that is linked to) GitHub or not. A good reason it might be viewed at
GitHub is for syntax highlighting or if it should not be downloaded but
would likely be downloaded by the browser otherwise.
- `entry_text` (string)
* This _JSON_ **string** is a short string that gives a summary of what the
file is, for purposes of the file lists in the `index.html` inventory.
Now that we have discussed the _JSON members_ of each file in the `manifest` we
will give a list of **MANDATORY** files (for winning entry source code the names
will depend on the year).
- the entry source code
* This file is typically called `winner.c`, where `winner` is as described
above, or `prog.c` (for later years). The `entry_text` is always `"entry
source code"`.
- the entry Makefile
* This is the submission's Makefile **modified** by the [Judges](judges.html),
should the submission win. The `entry_text` is always `"entry Makefile"` and
the `file_path` is **ALWAYS** `"Makefile"`.
- the original source code file
* This is the entry source code file that was submitted and that won. This
will be named either `winner.orig.c` or `prog.orig.c`, depending on the
year. This file may **NOT** be modified. The `entry_text` for this file is
always `"original source code"`.
- the [entry tarball](#tarball)
* This is the tarball of just the top level Makefile (and those included by
it) and the entry itself, for convenience. It is named in the form of
`YYYY_winner.tar.bz2`. For instance, for [1984/laman](1984/laman/index.html)
it is called `1984_laman.tar.bz2`. This file is **NOT** displayed via
GitHub. The `entry_text` is always `download entry tarball` as it is a file
that is to be downloaded, should one wish to.
- [.entry.json](#entry_json) file
* This is the file we're currently discussing, the `.entry.json` file. The
`entry_text` is always `"entry summary and manifest in JSON"` and the
`file_path` is **ALWAYS** `".entry.json"`.
- `.gitignore`
* The list of files that should not be committed under git. Its `entry_text`
is always `"list of files that should not be committed under git"` and the
`file_path` is **ALWAYS** `".gitignore"`.
- `.path`
* This file contains the path to the entry subdirectory from the top level
directory. For instance for [1984/laman](1984/laman/index.html) it is
`"1984/laman"`. This file's `entry_text` is always `"directory path from top
level directory"` and the `file_path` is **ALWAYS** `".path"`.
- `README.md`
* This file is the markdown source file for the `index.html` file. Its
`entry_text` is always `"markdown source for this web page"` (because it is
listed in `index.html`) and the `file_path` is **ALWAYS** `"README.md"`
(renamed from the `remarks.md` provided in submissions).
In most cases, if the entry has other html files then they are also formed
from markdown files and the `entry_text` will be similar; the `file_path` in
these cases will be the same as the html file except it will have the
extension `.md`.
- `index.html`
* This is the main page of the entry, formed from the `README.md` file. Its
`entry_text` is always `"this web page"` and its `file_path` is **ALWAYS**
`"index.html"`.
If the entry has an alternate source code file, often it will be in the form of
`"winner.alt.c"` or `"prog.alt.c"`; this is also what the `file_path` will be.
The `entry_text` will typically (not always but almost always) be `"alternate
source code"`.
Many entries have a script (or scripts) for the `Try` section in their index.html file.
Usually this is called `try.sh` for the entry and `try.alt.sh` for the alternate
source code (if there is an alternate version). Some, however, have another file
name. The `entry_text` for the `try` scripts will be `script to try entry` or
something along those lines.
<hr style="width:10%;text-align:left;margin-left:0">