mirror/ioccc
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

improve FAQ 5.5 and FAQ 6.16

Browse Source 
We improve FAQ 5.5 (correcting or updating IOCCC author information)
by adding a generic example on changing author's URL.

Now the "PLEASE HELP us identify proper locations for IOCCC authors"
(that now follows the change of URL example) contains only
generic information about changing the location_code from ZZ to AU.

We remove the indirect reference to author email in FAQ 6.16 as we
do not wish to call out what we previously included in the
`authors.html` page.

This commit modifies that otherwise perfect fine PR #2578.

Performed `make www` to accomplish the above and to test under macOS.
This commit is contained in:
Landon Curt Noll committed 2024-07-17 12:25:23 -07:00
1 parent 22e483723c
commit 43fafd0af6
2 files changed
+103 -116
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

faq.html
+43 -53
View File
@@ -1864,7 +1864,7 @@ entries that do not win on their web page for everyone to see.</p>
<div id="faq2_3"> <div id="faq2_3">
<h3 id="faq-2.3-how-much-time-does-it-take-to-judge-the-contest">FAQ 2.3: How much time does it take to judge the contest?</h3> <h3 id="faq-2.3-how-much-time-does-it-take-to-judge-the-contest">FAQ 2.3: How much time does it take to judge the contest?</h3>
</div> </div>
<p>It takes a fair amount of time to setup, run, answer email, process entries, <p>It takes a fair amount of time to setup, run, respond to messages, process entries,
review entries, trim down the set entries to a set of winning entries, doing the review entries, trim down the set entries to a set of winning entries, doing the
write-up of the entries, announcing the entries, reviewing final edits of the write-up of the entries, announcing the entries, reviewing final edits of the
winning entry set, posting the winning entries, being flamed :-), tell folks who send in winning entry set, posting the winning entries, being flamed :-), tell folks who send in
@@ -3189,15 +3189,14 @@ for information on opening up an IOCCC issue.</p>
<h2 id="faq-5.5-how-may-i-correct-or-update-ioccc-author-information">FAQ 5.5: How may I correct or update IOCCC author information?</h2> <h2 id="faq-5.5-how-may-i-correct-or-update-ioccc-author-information">FAQ 5.5: How may I correct or update IOCCC author information?</h2>
</div> </div>
</div> </div>
<h4 id="please-help-us-identify-proper-locations-for-ioccc-authors">PLEASE HELP us identify proper locations for IOCCC authors</h4> <p>You may correct or update IOCCC author information by submitting a
<p>If you know the location of an author listed under:</p> GitHub pull request that modifies an author’s <code>author_handle.json</code> file.</p>
<p>      <strong><a href="location.html#ZZ">ZZ - Unknown location</a></strong></p> <p>For example, if a given <code>author_handle.json</code> file contained:</p>
<p>or if you find IOCCC author location that is incorrect, <pre><code> &quot;url&quot; : &quot;https://www.example.com/employee/username&quot;,</code></pre>
then <strong>please submit a pull request</strong>, <p>and you knew that the author has long ago left the <code>www.example.com</code> company,
or at least <a href="contact.html">inform the IOCCC judges</a>.</p> and that they have a new faculty web page at <code>www.example.edu</code>, then you should
<p>See the submit a GitHub pull request to change the above line to:</p>
FAQ on “<a href="#pull_request">GitHub pull request</a>” <pre><code> &quot;url&quot; : &quot;https://www.example.edu/faculty/department/user.name&quot;,</code></pre>
for more information.</p>
<p>Authors of IOCCC winning entries are kept in JSON files of the form:</p> <p>Authors of IOCCC winning entries are kept in JSON files of the form:</p>
<pre><code> author/author_handle.json</code></pre> <pre><code> author/author_handle.json</code></pre>
<p>where <code>author_handle</code> is an author handle.</p> <p>where <code>author_handle</code> is an author handle.</p>
@@ -3206,60 +3205,57 @@ FAQ on “<a href="#author_handle_faq">author handle</a>”
for more information about author handles.</p> for more information about author handles.</p>
<p>See the <p>See the
FAQ on “<a href="#author_json">author_handle.json</a>” FAQ on “<a href="#author_json">author_handle.json</a>”
for information about the contents of these JSON file and how they are used.</p> for information about the contents of these JSON files and how they are used.</p>
<p>See the <p>See the
FAQ on “<a href="#find_author_handle">finding author handles</a>” FAQ on “<a href="#find_author_handle">finding author handles</a>”
for how to find your own <em>author_handle</em>.</p> for how to find an <em>author_handle</em>.</p>
<p>The contents of these JSON files contain the best known information
about authors of IOCCC entries. See
FAQ on “<a href="#author_json">author_handle.json</a>”
for information about the contents of these JSON file and how they are used.</p>
<p>You may update IOCCC author information in a <code>author_handle.json</code> file <p>You may update IOCCC author information in a <code>author_handle.json</code> file
by <a href="#pull_request">submitting a pull request</a> by <a href="#pull_request">submitting a pull request</a>
against the <a href="https://github.com/ioccc-src/winner/branches">master branch</a> against the <a href="https://github.com/ioccc-src/winner/branches">master branch</a>
of the <a href="https://github.com/ioccc-src/winner">ioccc-src/winner repo</a>.</p> of the <a href="https://github.com/ioccc-src/winner">ioccc-src/winner repo</a>.</p>
<p>As these files are JSON you should verify that they are validly formed (e.g. you <p>See the
didn’t make a typo).</p> FAQ on “<a href="#pull_request">GitHub pull request</a>”
<p>Please make sure that you run <code>make www</code> after updating the file or files. This unfortunately for more information.</p>
takes quite a while but it is the safest way to do it. There are other ways to go <p><strong>IMPORTANT NOTE</strong>: As these files are JSON you should verify that
about this that can speed things up. Here is one such way which was done when they are validly formed (e.g., you didn’t make a typo).</p>
fixing two authors in 1995 (in one commit as they were the authors of the same <p>Before you form your GitHub pull request that modifies a
two entries):</p> <code>author_handle.json</code> file, please run the <code>make www</code> command. This
<p>First, the two files, <a href="author/Heather_Downs.json">author/Heather_Downs.json</a> and unfortunately takes quite a while but it is the safest way to do
<a href="author/Selene_Makarios.json">author/Selene_Makarios.json</a> were fixed (the it. So you may wish to test your edits by running the somewhat
location was set as <code>ZZ</code> but Cody Boone Ferguson knew from the archive that it quicker <code>make quick_www</code> as this can speed up your testing.</p>
was the US for both of them and he also noticed that the URL, the same for <p>The <code>make quick_www</code> rule will update the <code>authors.html</code> and
both, was no longer valid and it was also known that the email was no longer
valid as it referred to the same domain). Thus the <code>location_code</code>, <code>url</code> (it was on the Internet Wayback Machine) and
in one case the <code>email</code> lines to look like:</p>
<pre class="&lt;--json--&gt;"><code> &quot;location_code&quot; : &quot;US&quot;,
&quot;email&quot; : null,
&quot;url&quot; : &quot;https://web.archive.org/web/19961019045145/http://www.bungalow.com/&quot;,</code></pre>
<p>Now since only two entries (the same entries) were won by these two individuals
it means that only two index.html files had to be updated, besides the
<a href="authors.html">authors.html</a> and <a href="location.html">location.html</a> files. These
are: <a href="1995/heathbar/index.html">1995/heathbar/index.html</a> and
<a href="1995/makarios/index.html">1995/makarios/index.html</a>. Thus the following
procedure was done:</p>
<pre class="&lt;!--sh--&gt;"><code> touch 1995/heathbar/README.md 1995/makarios/README.md
make quick_www</code></pre>
<p>That works because the <code>quick_www</code> rule will update the <code>authors.html</code> and
<code>location.html</code> pages and it will also check the timestamps of the <code>index.html</code> <code>location.html</code> pages and it will also check the timestamps of the <code>index.html</code>
files versus the <code>README.md</code> files. Since they were touched and thus the files versus the <code>README.md</code> files. Since they were touched and thus the
timestamp was updated, the timestamp was updated, the
<a href="https://github.com/ioccc-src/temp-test-ioccc/blob/master/bin/quick-readme2index.sh">bin/quick-readme2index.sh</a> tool would <a href="https://github.com/ioccc-src/temp-test-ioccc/blob/master/bin/quick-readme2index.sh">bin/quick-readme2index.sh</a> tool would
only worry about those two files. This greatly speeds things along.</p> only worry about those two files. This greatly speeds things along while testing.
<p>Once that command finishes a proper <code>git status</code> and <code>git diff</code> shows that Nevertheless, doing a final <code>make www</code> is still recommended best practice
everything is in order. In the end the safest way is to run <code>make www</code>, however.</p> before you form your pull request.</p>
<p>Please see <p>Please see
FAQ on “<a href="#fix_an_entry">fixing an entry</a>”.</p> FAQ on “<a href="#fix_an_entry">fixing an entry</a>”.</p>
<p>See also the <p>See also the
FAQ on “<a href="#pull_request">GitHub pull request</a>” FAQ on “<a href="#pull_request">GitHub pull request</a>”
for more information about pull requests.</p> for more information about pull requests.</p>
<h4 id="please-help-us-identify-proper-locations-for-ioccc-authors">PLEASE HELP us identify proper locations for IOCCC authors</h4>
<p>If you know the location of an author listed under:</p>
<p>      <strong><a href="location.html#ZZ">ZZ - Unknown location</a></strong></p>
<p>or if you find IOCCC author location that is incorrect,
then <strong>please submit a pull request</strong>,
or at least <a href="contact.html">inform the IOCCC judges</a>.</p>
<p><strong>FYI</strong>: The <a href="location.html#ZZ">ZZ - Unknown location</a> is used for <p><strong>FYI</strong>: The <a href="location.html#ZZ">ZZ - Unknown location</a> is used for
historic winning authors whose location or country is not known, historic winning authors whose location or country is not known,
whereas the <a href="location.html#XX">XX - Anonymous location</a> is used when the whereas the <a href="location.html#XX">XX - Anonymous location</a> is used when the
winning author does <strong>not wish to disclose their location</strong>.</p> winning author does <strong>not wish to disclose their location</strong>.</p>
<p>The contents of these JSON files contain the best known information
about authors of IOCCC entries. See
FAQ on “<a href="#author_json">author_handle.json</a>”
for information about the contents of these JSON files and how they are used.</p>
<p>For example, if a given <code>author_handle.json</code> file contained:</p>
<pre><code> &quot;location_code&quot; : &quot;ZZ&quot;,</code></pre>
<p>and you knew that the author was located in <a href="location.html#AU">Australia</a>
(location code <strong>AU</strong>), we encourage you to submit a <strong>GitHub pull
request</strong> to change that line to:</p>
<pre><code> &quot;location_code&quot; : &quot;AU&quot;,</code></pre>
<h3 id="important-note-about-xx---anonymous-location">Important note about <strong>XX - Anonymous location</strong>:</h3> <h3 id="important-note-about-xx---anonymous-location">Important note about <strong>XX - Anonymous location</strong>:</h3>
<p>Unless you are the author who originally selected the <strong>XX - Anonymous <p>Unless you are the author who originally selected the <strong>XX - Anonymous
location</strong>, please do not attempt to change an <strong>XX - Anonymous location</strong>, please do not attempt to change an <strong>XX - Anonymous
@@ -3485,7 +3481,7 @@ for information about how to update
and/or correct IOCCC author information.</p> and/or correct IOCCC author information.</p>
<p>See the <p>See the
FAQ on “<a href="#auth_json">.auth.json</a>” FAQ on “<a href="#auth_json">.auth.json</a>”
for information about the contents of these JSON file and for information about the contents of these JSON files and
how they are used.</p> how they are used.</p>
<p>See the <p>See the
FAQ on “<a href="#find_author_handle">finding author handle</a>” FAQ on “<a href="#find_author_handle">finding author handle</a>”
@@ -4274,19 +4270,13 @@ information in the <a href="authors.html">authors.html</a> page.</p>
<p>There you will find various information including a link to their <p>There you will find various information including a link to their
<a href="authors.html">authors.html</a> information which includes various things like <a href="authors.html">authors.html</a> information which includes various things like
their GitHub account (if known), a URL or alternate UL, mastodon handle, their GitHub account (if known), a URL or alternate UL, mastodon handle,
location (if known and not anonymous location) and a link to their JSON author location (if known and not anonymous location) and a link to their JSON author file.</p>
file which has more information like email (if known).</p>
<p><strong>NOTE</strong>: you might wish to search google (or some other search engine) by their <p><strong>NOTE</strong>: you might wish to search google (or some other search engine) by their
name as sometimes you can find out their GitHub account even if it’s not in our name as sometimes you can find out their GitHub account even if it’s not in our
JSON files.</p> JSON files.</p>
<p>Of course if you know the author’s name you can go directly to <p>Of course if you know the author’s name you can go directly to
<a href="authors.html">authors.html</a> and click on their surname’s/last name’s/second <a href="authors.html">authors.html</a> and click on their surname’s/last name’s/second
name’s initial and then scroll down (if necessary) to the author in question.</p> name’s initial and then scroll down (if necessary) to the author in question.</p>
<p><strong>NOTE</strong>: previously we included email in the <a href="authors.html">authors.html</a> page
but we have decided against this. Nevertheless, the <code>author_handle</code> link under
the author links to a JSON file which has the email address if it is known,
which you might wish to consult. You might also wish to look at their URL or
alternate URL for more information.</p>
<hr style="width:10%;text-align:left;margin-left:0"> <hr style="width:10%;text-align:left;margin-left:0">
<p>Jump to: <a href="#">top</a></p> <p>Jump to: <a href="#">top</a></p>
<!-- <!--
faq.md
+60 -63
View File
@@ -1707,7 +1707,7 @@ entries that do not win on their web page for everyone to see.
### FAQ 2.3: How much time does it take to judge the contest? ### FAQ 2.3: How much time does it take to judge the contest?
</div> </div>
It takes a fair amount of time to setup, run, answer email, process entries, It takes a fair amount of time to setup, run, respond to messages, process entries,
review entries, trim down the set entries to a set of winning entries, doing the review entries, trim down the set entries to a set of winning entries, doing the
write-up of the entries, announcing the entries, reviewing final edits of the write-up of the entries, announcing the entries, reviewing final edits of the
winning entry set, posting the winning entries, being flamed :-), tell folks who send in winning entry set, posting the winning entries, being flamed :-), tell folks who send in
@@ -3708,19 +3708,22 @@ for information on opening up an IOCCC issue.
</div> </div>
</div> </div>
#### PLEASE HELP us identify proper locations for IOCCC authors You may correct or update IOCCC author information by submitting a
GitHub pull request that modifies an author's `author_handle.json` file.
If you know the location of an author listed under: For example, if a given `author_handle.json` file contained:
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;**[ZZ - Unknown location](location.html#ZZ)** ``` <!---json-->
"url" : "https://www.example.com/employee/username",
```
or if you find IOCCC author location that is incorrect, and you knew that the author has long ago left the `www.example.com` company,
then **please submit a pull request**, and that they have a new faculty web page at `www.example.edu`, then you should
or at least [inform the IOCCC judges](contact.html). submit a GitHub pull request to change the above line to:
See the ``` <!---json-->
FAQ on "[GitHub pull request](#pull_request)" "url" : "https://www.example.edu/faculty/department/user.name",
for more information. ```
Authors of IOCCC winning entries are kept in JSON files of the form: Authors of IOCCC winning entries are kept in JSON files of the form:
@@ -3736,66 +3739,38 @@ for more information about author handles.
See the See the
FAQ on "[author_handle.json](#author_json)" FAQ on "[author_handle.json](#author_json)"
for information about the contents of these JSON file and how they are used. for information about the contents of these JSON files and how they are used.
See the See the
FAQ on "[finding author handles](#find_author_handle)" FAQ on "[finding author handles](#find_author_handle)"
for how to find your own _author_handle_. for how to find an _author_handle_.
The contents of these JSON files contain the best known information
about authors of IOCCC entries. See
FAQ on "[author_handle.json](#author_json)"
for information about the contents of these JSON file and how they are used.
You may update IOCCC author information in a `author_handle.json` file You may update IOCCC author information in a `author_handle.json` file
by [submitting a pull request](#pull_request) by [submitting a pull request](#pull_request)
against the [master branch](https://github.com/ioccc-src/winner/branches) against the [master branch](https://github.com/ioccc-src/winner/branches)
of the [ioccc-src/winner repo](https://github.com/ioccc-src/winner). of the [ioccc-src/winner repo](https://github.com/ioccc-src/winner).
As these files are JSON you should verify that they are validly formed (e.g. you See the
didn't make a typo). FAQ on "[GitHub pull request](#pull_request)"
for more information.
Please make sure that you run `make www` after updating the file or files. This unfortunately **IMPORTANT NOTE**: As these files are JSON you should verify that
takes quite a while but it is the safest way to do it. There are other ways to go they are validly formed (e.g., you didn't make a typo).
about this that can speed things up. Here is one such way which was done when
fixing two authors in 1995 (in one commit as they were the authors of the same
two entries):
First, the two files, [author/Heather_Downs.json](author/Heather_Downs.json) and Before you form your GitHub pull request that modifies a
[author/Selene_Makarios.json](author/Selene_Makarios.json) were fixed (the `author_handle.json` file, please run the `make www` command. This
location was set as `ZZ` but Cody Boone Ferguson knew from the archive that it unfortunately takes quite a while but it is the safest way to do
was the US for both of them and he also noticed that the URL, the same for it. So you may wish to test your edits by running the somewhat
both, was no longer valid and it was also known that the email was no longer quicker `make quick_www` as this can speed up your testing.
valid as it referred to the same domain). Thus the `location_code`, `url` (it was on the Internet Wayback Machine) and
in one case the `email` lines to look like:
``` <--json--> The `make quick_www` rule will update the `authors.html` and
"location_code" : "US",
"email" : null,
"url" : "https://web.archive.org/web/19961019045145/http://www.bungalow.com/",
```
Now since only two entries (the same entries) were won by these two individuals
it means that only two index.html files had to be updated, besides the
[authors.html](authors.html) and [location.html](location.html) files. These
are: [1995/heathbar/index.html](1995/heathbar/index.html) and
[1995/makarios/index.html](1995/makarios/index.html). Thus the following
procedure was done:
``` <!--sh-->
touch 1995/heathbar/README.md 1995/makarios/README.md
make quick_www
```
That works because the `quick_www` rule will update the `authors.html` and
`location.html` pages and it will also check the timestamps of the `index.html` `location.html` pages and it will also check the timestamps of the `index.html`
files versus the `README.md` files. Since they were touched and thus the files versus the `README.md` files. Since they were touched and thus the
timestamp was updated, the timestamp was updated, the
[bin/quick-readme2index.sh](%%REPO_URL%%/bin/quick-readme2index.sh) tool would [bin/quick-readme2index.sh](%%REPO_URL%%/bin/quick-readme2index.sh) tool would
only worry about those two files. This greatly speeds things along. only worry about those two files. This greatly speeds things along while testing.
Nevertheless, doing a final `make www` is still recommended best practice
Once that command finishes a proper `git status` and `git diff` shows that before you form your pull request.
everything is in order. In the end the safest way is to run `make www`, however.
Please see Please see
FAQ on "[fixing an entry](#fix_an_entry)". FAQ on "[fixing an entry](#fix_an_entry)".
@@ -3804,11 +3779,40 @@ See also the
FAQ on "[GitHub pull request](#pull_request)" FAQ on "[GitHub pull request](#pull_request)"
for more information about pull requests. for more information about pull requests.
#### PLEASE HELP us identify proper locations for IOCCC authors
If you know the location of an author listed under:
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;**[ZZ - Unknown location](location.html#ZZ)**
or if you find IOCCC author location that is incorrect,
then **please submit a pull request**,
or at least [inform the IOCCC judges](contact.html).
**FYI**: The [ZZ - Unknown location](location.html#ZZ) is used for **FYI**: The [ZZ - Unknown location](location.html#ZZ) is used for
historic winning authors whose location or country is not known, historic winning authors whose location or country is not known,
whereas the [XX - Anonymous location](location.html#XX) is used when the whereas the [XX - Anonymous location](location.html#XX) is used when the
winning author does **not wish to disclose their location**. winning author does **not wish to disclose their location**.
The contents of these JSON files contain the best known information
about authors of IOCCC entries. See
FAQ on "[author_handle.json](#author_json)"
for information about the contents of these JSON files and how they are used.
For example, if a given `author_handle.json` file contained:
``` <!---json-->
"location_code" : "ZZ",
```
and you knew that the author was located in [Australia](location.html#AU)
(location code **AU**), we encourage you to submit a **GitHub pull
request** to change that line to:
``` <!---json-->
"location_code" : "AU",
```
### Important note about **XX - Anonymous location**: ### Important note about **XX - Anonymous location**:
Unless you are the author who originally selected the **XX - Anonymous Unless you are the author who originally selected the **XX - Anonymous
@@ -4108,7 +4112,7 @@ and/or correct IOCCC author information.
See the See the
FAQ on "[.auth.json](#auth_json)" FAQ on "[.auth.json](#auth_json)"
for information about the contents of these JSON file and for information about the contents of these JSON files and
how they are used. how they are used.
See the See the
@@ -5346,8 +5350,7 @@ information in the [authors.html](authors.html) page.
There you will find various information including a link to their There you will find various information including a link to their
[authors.html](authors.html) information which includes various things like [authors.html](authors.html) information which includes various things like
their GitHub account (if known), a URL or alternate UL, mastodon handle, their GitHub account (if known), a URL or alternate UL, mastodon handle,
location (if known and not anonymous location) and a link to their JSON author location (if known and not anonymous location) and a link to their JSON author file.
file which has more information like email (if known).
**NOTE**: you might wish to search google (or some other search engine) by their **NOTE**: you might wish to search google (or some other search engine) by their
name as sometimes you can find out their GitHub account even if it's not in our name as sometimes you can find out their GitHub account even if it's not in our
@@ -5357,12 +5360,6 @@ Of course if you know the author's name you can go directly to
[authors.html](authors.html) and click on their surname's/last name's/second [authors.html](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. name's initial and then scroll down (if necessary) to the author in question.
**NOTE**: previously we included email in the [authors.html](authors.html) page
but we have decided against this. Nevertheless, the `author_handle` link under
the author links to a JSON file which has the email address if it is known,
which you might wish to consult. You might also wish to look at their URL or
alternate URL for more information.
<hr style="width:10%;text-align:left;margin-left:0"> <hr style="width:10%;text-align:left;margin-left:0">