diff --git a/tmp/README.md b/tmp/README.md index 847338b23..319e6b3a1 100644 --- a/tmp/README.md +++ b/tmp/README.md @@ -4,7 +4,7 @@ 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. -This documentation is here to help define terms, file under `tmp` +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 @@ -12,17 +12,17 @@ later on, after the contents ## terms -* author +### `author` -An individual who was an `author` of at least one IOCCC entry. +An individual who was an `author` of at least one winning IOCCC entry. -Some authors have submitted more than one IOCCC entry that won. -Some winning IOCCC entries have more than one author. +Some authors have submitted more than one IOCCC entry that won. Some winning +IOCCC entries have more than one author. -* author_handle +### `author_handle` -An `author_handle` is string that refers to a given author and is unique -to the IOCCC. Each author has one, and only one `author_handle`. +An `author_handle` is string that refers to a given author and is unique to the +IOCCC. Each author has exactly one `author_handle`. For each `author_handle`, there will be a JSON file of the form: @@ -30,28 +30,27 @@ For each `author_handle`, there will be a JSON file of the form: author/author_handle.json ``` -Because the `author_handle` is used to form a JSON filename, the -string must be lower case POSIX safe string. Furthermore, the -author_handle must of an ASCII string that matches this regexp: +Because the `author_handle` is used to form a JSON filename, the string must be +lower case POSIX safe string. Furthermore, the `author_handle` must be an ASCII +string that matches this regexp: ```re ^[0-9a-z][0-9a-z_]*$ ``` -Default `author_handle`'s do not have multiple consecutive -_ (underscore) characters. Nevertheless, multiple consecutive -_ (underscore) characters are allowed. Users who wish to -override the +Default `author_handle`'s do not have multiple consecutive `_` (underscore) +characters. Nevertheless, multiple consecutive `_` (underscore) characters are +allowed. Contest submitters who wish to override the `author_handle` may do so. -The `author_handle` is derived from the name of the author. -While there is a algorithm that maps the name of the author -(which can contain any UTF-8 characters) into a default -`author_handle` string, those who submit an entry to the IOCCC -are free to choose a different `author_handle` string. +The `author_handle` is derived from the name of the author. While there is a +algorithm that maps the name of the author (which can contain any UTF-8 +characters) into a default `author_handle` string, those who submit an entry to +the IOCCC are free to choose a different `author_handle` string if they so +desire. -An `author` who has won a previous IOCCC is encouraged to -reuse their author_handle so that new winners an be associated -with the same author. +An `author` who has won a previous IOCCC is encouraged to reuse their +`author_handle` so that new winning entries can be associated with the same +author. For an anonymous `author`, their handle is one of these forms: @@ -65,34 +64,38 @@ or: Anonymous_year.digits ``` -The latter form is in case there are more than one -anonymous author in a given year. -Anonymous author_handle's match this regexp: +The latter form is in case there are more than one anonymous author in a given +year. + +NOTE: even if the directory name is not `anonymous` the above rules apply as in +in the case of [2005/anon](/2005/anon/anon.c). + +Anonymous `author_handle`'s match this regexp: ```re Anonymous_[0-9][0-9][0-9][0-9][.0-9]*$ ``` -* winner +### `winner` An IOCCC entry that won an award for given IOCCC. A `winner` has one more more `author`s. Each `winner` is contained under its own directory. The parent of the winner directory -is a year directory. +is the year's directory. While in most cases a `winner` consists of files under a `winner` directory, -there are a few cases where a `winner` directory contains sub-directories. +there are a few cases where a `winner` directory contains subdirectories. -Use of sub-directories under a `winner` directory is discouraged and +Use of subdirectories under a `winner` directory is discouraged and may be limited to previous `winner`s that used them. -* year +### `year` A `year` is a 4 character string. Most years are 4-digit strings that -represent the year. Some special `year` strings are possible, such as "_mock_". +represent the year. Some special `year` strings are possible, such as _`mock`_. Non-numeric `year` strings are lower case. A `year` string matches this regexp: @@ -103,7 +106,7 @@ A `year` string matches this regexp: The `year` directories reside directly below the top level directory. -* .year +### `.year` Each `year` will have a file directory under it named: @@ -111,9 +114,10 @@ Each `year` will have a file directory under it named: .year ``` -The contents of "_.year_" file is the year string of the directory. +The contents of the `.year` file is the year string of the directory. For +instance, [2020/.year](/2020/.year) has the string: `2020`. -* dir +### `dir` A `dir` is a POSIX safe string that holds an winner. @@ -126,7 +130,7 @@ A `dir` is a string that matches this regexp: Each `winner` is under its own individual directory. This directory is directly under a `year` directory. -* winner_id +### `winner_id` A string that identifies the winning entry. The string is of the form: @@ -134,7 +138,7 @@ A string that identifies the winning entry. The string is of the form: year_dir ``` -* .id +### `.id` Each `winner` directory will have a file directory under it named: @@ -142,12 +146,12 @@ Each `winner` directory will have a file directory under it named: .id ``` -The contents of "_.id_" file is the `winner_id` string for that `winner`. +The contents of `_.id_` file is the `winner_id` string for that `winner`. -* sort_word +* `sort_word` -A string that is used to determine the position within the `winners.html` file, -a `author` and the `winners` they submitted are to be listed. +A string that is used to determine the position within the `winners.html` file; +an `author` and the `winners` they submitted are to be listed. A `sort_word` match this regexp: @@ -157,108 +161,134 @@ A `sort_word` match this regexp: ## files -- [author-names.txt](author-names.txt) +### [author-names.txt](author-names.txt) A text file of full names of each `author`: one full name per line. -- [author-wins.csv](author-wins.csv) +In the case of anonymous authors the form is: -A CSV file: one line per `author`. +``` +Anonymous YYYY +``` -The 1st field is a `author_handle`. +### [author-wins.csv](author-wins.csv) -The 2nd and later fields are the `winner_id`'s of all `winner`s won by the `author`. +A CSV (Comma Separated Values) file: one line per `author`. -- [author.csv](author.csv) +The first field is an `author_handle`. + +The other fields are the `winner_id`'s of all `winner`s won by the `author`. + +### [author.csv](author.csv) The [author.csv](author.csv) is a CSV file that was exported from the [author.numbers](author.numbers) file. -In case of conflict, the data in [author.numbers](author.numbers) file is considered -authoritative over the [author.csv](author.csv) file. +In case of conflict, the data in [author.numbers](author.numbers) file is +considered authoritative over the [author.csv](author.csv) file. The [author.csv](author.csv) is generated from the [author.numbers](author.numbers) file, -via the macOS numbers spreadsheet app, as follows: +via the [macOS](https://www.apple.com/macos/) +[Numbers](https://www.apple.com/numbers/) spreadsheet app, as follows: 0. open [author.csv](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..)) + * 1a. `[ ]` Include table names (unset) + * 1b. Text Encoding: Unicode (UTF-8) + * 1c. Click ((Save..)) + 2. Save As: author.csv -2a. Select the `tmp` directory + * 2a. Select the `tmp` directory + 3. Click ((Export)) -3a. If needed click ((Replace)) + * 3a. If needed click ((Replace)) + 4. open a terminal window + 5. cd to the `tmp` directory + 6. tr -d '\015' < author.csv > tmp.csv + 7. echo >> tmp.csv + 8. mv -f tmp.csv author.csv -- [author.numbers](author.numbers) +### [author.numbers](author.numbers) -A macOS numbers spreadsheet contain information about `author`s: one line per `author`. +A [macOS](https://www.apple.com/macos) [Numbers](https://www.apple.com/numbers/) +spreadsheet contains information about `author`s: one line per `author` with the +following fields: -The 1st field is `sort_word` string. + +1. This field is `sort_word` string. -The 2nd field is the full name of the `author`. +2. This field is the full name of the `author`. -The 3rd field is the `author_handle` of the `author`. +3. This field is the `author_handle` of the `author`. -The 4th field is the primary URL of `author` or the string "_null_" if none was given. +4. This field is the primary URL of `author` or the string `null` if none was +given. -The 5th field is the email address 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. -The 6th field is the location ISO 3166 code of `author` or the string "_null_" is unknown. +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. +use the code `XX`. The location ISO 3166 code consists of two UPPER CASE ASCII letters. -The 7th 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. +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. -The 8th field is the mastodon handle of the `author` or the string "_null_" if none was given. +8. This field is the mastodon handle of the `author` or the string `null` if +none was given. -The 9th field is the alternate URL of `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_handle.txt](author_handle.txt) +### [author_handle.txt](author_handle.txt) -A text file containing `author_handle`s for each `author`: one `author_handle` per line. +A text file containing `author_handle`s for each `author`: one `author_handle` +per line. -- [example.author.json](example.author.json) +### [example.author.json](example.author.json) -This is a JSON file containing an example `author/author_handle.json` for a fictitious `author`. +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](author.csv) file and the [author-wins.csv](author-wins.csv) file. -- [example.dot_winner.json](example.dot_winner.json) +### [example.dot_winner.json](example.dot_winner.json) -This is a JSON file containing an example `year/dir/.winner.json` for a fictitious `winner`. +This is a JSON file containing an example `year/dir/.winner.json` for a +fictitious `winner`. -An `year/dir/.winner.json` file will be derived from the contents the `year/dir/.id` file, +A `year/dir/.winner.json` file will be derived from the contents the `year/dir/.id` file, the [author-wins.csv](author-wins.csv) file, the `year/dir/.year` file, and the contents of the `year/dir` directory. -- [sql/winners.sql](sql/winners.sql) +### [sql/winners.sql](sql/winners.sql) -This is a historic SQL command the that was used in the past to generate data -for the old winners directory tree. +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. -- [winner_id.txt](winner_id.txt) +### [winner_id.txt](winner_id.txt) A text file containing `winner_id` strings: one `winner_id` per line. -- [year-prize.csv](year-prize.csv) +### [year-prize.csv](year-prize.csv) A CSV file: one line per `winner`. -The 1st field is a `winner_id`. +The first field is a `winner_id`. -The 2nd field is the name of the award for given `winner`. +The second field is the name of the award for given `winner`. -* [gen_author_json.sh](gen_author_json.sh) +### [gen_author_json.sh](gen_author_json.sh) -Temporary tool used to generate the author/author_handle.json files. +Temporary tool used to generate the `author/author_handle.json` files. The following command, executed in this directory, created the `author/` directory: