ioccc/tmp

tmp

The tools under this directory are an alpha release. The build-ioccc repo will hold the beta and formal release of tools that will maintain the official IOCCC web site.

Currently these tools maintain the experimental web site by default, via the temp-test-ioccc GitHub repo. These tools will redefault to using the temp-test-ioccc repo and the experimental web site until the official IOCCC web site, via the IOCCC winner repo is ready for the mass pull request/merge.

IMPORTANT: The purpose of the tmp directory is to hold temporary files. The files in the tmp directory will go away leaving behind an empty tmp directory.

purpose

This documentation is here to help define terms, files under tmp/ and the format of those files.

NOTE: The terms section may be moved to another file later on, after the contents of this directory are removed.

files

OLD_manifest

The files in the OLD_manifest were in the top of the tmp directory as of 2023 Oct 26. They represent the first complete manifest that matched the winner file directories.

These files in this directory are kept as a temporary snapshot for now.

README.md

This file.

author_names.txt

A text file of full names of each author: one full name per line.

In the case of anonymous authors the form is:

Anonymous YYYY

author_wins.numbers

A macOS Numbers spreadsheet: one line per author.

The first field is an author_handle.

The other fields are the winner_id's of all winners won by the author.

author_wins.csv

The author_wins.csv is a CSV file that was exported from the author_wins.numbers file.

In case of conflict, the data in author_wins.numbers file is considered authoritative over the author_wins.csv file.

The author_wins.csv.csv is generated from the author_wins.numbers file, via the macOS Numbers spreadsheet app, as follows:

0. open author_wins.numbers in numbers: modify if/as needed

1. File -> Export To -> CSV...

   • 1a. [ ] Include table names (unset)
   • 1b. Text Encoding: Unicode (UTF-8)
   • 1c. Click ((Save..))

2. Save As: author_wins.csv

   • 2a. Select the tmp directory

3. Click ((Export))

   • 3a. If needed click ((Replace))

4. Execute ./fix_csv.sh

author.numbers

A macOS Numbers spreadsheet contains information about authors: one line per author with the following fields:

1. This field is sort_word string.

2. This field is the full name of the author.

3. This field is the author_handle of the author.

4. This field is the primary URL of author or the string null if none was given.

5. This field is the email address of author or the string null if none was given.

6. This field is the location ISO 3166 code of author or the string null is unknown. An author who does not wish to specify a location ISO 3166 code is encouraged to use the code XX. The location ISO 3166 code consists of two UPPER CASE ASCII letters.

7. This field is the twitter handle of the author or the string null if none was given. This field is kept for purely historic record purposes and is otherwise not used.

8. This field is the mastodon handle of the author or the string null if none was given.

9. This field is the alternate URL of author or the string null if none was given.

author.csv

The author.csv is a CSV file that was exported from the author.numbers file.

In case of conflict, the data in author.numbers file is considered authoritative over the author.csv file.

The author.csv is generated from the author.numbers file, via the macOS Numbers spreadsheet app, as follows:

0. open author.csv in numbers: modify if/as needed

1. File -> Export To -> CSV...

   • 1a. [ ] Include table names (unset)
   • 1b. Text Encoding: Unicode (UTF-8)
   • 1c. Click ((Save..))

2. Save As: author.csv

   • 2a. Select the tmp directory

3. Click ((Export))

   • 3a. If needed click ((Replace))

4. Execute ./fix_csv.sh

author_handle.txt

A text file containing author_handles for each author: one author_handle per line.

awards_check.sh

Script to verify that the award name for each entry as found as a level 1 markdown header in each entry's README.md file.

Run the script from the top level directory. The output should end in ":1".

For example, this command should not produce any output.

tmp/awards_check.sh | grep -v ':1$'

Any output is an indication that either an award name is incorrect, or the award is not formed at a level 1 markdown header, or that more than one award line as at a level 1 markdown header we found, or the README.md file is missing, etc.

check_path_list.sh

Look for problems with path_list.required.txt, path_list.manifest.txt, and path_list.found.txt files. In particular, the files found in winning directories are compared with the list of required files as well as the complete manifest list of files.

If all is OK, check_path_list.sh exits 0 and prints nothing. If there are missing required files, or extra files found then check_path_list.sh will exit non-zero and print information about problems.

echo.sh

Tool that simply echos it arguments: used to test run_all.sh.

example.author.json

This is a JSON file containing an example author/author_handle.json for a fictitious author.

An author/author_handle.json file will be derived from the contents of the author.csv file and the author_wins.csv file.

example.dot_winner.json

This is a JSON file containing an example year/dir/.winner.json for a fictitious winner.

A year/dir/.winner.json file will be derived from the contents the year/dir/.id file, the author_wins.csv file, the year/dir/.year file, and the the manifest.csv file.

The 11 field names in manifest.numbers match the JSON member names found in example.dot_winner.json.

fake.gen_index.sh

Generate a fake index.html for a given winner.

fix_csv.sh

This tool will fix CSV files exported by macOS Numbers by removing carriage returns and appending a newline if it was missing.

Fixing involves these actions:

tr -d '\015' < input.csv > tmp.csv
echo >> tmp.csv
mv -f tmp.csv input.csv

This tool also forms path_list.built.txt, path_list.manifest.txt, and path_list.required.txt from manifest.csv.

gen_author_json.sh

Temporary tool used to generate the author/author_handle.json files.

The following command, executed in this directory, created the author/ directory:

rm -rf ../author ; ./gen_author_json.sh  author_handle.txt author.csv author_wins.csv ../author

gen_winner_json.sh

Generate a .winner.json for a given winner.

