From 0e11c054ae6dc255e2da220193bf8ac4234fc0f2 Mon Sep 17 00:00:00 2001 From: Cody Boone Ferguson <53008573+xexyl@users.noreply.github.com> Date: Fri, 26 Jul 2024 12:20:03 -0700 Subject: [PATCH] Add FAQ on .entry.json files This FAQ was added as part of updates to bin/index.html. I did notice that there are some inconsistencies with formatting in some FAQs compared to this (and others also). The example here is that for JSON members it would be better to use inline code blocks than italics but some use italics instead. There are others as well. I did look at the format and the links in this updated FAQ but the format inconsistencies can be addressed another time - after it is clear that new FAQs will not have to be added. Even so this FAQ that was added here could also possibly be improved further - also later on. The bin/index.html updates need to be more thoroughly checked as part of further documenting the newer tools (and any additional ones that might be added) but there should be some improvements as well. This required check will also be done later on. --- bin/README.md | 62 +++++--- bin/index.html | 58 ++++--- faq.html | 333 +++++++++++++++++++++++++++++++++++++++- faq.md | 403 ++++++++++++++++++++++++++++++++++++++++++++++++- 4 files changed, 811 insertions(+), 45 deletions(-) diff --git a/bin/README.md b/bin/README.md index 76afe9b71..a68de5f02 100644 --- a/bin/README.md +++ b/bin/README.md @@ -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: ``` @@ -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.
### [add-dir.sh](%%REPO_URL%%/bin/add-dir.sh)
-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.
@@ -134,8 +134,8 @@ Alternate usage: ### [chk-entry.sh](%%REPO_URL%%/bin/chk-entry.sh)
-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.
### [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)
-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
@@ -598,7 +622,7 @@ the [md2html tool](index.html#md2html). ### [new-year.sh](%%REPO_URL%%/bin/new-year.sh)
-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: diff --git a/bin/index.html b/bin/index.html index f8e9b1c1e..cb823f57f 100644 --- a/bin/index.html +++ b/bin/index.html @@ -407,10 +407,10 @@ help, diagnose problems, see progress etc. These options are as follows:

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 tool -from the root directory, you would do:

+from the root directory (of the repo/website), you would do:

    bin/all-run.sh -h

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 tool, you might do:

@@ -423,25 +423,25 @@ for some tools, set a verbosity level.

For instance to see what version the chk-entry.sh tool is, you would do:

    bin/chk-entry.sh -V
-

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. 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 -h option on it first.

There are some scripts that are invoked by the -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 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.

add-dir.sh

-

This tool is used my the Judges as part of the final +

This tool is used by the Judges as part of the final steps to announce a new winning IOCCC entry.

Usage:

    mkdir -p YYYY/dir
     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.

all-run.sh

@@ -461,13 +461,16 @@ steps to announce a new winning IOCCC entry.

chk-entry.sh

-

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:

    bin/chk-entry.sh 2020/ferguson1

If you wish to run it on all entries, we recommend that this tool be invoked via the top level Makefile:

    make verify_entry_files
+

NOTE: see the +FAQ on “.entry.json files” +for more details on .entry.json files.

csv2entry.sh

@@ -483,8 +486,9 @@ title

This tool updates .entry.json files entries whose content is modified.

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 some spreadsheet such as the macOS @@ -496,6 +500,9 @@ to restore the CSV order and other canonicalizing processes.

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” +for more details on .entry.json files.

Internal details of bin/csv2entry.sh

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).

cvt-submission.sh

-

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 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 as part of packaging +submissions.

+

We will also form new author/author_handle.json (see the +FAQ on “author_handle.json files” +for more information) and update author/author_handle.json +for authors who previously won. See also the +FAQ on “author_handle”. +See also the +FAQ on “.entry.json”.

Usage:

    bin/cvt-submission.sh -v 1 YYYY/dir

Here, YYYY/dir is the path of the submission under the YYYY -year directory.

+year directory. For instance

entry2csv.sh

@@ -729,7 +749,7 @@ the md2html tool.

new-year.sh

-

This tool is used my the Judges as part of the final +

This tool is used by the Judges as part of the final steps to announce a new set of winning IOCCC entries.

Usage:

    bin/new-year.sh -v 1 YYYY
diff --git a/faq.html b/faq.html index 929fb7689..632fc1304 100644 --- a/faq.html +++ b/faq.html @@ -389,7 +389,7 @@

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

The IOCCC FAQ

@@ -2716,9 +2717,11 @@ it like:

though of course for both you may specify a rule or rules to run.

+

3.20 - How do I download individual winning entries or all winning entries of a given year?

+

Although one can clone the entire winner repo 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 “author handle” 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 -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:

    author/Yusuke_Endoh.json
@@ -4309,6 +4312,330 @@ JSON files.

Of course if you know the author’s name you can go directly to 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.

+
+
+

FAQ 6.17: What is a .entry.json file and how is they used?

+
+
+

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 +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 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 file, as +it is shorter than some of the others.

+

As of Fri 26 Jul 2024 17:29:15 UTC, it contains:

+
    {
+        "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"
+            }
+        ]
+    }
+
+
+
Walk through of a .entry.json file
+
+

We now will walk through the above JSON document looking at all the JSON +members:

+
no_comment
+
    "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
+
        "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 would be the one to do this +in conjunction with changes to bin directory tools.

+
award
+
    "award" : "Third Place",
+

This JSON string is the award title of the entry which the Judges +decide/decided when it becomes/became a winning entry.

+
year
+
    "year" : 1984,
+

This JSON number is the year the contest ran, ended or was announced in.

+
dir
+
    "dir" : "laman",
+

This JSON string is the subdirectory of the entry, under the year directory, +in this case 1984. With the above member, year, and this +one, one can determine the directory of the entry, here being +1984/laman.

+
entry_id
+
    "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” +for more information about author handles.

+

See +FAQ on “author_handle.json” +for information about the contents of these JSON file and +how they are used.

+
author_set
+
    "author_set" : [
+        { "author_handle" : "Mike_Laman" }
+    ],
+

This JSON array has a list of author_handles 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” +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:

+
    "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:

+ +

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).

+ +

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.

Jump to: top

+ { + "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" + } + ] + } + +``` + +
+##### Walk through of a `.entry.json` file +
+ +We now will walk through the above JSON document looking at all the JSON +members: + +##### `no_comment` + +``` + "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` + +``` + "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` + +``` + "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` + +``` + "year" : 1984, +``` + +This JSON number is the year the contest ran, ended or was announced in. + +##### `dir` + +``` + "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` + +``` + "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` + + +``` + "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: + +``` + "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. + + + +