diff --git a/faq.md b/faq.md
index e4a3b27d8..40e1e9f65 100644
--- a/faq.md
+++ b/faq.md
@@ -50,6 +50,7 @@ other inconsistencies with the original entry?](#faq4_3)
- [5.2 - How may I submit a fix to an IOCCC winner?](#faq5_2)
- [5.3 - How may I report an IOCCC web site problem?](#faq5_3)
- [5.4 - How may I submit a fix to an IOCCC web site?](#faq5_4)
+- [5.5 - How may I correct or update IOCCC author information?](#faq5_5)
## Section 6 - [Miscellaneous IOCCC](#faq6)
- [6.0 - How did an entry breaks the size rule 2, win the IOCCC?](#faq6_0)
@@ -57,6 +58,9 @@ other inconsistencies with the original entry?](#faq4_3)
- [6.2 - May I mirror the IOCCC web site?](#faq6_2)
- [6.3 - May I use parts of the IOCCC in an article, book, newsletter, or instructional material?](#faq6_3)
- [6.4 - Why do you sometimes use the first person plural?](#faq6_4)
+- [6.5 - What is an author handle?](#faq6_5)
+- [6.6 - What is a author_handle.json file and how are they used?](#faq6_6)
+- [6.7 - What is a winner_id?](#faq6_7)
# The IOCCC FAQ
@@ -1349,8 +1353,6 @@ section may offer you important fixing clues.
### We welcome your help on fixing the IOCCC web site
-XXX
-
### FAQ 5.1: How do I report a bug in an IOCCC winner?
@@ -1455,7 +1457,7 @@ If you see lines containing:
```
This means that the file is generated by a tool from the
-[build-ioccc](https://github.com/ioccc-src/build-ioccc) repo
+[build-ioccc repo](https://github.com/ioccc-src/build-ioccc)
using files found in the
[ioccc-src/winner repo](https://github.com/ioccc-src/winner) repo.
@@ -1482,6 +1484,24 @@ When in doubt, consider opening up an [IOCCC issue](https://github.com/ioccc-src
See [FAQ 5.3](#faq5_3) for information on opening up an IOCCC issue.
+## FAQ 5.5: How may I correct or update IOCCC author information?
+
+Authors of IOCCC winning entries are kept in JSON files of the form:
+
+```
+author/author_handle.json
+```
+
+where _author_handle_ is an author handle. See [FAQ 6.5](#faq6_5) for more
+information about an author handles.
+
+The contents of these JSON files contain the best known information
+about authors of IOCCC winners. See [FAQ 6.6](#faq6_6) for information
+about the contents of these JSON file and how they are used.
+
+XXX
+
+
## Section 6: Miscellaneous IOCCC
@@ -1560,3 +1580,608 @@ exaggeration](https://books.google.com/books?id=ms3tce7BgJsC&lpg=PA134&vq=%22the
p.s. Here is an image of F. D. C. Willard:
[F D C Willard](png/F.D.C.Willard.png)
+
+
+### FAQ 6.5: What is an 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:
+
+```
+author/author_handle.json
+```
+
+See [FAQ 6.6](#faq6_6) for information about the contents of these JSON file and
+how they are used.
+
+Because the `author_handle` is used to form a JSON filename, the string must be
+POSIX safe string. Furthermore, the `author_handle` must be an ASCII
+string that matches this regexp:
+
+```re
+^[0-9A-Za-z][0-9A-Za-z_]*$
+```
+
+Default `author_handle`'s do not have multiple consecutive `_` (underscore)
+characters. Nevertheless, multiple consecutive `_` (underscore) characters are
+allowed. Contest submitters who wish to override their default `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 if they so
+desire.
+
+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:
+
+```
+Anonymous_year
+```
+
+or:
+
+```
+Anonymous_year.digits
+```
+
+
+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]*$
+```
+
+See [FAQ 5.5](#faq5_5) for information about how to update
+and/or correct IOCCC author information.
+
+
+### FAQ 6.6: What is a author_handle.json file and how are they used?
+
+**TL:DR**: The contents of these JSON files contain the best known
+information about authors of IOCCC winners and is used to help form
+HTML files as well to contact an author.
+
+The content of these JSON files are used by tools from the [build-ioccc
+repo](https://github.com/ioccc-src/build-ioccc) to help build HTML
+content for the [official IOCCC web site](https://www.ioccc.org).
+For example, the `index.html` file for each IOCCC winner contains
+selected information about the authors. Tools from the [build-ioccc
+repo](https://github.com/ioccc-src/build-ioccc) use the content of
+these JSON files to generate the `index.html` files for each IOCCC
+winning entry.
+
+Moreover, should the [IOCCC judges](judges.html) need to
+contact an authors of a IOCCC winner, they will consult the contents
+of the author's JSON file for ways to contact them.
+
+Each author of an IOCCC winning entry has their own `author_handle.json` file
+of the form:
+
+```
+author/author_handle.json
+```
+
+where _author_handle_ is an author handle. See [FAQ 6.5](#faq6_5) 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_README.md](https://github.com/ioccc-src/mkiocccentry/blob/master/jparse/json_README.md#so_called_json_spec)
+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
+```
+
+As of _Thu Nov 30 23:51:12 UTC 2023_, the contents was as follows:
+
+```json
+{
+ "no_comment" : "mandatory comment: because comments were removed from the original JSON spec",
+ "author_JSON_format_version" : "1.0 2023-06-10",
+ "author_handle" : "Yusuke_Endoh",
+ "full_name" : "Yusuke Endoh",
+ "sort_word" : "endoh",
+ "location_code" : "JP",
+ "location_name" : "Japan",
+ "email" : "mame@ruby-lang.org",
+ "url" : "https://mametter.hatenablog.com",
+ "alt_url" : null,
+ "deprecated_twitter_handle" : null,
+ "mastodon" : "@mame@ruby.social",
+ "mastodon_url" : "https://ruby.social/@mame",
+ "github" : "@mame",
+ "affiliation" : null,
+ "winning_entry_set" : [
+ { "winner_id" : "2012_endoh1" },
+ { "winner_id" : "2012_endoh2" },
+ { "winner_id" : "2013_endoh1" },
+ { "winner_id" : "2013_endoh2" },
+ { "winner_id" : "2013_endoh3" },
+ { "winner_id" : "2013_endoh4" },
+ { "winner_id" : "2014_endoh1" },
+ { "winner_id" : "2014_endoh2" },
+ { "winner_id" : "2015_endoh1" },
+ { "winner_id" : "2015_endoh2" },
+ { "winner_id" : "2015_endoh3" },
+ { "winner_id" : "2015_endoh4" },
+ { "winner_id" : "2018_endoh1" },
+ { "winner_id" : "2018_endoh2" },
+ { "winner_id" : "2019_endoh" },
+ { "winner_id" : "2020_endoh1" },
+ { "winner_id" : "2020_endoh2" },
+ { "winner_id" : "2020_endoh3" }
+ ]
+}
+```
+
+We now will walk thru the above JSON document looking at various 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.
+
+
+##### author_JSON_format_version
+
+```json
+ "author_JSON_format_version" : "1.0 2023-06-10",
+```
+
+This _JSON member_ holds the format version of the `author_handle.json` JSON file.
+
+There **MUST** be one and only one `author_JSON_format_version`
+_JSON member_ and the _JSON value_ **MUST** be a _JSON string_.
+
+This is **NOT** the version of the contents! When updating an
+`author_handle.json` JSON file, **DO NOT MODIFY author_JSON_format_version**!
+As of _Thu Nov 30 23:51:12 UTC 2023_, the _JSON value_ **MUST** be _"1.0 2023-06-10"_.
+
+The _author_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 web site](https://www.ioccc.org) would be the one to do this
+in conjunction with changes to the [build-ioccc
+repo](https://github.com/ioccc-src/build-ioccc).
+
+
+##### author_handle
+
+```json
+ "author_handle" : "Yusuke_Endoh",
+```
+
+This _JSON member_ holds the author handle of the author.
+
+There **MUST** be one and only one `author_handle` _JSON member_
+and the _JSON value_ **MUST** be a _JSON string_ that is also a value author handle.
+
+See [FAQ 6.5](#faq6_5) 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 `.winner.json` files for all of this authors
+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.
+
+
+##### full_name
+
+```json
+ "full_name" : "Yusuke Endoh",
+```
+
+This _JSON member_ holds the full name of the author.
+
+There **MUST** be one and only one `full_name` _JSON member_ and the _JSON value_ **MUST**
+be a _JSON string_.
+
+The full name of an author may use non-ASCII characters so long as the
+full name is properly encoded as a _JSON string_.
+
+
+##### sort_word
+
+```json
+ "sort_word" : "endoh",
+```
+
+This _JSON member_ holds the string that will be used to sort the author.
+
+There **MUST** be one and only one `sort_word` _JSON member_ and the _JSON value_ **MUST**
+be a _JSON string_. Moreover the string **MUST** be a lower case ASCII
+alphanumeric string that starts with a lower case ASCII letter.
+
+The _JSON value_ is used, for example, to place a reference to the author
+in the `/winners.html` file.
+
+Normally the `sort_word` _JSON member_ _JSON value_ is the last
+name of the author, translated into lower case ASCII alphanumeric
+string that starts with a lower case ASCII letter. If the author
+wishes to be found in the `/winners.html` file under a different
+string, such as if they wish to be listed under their first name
+or their username, then they may change this accordingly.
+
+
+##### location_code
+
+```json
+ "location_code" : "JP",
+```
+
+This _JSON member_ holds the string that is the
+[ISO 3166-1 alpha-2 code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Decoding_table)
+of the author's location or country.
+
+There **MUST** be one and only one `location_code` _JSON member_ and the _JSON value_ **MUST**
+be a _JSON string_. Moreover the string **MUST** be 2 character UPPER case ASCII
+alphabetic string that is **NOT** an Unassigned
+[ISO 3166-1 alpha-2 code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Decoding_table) value
+(not a 2 character symbol with a gray background on that Wikipedia table)
+
+The `soup/location` tool from the [mkiocccentry repo](https://github.com/ioccc-src/mkiocccentry),
+when run without arguments, will print the ISO 3166-1 alpha-2 codes that permitted, along with
+the location name.
+
+We use the term "location" (and not "country") because some of the
+ISO 3166-1 alpha-2 codes belong to locations that are not technically
+a country, such as "Antarctica" or a User-assigned code.
+
+If the author wishes to not specify a location, they should select **XX**.
+
+
+##### location_name
+
+```json
+ "location_name" : "Japan",
+```
+
+This _JSON member_ holds the string that is the canonical location name as reported by the
+`soup/location` tool from the [mkiocccentry repo](https://github.com/ioccc-src/mkiocccentry),
+when given the [location code](#location_code) as specified above.
+
+There **MUST** be one and only one `location_code` _JSON member_ and the _JSON value_ **MUST**
+be a _JSON string_. Moreover the string **MUST** be what the `soup/location` tool prints
+when given the `location_code` as an argument.
+
+We use the term "location" (and not "country") because some of the
+ISO 3166-1 alpha-2 codes belong to locations that are not technically
+a country, such as "Antarctica" or a User-assigned code.
+
+Often a given location may have a long official name, and multiple common names.
+For names associated with the location **DE** might be:
+
+```
+Germany
+Federal Republic of Germany
+Bundesrepublik Deutschland
+Deutschland
+...
+```
+
+The "location_name" printed by the `soup/location` tool is often a
+short, common string that is sometimes called the formal location
+name for the given ISO 3166 code. Thus in the above example for _DE_,
+the location name of _Germany_ is used.
+
+If the author wishes to not specify a location, they should select **Anonymous location**.
+
+
+##### email
+
+```json
+ "email" : "mame@ruby-lang.org",
+```
+
+This _JSON member_ holds the email address of the author, or is the value null.
+
+There **MUST** be one and only one `email` _JSON member_ and the _JSON value_ **MUST**
+be a _JSON string_ or it **MUST** be a _JSON null_.
+
+If the author wishes to not specify an email address, or if the email address is
+unknown, they should use the _JSON null_ as the _JSON value_ of this _JSON member_.
+For example:
+
+```json
+ "email" : null,
+```
+
+NOTE: The _JSON null_ is **NOT** enclosed in quotes!
+
+
+##### url
+
+```json
+ "url" : "https://mametter.hatenablog.com",
+```
+
+This _JSON member_ holds the URL of the author's home page.
+
+There **MUST** be one and only one `url` _JSON member_ and the _JSON value_ **MUST**
+be a _JSON string_ or it **MUST** be a _JSON null_.
+
+If the author wishes to not specify an email address, or if the URL is
+unknown, they should use the _JSON null_ as the _JSON value_ of this _JSON member_.
+For example:
+
+```json
+ "url" : null,
+```
+
+NOTE: The _JSON null_ is **NOT** enclosed in quotes!
+
+
+##### alt_url
+
+```json
+ "alt_url" : null,
+```
+
+This _JSON member_ holds an alternate or 2nd URL a home page for the author.
+
+There **MUST** be one and only one `url` _JSON member_ and the _JSON value_ **MUST**
+be a _JSON string_ or it **MUST** be a _JSON null_.
+
+In some cases the author may wish to record a special URL for their IOCCC entry,
+or a 2nd URL such as a work or school or personal home page. For example,
+Cody as of _Thu Nov 30 23:51:12 UTC 2023_ used:
+
+```json
+ "alt_url" : "https://ioccc.xexyl.net",
+```
+
+If the author wishes to not specify an email address, or if the alternate URL is
+unknown, they should use the _JSON null_ as the _JSON value_ of this _JSON member_.
+For example:
+
+```json
+ "url" : null,
+```
+
+NOTE: The _JSON null_ is **NOT** enclosed in quotes!
+
+
+##### deprecated_twitter_handle
+
+This _JSON member_ used to hold the twitter handle of the author.
+
+There **MUST** be one and only one `deprecated_twitter_handle` _JSON member_ and the _JSON value_ **MUST**
+be a _JSON string_ or it **MUST** be a _JSON null_.
+
+The IOCCC no longer is associated with twitter (or whatever someone chooses to call it),
+and so the `deprecated_twitter_handle` is **no longer used**. A _JSON value_ that is
+not a _JSON null_ is kept for only historic reasons. For example, Anthony C. Howe
+once used:
+
+```json
+ "deprecated_twitter_handle" : "@SirWumpus",
+```
+
+If the author wishes to not specify an twitter handle, or if the twitter handle is
+unknown, they should use the _JSON null_ as the _JSON value_ of this _JSON member_.
+For example:
+
+```json
+ "deprecated_twitter_handle" : null,
+```
+
+NOTE: The _JSON null_ is **NOT** enclosed in quotes!
+
+
+##### mastodon
+
+```json
+ "mastodon" : "@mame@ruby.social",
+```
+
+This _JSON member_ holds the
+[Mastodon social network](https://en.wikipedia.org/wiki/Mastodon_\(social_network\))
+handle of the author.
+
+There **MUST** be one and only one `mastodon` _JSON member_ and the _JSON value_ **MUST**
+be a _JSON string_ or it **MUST** be a _JSON null_. The _JSON string_ just be a valid
+Mastodon handle. In particular is must start with an at sign (_@_), followed by the
+Mastodon username, followed by a 2nd sign (_@_), followed by the Mastodon server instance
+used by the author.
+
+For more information in Mastodon, see the [Mastodon help](https://mastodon.help) guide.
+See the "Mastodon Address" section of that page in particular.
+
+The IOCCC Mastodon handle is:
+
+```json
+@ioccc@fosstodon.org
+```
+
+The IOCCC uses the Mastodon social network for announcements such
+as the opening and closing of a new IOCCC, changes to the IOCCC web
+site, updates during the judging process, and when new IOCCC winners
+are selected. We recommend you follow us on Mastodon.
+
+If the author wishes to not specify an Mastodon handle, or if the Mastodon handle is
+unknown, they should use the _JSON null_ as the _JSON value_ of this _JSON member_.
+For example:
+
+```json
+ "mastodon" : null,
+```
+
+NOTE: The _JSON null_ is **NOT** enclosed in quotes!
+
+
+##### mastodon_url
+
+```json
+ "mastodon_url" : "https://ruby.social/@mame",
+```
+
+This _JSON member_ holds the URL of the author's Mastodon page.
+
+There **MUST** be one and only one `mastodon_url` _JSON member_ and the _JSON value_ **MUST**
+be a _JSON string_ or it **MUST** be a _JSON null_. The _JSON string_ just be a valid URL.
+If the `mastodon` handle is a _JSON null_, them the `mastodon_url` **MUST** be a _JSON null_.
+If the `mastodon` handle is a _JSON string_, then the `mastodon_url` **MUST** be a _JSON string_.
+
+The `mastodon_url` is just a translation of the above mentioned [mastodon](#mastodon) handle.
+For example, if the Mastodon handle is:
+
+```
+@user@server.domain
+```
+
+Then the `mastodon_url` would be:
+
+```
+https://server.domain/@user
+```
+
+If the author wishes to not specify an Mastodon URL, or if the Mastodon URL is
+unknown, they should use the _JSON null_ as the _JSON value_ of this _JSON member_.
+For example:
+
+```json
+ "mastodon_url" : null,
+```
+
+NOTE: The _JSON null_ is **NOT** enclosed in quotes!
+
+
+##### github
+
+```json
+ "github" : "@mame",
+```
+
+This _JSON member_ holds the [GitHub](https://github.com) handle of the author.
+
+There **MUST** be one and only one `github` _JSON member_ and the _JSON value_ **MUST**
+be a _JSON string_ or it **MUST** be a _JSON null_. The `github` _JSON string_ **MUST**
+start with an at sign (_@_) and **MUST** be a valid GitHub username.
+
+The IOCCC uses GitHub to hold the [official winner repo of the IOCCC](https://github.com/ioccc-src/winner),
+and hosts [official IOCCC web site](https://www.ioccc.org) on GitHub pages.
+
+The IOCCC GitHub handle is:
+
+```
+@ioccc-src
+```
+
+If the author wishes to not specify an GitHub handle, or if the GitHub handle is
+unknown, they should use the _JSON null_ as the _JSON value_ of this _JSON member_.
+For example:
+
+```json
+ "github" : null,
+```
+
+NOTE: The _JSON null_ is **NOT** enclosed in quotes!
+
+
+##### affiliation
+
+```json
+ "affiliation" : null,
+```
+
+This _JSON member_ holds the affiliation of the author.
+
+There **MUST** be one and only one `affiliation` _JSON member_ and the _JSON value_ **MUST**
+be a _JSON string_ or it **MUST** be a _JSON null_.
+
+An affiliation might be the name of a school, university, company, or organization.
+It is recommended that the affiliation _JSON string_ be the formal affiliation name.
+For example, the affiliation for the IOCCC would be:
+
+```
+The International Obfuscared C Code Contest
+```
+
+If the author wishes to not specify an affiliation, or if the affiliation is
+unknown, they should use the _JSON null_ as the _JSON value_ of this _JSON member_.
+For example:
+
+```json
+ "affiliation" : null,
+```
+
+NOTE: The _JSON null_ is **NOT** enclosed in quotes!
+
+
+##### winning_entry_set
+##### winner_id
+
+```json
+ "winning_entry_set" : [
+ { "winner_id" : "2012_endoh1" },
+ { "winner_id" : "2012_endoh2" },
+ { "winner_id" : "2013_endoh1" },
+...
+ { "winner_id" : "2020_endoh1" },
+ { "winner_id" : "2020_endoh2" },
+ { "winner_id" : "2020_endoh3" }
+ ]
+```
+
+The `winning_entry_set` _JSON member_ holds _JSON array_ containing one or more `winner_id` _JSON member_s.
+
+There **MUST** be one and only one `winning_entry_set` and the _JSON value_ **MUST**
+be a non-empty _JSON array_. Each value in that _JSON array_ **MUST** must contain
+a _JSON member_ whose _JSON name_ **MUST** be "_winner_id_" and those _JSON value_
+is a valid winner ID.
+
+Due to the nature of the _So-called JSON spec_, the last value of the `winning_entry_set`
+_JSON array_ cannot end in a comma (_,_).
+
+See [FAQ 6.7](#faq6_7) for information about winner ids.
+
+See [FAQ 5.5](#faq5_5) for information about how to update
+and/or correct IOCCC author information.
+
+
+### FAQ 6.7: What is a winner_id?
+
+A `winner_id` is a string that identifies a winning entry of the IOCCC.
+
+A `winner_id` is a 4-digit year, followed by an underscore, followed by a directory name.
+
+For example, the `winner_id` associated with Cody Boone Ferguson's 2nd winning IOCCC entry
+of 2020 is found under the following directory:
+
+```
+2020/ferguson2
+```
+
+The `winner_id` for that winning entry is:
+
+```
+2020_ferguson2
+```