gen_path_list.found.sh

The list of paths of files in winners.

After doing a make clobber this tool updates, if needed, form path_list.found.txt.

old-ioccc.css

The previous version of /ioccc.css, now tmp/old-ioccc.css to make room for the new IOCCC css being developed.

manifest.numbers

A macOS Numbers spreadsheet contains information about files in winner directories under year directories. This file as the following fields:

1. year:

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

   NOTE: If year begins with "#", then dir is a comment, and the rest of the row is to be ignored. Rows of this form do NOT contain manifest information for a file.

2. dir:

   Directory name number the IOCCC year.

3. path:

   Path under the IOCCC/directory. In a few cases this is a path, not just a simple filename under the IOCCC/directory.

4. inventory_order:

   This number is the winners rank showing the order that this file is to be listed for the given entry's in winners.html.

   If the number is 9 digits or less, then the given file is considered a primary file when listed in the inventory of files for a given winner.

   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 winner. We recommend using the value 4294967295 (2^32-1) for secondary files.

5. OK_to_edit:

   If the value is true, then the file is one that may be edited directly.

   If the value is false, then the file should NOT be edited, because the given file is generated by a tool. One should NOT modify such a file directly, but instead modify source files (i.e., markdown files, JSON files, etc.)

6. display_as:

   The type of given file.

7. display_via_github

   If true, then the contents of the file should be viewed via the GitHub repo.

   If false, 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.

8. winners_text:

   Any text that should be displayed at the end of line in winners.html (with a preceding " - "), or null is no such text is to be displayed.

The 8 field names in manifest.numbers, must match the JSON member names found in example.dot_winner.json.

NOTE: Cells containing true or false are JSON booleans. NOTE: All other cells are JSON strings that need to be double quoted, including the year. NOTE: Do not put commas, nor quotes, nor newlines in fields as these are bound to cause problems.

In case of conflict, the data in manifest.numbers file is considered authoritative over the manifest.csv file.

manifest.csv

The manifest.csv is a CSV file that was exported from the manifest.numbers file.

In case of conflict, the data in manifest.numbers file is considered authoritative over the manifest.csv file.

The manifest.csv is generated from the manifest.numbers file, via the macOS Numbers spreadsheet app, as follows:

0. open manifest.numbers in numbers: modify if/as needed

1. File -> Export To -> CSV...

   • 1a. [ ] Include table names (unset)
   • 1b. Text Encoding: Unicode (UTF-8)
   • 1c. Click ((Save..))

2. Save As: manifest.csv

   • 2a. Select the tmp directory

3. Click ((Export))

   • 3a. If needed click ((Replace))

4. Execute ./fix_csv.sh

path_list.built.txt

A list of file paths (from the top directory) of winner directories, that are built from other primary content files.

These paths are formed from manifest.numbers entries where the "created_by" (5th) field is null. See manifest.numbers for details on the fields.

This file is formed by the fix_csv.sh tool.

path_list.found.txt

A list of files that exist, or should exist once the tools to generate certain files, such as the index.html, or the .winner.json files for each entry, are created.

This file is created by gen_path_list.found.sh.

path_list.manifest.txt

This is the list of file paths, both primary and constructed files from winners.

This file is formed by the fix_csv.sh tool.

path_list.required.txt

A list of file paths (from the top directory) of winner directories, that are required to exist.

These paths are formed from manifest.numbers entries where the "created_by" (5th) field is non-null. See manifest.numbers for details on the fields.

This file is formed by the fix_csv.sh tool.

sql/winners.sql

This is a SQL file, extracted from another SQL file that was used in the past to generate data for the old winners directory tree.

src

This is a temporary location for potential tools that are used to build and maintain the www.ioccc.org web site.

Eventually a separate build-ioccc repo will hold these tools.

run_all.sh

A tool to run another tool over all winner directories.

Examples:

./run_all.sh -v 3 ./fake.gen_index.sh
./run_all.sh -v 1 ./gen_winner_json.sh

templates

template-footer.html

template-header.html

template-top.html

An HTML template for what goes into the top of constructed HTML pages.

Constructed HTML pages will be as follows:

0. template-top.html
1. file: path HTML comment
2. created by tool: tool-name HTML comment
3. tool version: tool-version HTML comment
4. content source: path HTML comment ... possible multiple content source HTML comments ... n. [template-header.html])(template-header.html) n+1. content generated by a tool such as pandoc n+2. template-footer.html

test.html

A test page for ioccc.css.

This page was modeled after the above mentioned templates with the "content generated by a tool such as pandoc" replaced with some j-random test text.

winner_dir.txt

A list of paths to winner directories that reside under year directories.

winner_id.txt

A text file containing winner_id strings: one winner_id per line.

year_prize.numbers

A macOS Numbers spreadsheet: one line per winner.

The first field is a winner_id.

The second field is the name of the award for given winner.

year_prize.csv

The year_prize.csv is a CSV file that was exported from the year_prize.numbers file.

In case of conflict, the data in year_prize.numbers file is considered authoritative over the year_prize.csv file.

The year_prize.csv.csv is generated from the year_prizes.numbers file, via the macOS Numbers spreadsheet app, as follows:

0. open year_prize.numbers in numbers: modify if/as needed

1. File -> Export To -> CSV...

   • 1a. [ ] Include table names (unset)
   • 1b. Text Encoding: Unicode (UTF-8)
   • 1c. Click ((Save..))

2. Save As: year_prize.csv

   • 2a. Select the tmp directory

3. Click ((Export))

   • 3a. If needed click ((Replace))

4. Execute ./fix_csv.sh