Typo and format fix tmp/README.md
...at least temporarily :-)
This commit is contained in:
Cody Boone Ferguson committed
1 parent
2949e9f0c3
commit
c5f5e42bd3
1 file changed
+114
-84
+114
-84
@@ -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:
|
||||
|
||||
|
||||
Reference in new issue
Block a user