The menu in all html pages for the FAQ was fixed to link to the step 0
(of how to enter the contest) and also it was renamed ('Enter the
IOCCC').
I also went through the most important sections of the FAQ (how to
enter and the mkiocccentry related questions) and checked the
register.html, pw-change.html and submit.html pages. It is possible I
have missed something but I think it's in pretty good shape nonetheless.
Make lines beginning (in markdown files) 'BTW' bold. Rebuilt the
respective html pages.
Slight update to abstract in two entries (1985/shapiro and
1994/shapiro). One is changing 'defines' to '#defines' and the other was
a typo fix.
Fixed make gen_next: added missing new files.
Various fixes in next/register.html (typos and other things).
We added lettered steps to `next/register.md` as part of our
configuring the mailing list for IOCCC28.
Change "IOCCC Judges" to the more commonly used "IOCCC judges"
and made it a HTML link in `2014/README.md`, `2015/README.md`,
and `faq.md`.
Added a reference to "first time login" in `next/submit.md`.
Improved some text in Step 3 of FAQ 0.0 of `faq.md`.
Performed `make quick_www` to update the HTML pages.
TODO: Need to add images to the lettered steps in `next/register.md.
Added a new `next/submit.html` to move the "how to submit" form "in-line"
of the top FAQ entry into a new page managed by `next/submit.md`.
Thus, `next/submit.html` is a parallel to `next/register.html`
and `next/submit.md` is a parallel to `next/register.md`.
Changed the FAQ "faq.html#submit" and into "faq.html#enter".
Added individual tags for the steps in FAQ0.0.
Moved "faq.html#register" down to FAQ 0.0 step 2.
Added "faq.html#submit" for FAQ 0.0 step 5,
however elsewhere often "next/submit.html" is used.
Changed references for "faq.html#upload" to "next/submit.html".
We made a number of changes to the following markdown files to reflect the above:
- `about.md`
- `faq.md`
- `index.md`
- `markdown.md`
- `next/README.md`
- `next/README.md`
- `next/guidelines.md`
- `next/register.md`
- `next/rules.md`
- `nojs-menu.md`
- `status.md`
as well as these files:
- `bin/gen-top-html.sh`
- `bin/md2html.cfg`
and added:
- `next/submit.html`
- `next/submit.md`
Perform `make www` and `make gen_status` to perform the above and test under macOS.
TODO: Add images about the mailing list to `next/register.md`. See the line:
```
XXX - **put images and other details about joining the mailing list here** - XXX
```
There were numerous fixes and clarifications. One important fix was a
typo for jparse(3), being instead jparse(8) which is obviously very
wrong.
Other things were improved upon. The FAQ simply stresses something a bit
better as the guidelines (or maybe it was the rules) links to that FAQ.
We improved the rules language around `make clobber` to not insist,
but instead request actions to restore the state of the submission.
Updated `inc/rules.closed.hdr` and `inc/guidelines.closed.hdr` to clarify
the tentative nature of the rules and guidelines without implying
that they might be massively changed before the IOCCC re-opened.
The `next/rules.md` and `next/guidelines.md` have been updated to
include the `inc/rules.closed.hdr` and `inc/guidelines.closed.hdr`
content respectively.
The top level warning that the rules and guidelines are out of date
have been removed.
Performed `make rules guidelines` to update the HTML pages.
The FAQ now has a list to view or download the example Makefile.
The guidelines had some reordering of things and some additional
information was also added, like noting better how one does not need to
install jparse, dbg or dyn_array to use mkiocccentry, and how even if
they do, mkiocccentry will use its own clone.
The guidelines now link to both GitHub (viewing option) and directly to
the files Makefile.example, try.sh and try.alt.sh, as does the FAQ.
I made sure to keep the version of the guidelines and rules the same (as
in major.minor) but updated the date, as these changes are part of the
previous commit.
The Makefile.example file now has the ALT_OBJ and ALT_TARGET (with a
comment explaining how to use it) and the alt rule (which if the
variables are left empty it will do nothing with 'make alt' or 'make
everything').
The example Makefile now has the everything rule as well, for those who
have an alt target.
Fix links to next/try.sh, next/try.alt.sh and next/Makefile.example in
html files (guidelines/rules/FAQ) to not link to GitHub as they're
supposed to be downloaded.
The file template/entry/Makefile.entry was moved to
next/Makefile.example. This matches the mkiocccentry repo in filename
and where it was before (template/entry) is not the right place as that
is for the template of making submissions into a winning entry whereas
next/ is for the next contest. The next/ seems like the most logical
place because the example file could be updated per contest for whatever
reason, perhaps by adding the year in it (or not). On the other hand,
the try.sh in template/entry is for submitters too but since the
bin/cvt-submission.sh script will copy the template files to a winning
entry if it does not exist it is left in template/entry, even if this
might not be ideal.
The references to the old Makefile.entry have been updated to
Makefile.example in the new path/filename.
Other changes had to be made too including updates to
bin/cvt-submission.sh. That script should be checked to make sure
everything is okay but as I have no way to test it that might have to be
done by the judges though I think it is okay.
Html files that have been changed that might need to be checked are:
0. faq.html (this one especially should be checked)
1. next/guidelines.html (though the judges will be checking this more)
2. next/rules.html (though the judges will be checking this more)
For the faq.html file, the Makefile.example and try.sh/try.alt.sh
scripts should be downloaded, not linked to on GitHub and it needs to be
clear that one should use the Makefile.example from the website (this
repo) rather than the out of date mkiocccentry repo.
For the guidelines and rules, and especially the guidelines, any files
linked should also be downloaded and not linked to GitHub. The text
should be clear already but it might be good to have a quick pass. The
judges will be going over these files before the next contest too. The
files should be downloaded here too, not linked to GitHub as submitters
need to download the files to make use of.
The thanks-for-help.html file was slightly modified but should be fine
too. In this case the GitHub file should be linked to.
The version of the rules and guidelines are from an earlier date of when
they were last modified for the above changes (as this was worked on
over a number of days).
The scripts can be found under template/entry. A new FAQ entry has been
added and the guidelines have been updated.
The rules have a new div id ("version") to match what was added to
guidelines yesterday (since it's obvious what kind of version it is.
Once this has been merged html files need to be checked to make sure
everything is okay.
We move the "_Thanks for the help_" out from under the "Entries"
menu and under the "About" menu to better balance the menus.
Besides, "_Thanks for the help_" is more **about** the IOCCC itself.
The sections have been modified a fair amount. The Entries menu has been
extended to have: Fixing entries, Updating author info, Thanks for the
help. The first two were moved from FAQ and the last one from About.
The rationale for these, in order: entries and authors have to do with
entries and most of the help involves entries. It also has to do with
website but in 'about' it does not seem the right place, unless maybe it
is renamed to 'Credits' or something (I am not suggesting this one way
or the other). This one is debatable but that was the rationale.
The Status menu has been extended to have: Markdown guidelines and
Security policy. The rationale is that the markdown guidelines are part
of contest guidelines and the security policy is about the status of the
entries and how if there are any security problems they will not be
addressed (instead of about the IOCCC).
The FAQ was extended to have: Compiling entries, Running entries, How to
help. The reason to not have compiling and running entries under Entries
is because this is 'how to' and also the menu was too long. How to help
seems like a good idea under FAQ too (was in About).
About was extended to have the new 'about.html' page (from about.md).
This is a rare case where a new file is useful as it fits under 'About'.
The menu now is: Home page, About the IOCCC, The Judges, Contact us. I
was pondering the 'About [the IOCCC]' at the top and also naming it
'About us' but it seemed like a link to index.html was necessary and as
for 'about us' it seemed less clear as to whether it was about the
judges or the contest itself. The FAQ has been updated slightly for
this.
After further inspection the bin/index.html and the inc/index.html links
were removed from the about section.
With these changes, renaming an item or slight reordering
notwithstanding, I believe that #2006 is probably in good shape.
The mobile About menu was missing the IOCCC markdown guidelines. This
has been added to the mobile menu but moved to 'Status' which is where
guidelines are (it has been renamed to be 'IOCCC Markdown Guidelines' to
match the style of the other items in that menu).
The About menu now has two more links, one for the website tools and the
other for the include files of the tools. It might be, looking at the
generated html files, better to have another menu instead, but what that
should be is unclear. The reason it might be better is because the
'About' menu is rather long. In retrospect it might be better to not
have the script include files in the html files but this can be decided
and dealt with later.
The script bin/find-missing-links.sh now ignores the directory NOTES/. A
better approach might be using git ls-files --exclude but a quick test
did not work right. Another option, at least for NOTES/, might be to use
'git ls-files --exclude-standard'.
The bin/index.html file has been updated.
Run make www to rebuild all html files.
More work might need to be done in this section and other sections might
need checking too but I believe this section is more helpful. An attempt
was made to shorten some of it without compromising the usefulness but
more will have to be done to make sure this is the case.
A number of question answers have been merged and shortened somewhat.
Fix link in the menu of all html pages and the inc/ files that was
broken due to renaming an anchor.
The guidelines and rules have had a link fix (to the FAQ) as well as
some additional points added about the mkiocccentry toolkit.
More work in the FAQ needs to be done, including with the how to enter
the IOCCC, but as so much work has been done already I have decided to
make the commit to get these many important changes out of the way.
Numerous sections have had questions moved to another section including
the new sections 'The mkiocccentry toolkit: finer details' and 'History
of the IOCCC'.
The first section was renamed (pending any better name as it might not
be quite right) 'Entering the IOCCC: the bare minimum you need to know'.
Renamed some questions to better (hopefully) account for what they are
about.
The purpose of not making the actual content match this reordering is so
that if any changes need to be made they do not have to be done again
(though a few were moved). Thus before more work can be done some
discussion is needed.
The guidelines and rules now refer at the top to the general FAQ
especially about the bare minimum one needs to know.
The jparse/ subdirectory in the mkiocccentry repo is self-contained but
it was suggested to put in parentheses the original source and this has
been done now.
Several new FAQ entries have been added to discuss some of the details
of chkentry, txzchk, fnamchk, jparse and maybe others that are related
to the rules and guidelines (and in particular rule 17 and how to
package submission tarballs). As there are new FAQ entries on these
(which is much of what was in the guidelines) the guidelines have been
shortened for these additions.
Looking over the rendered html files it seems okay but I believe that
these entries are works in progress and not complete.
For reference the new FAQ version is 28.0.3 2024-07-27 and the new
guidelines version is 28.11 2024-07-27.
We quasi-canonicalized markdown links to FAQ entries.
**IMPORTANT NOTE**: This is a useful step in completing issue #2417. This commit is consistent with the top level TODO comment requirements. Nevertheless, this changes made by this commit needs to be examined and in some cases improved.
A link to an FAQ entry is of the form:
```
FAQ on "[the link text](....faq.html#string)"
FAQ on "[the link text](....faq.html#string)"
```
The "FAQ" is at the start of the line, or in rare cases is preceded only by whitespace.
The reference to the FAQ starts outside of the markdown link with the string **FAQ ON "**.
After the markdown link is a **"** followed by either the end of line or a single punctuation character such as a period or comma.
We reduced the size of "the link text" that refer to an FAQ to at most 3 words. In some cases the sentence and/or text surrounding the markdown link to a FAQ may need to be further adjusted to better accommodate this new style.
**IMPORTANT NOTE**: References to a FAQ entry are on a separate line.
p.s. When linking to the `faq.html` file itself, we use markdown of the form "`the [IOCCC FAQ](..../faq.html)`" and place the word "the" outside of the "IOCCC FAQ" link text.
Given the above system (and because references to an FAQ entry is on a separate line), the following command shows links to FAQ entries, sorted by FAQ entry "link #name" so that one may evaluate the way a given FAQ entry is referenced:
```sh
find * -name '*.md' -print0 | xargs0 grep -E '^[[:space:]]*FAQ on "' | sed -e 's/^\([^:]*\):\( *FAQ on "[^#]*\)#\([^)]*\)\()".*\)$/#\3\t\1\t\2#\3\4/' | sort
```
The above command shows the value of consistency when it comes to FAQ references.
**NOTE**: There are a few differences on how a given FAQ is references. That is probably OK as there is NOT an "total mandate" that all references to a given FAQ must have the same "link text" for example. On the other hand if references to a given FAQ can be identical, that might be helpful. We are certain that in some contexts the "link text" might need to change.
Should we decide to change the way FAQ are referenced, we will be able to modify identify and modify them with greater ease.'
Examine the changes made by this commit and adjust and/or improve as needed.
Performed `make www` to accomplish the above and to test under macOS.
The location of the link is in the About menu under the 'Contacting the
IOCCC' and above 'Thanks for the help'. At first I had it at the very
bottom, under 'IOCCC markdown guidelines', but it seemed better to have
it closer to contacting the IOCCC. This is the same location in the no
JavaScript menu (which, for those who do not know or forget, is not a
requirement except for some screen sizes).
The top level Makefile has a new 'security' rule. Updated make help.
Typo fixes in make help.
SECURITY.html has had a few updates as well: change the wording of entry
code is unsupported (it now says 'ALL CODE IN ALL IOCCC ENTRIES IS
UNSUPPORTED!!') and it now links to the mkiocccentry repo and how to
report a possible security vulnerability in that repo; as that IS
supported - and since there was reference to discussing security
concerns is in SECURITY.html - even though the entries will not receive
security updates - it seemed a good idea to have a link to report such
security issues in the mkiocccentry repo. Perhaps the FAQ needs to be
updated for this too.
This includes updates from a recent change in txzchk and more details
about the tools and what they check (warnings and errors) and how to use
them individually.
This does need to be reviewed further, possibly being shorted or
referring to an FAQ, but it's a good start.
The rules had a typo fix as well.
Some of these are very important technical fixes as they stated things
that were not accurate. Other things were (hopefully) clarified. Another
check will have to be done sometime soon.
Rather than have a literal vertical bar (|) for lines that indicate a
change from the last contest, it is now a CSS class which has a solid
black left border of 4 pixels. This not only makes it easier to see but
it fixes some formatting issues too (see below for tests).
This means that if a change mark is needed one can do:
<p class="leftbar">
...
</p>
A tip for vim users: in the .vimrc file add the following line
(temporarily or otherwise):
abbr leftbar <p class="leftbar">
Then you only need to type:
leftbar
and it will automatically add the proper block.
As for testing how this looks I have checked it with Safari with:
- an iPhone 14 Pro Max
- an iPhone 8 Plus
- a MacBook Pro 16 inch (both at full width and smallest width)
- an iPad Pro 11 inch 4th generation in both portrait and landscape
orientations
An important point that one needs to remember when using this CSS class
in lists is that one cannot do:
<p class="leftbar">
* foo
</p>
<p class="leftbar">
* bar
</p>
but rather do:
* <p class="leftbar">foo</p>
* <p class="leftbar">bar</p>
A problem was discovered in blockquotes for really long text, in
particular in the guidelines: 2305567963945518424753102147331756070. The
problem was that the number flowed outside the border. That should no
longer happen. Below is what should happen instead, though it's hard to
be sure how it will look in every case.
In Safari on a 16" MacBook Pro with Safari all across the screen it is
not a problem but shorter text will be in a smaller box (this means
the green box will vary in size depending on what is in it but this does
not seem to be a big problem).
With Safari in an old iPhone 8 Plus the box can go a bit further beyond
the screen width but text does not go beyond the boundary and one can
scroll left/right at need.
With Safari in an iPhone 14 Pro Max there is currently a cache issue but
earlier (when playing with different options) it seemed to fit and in
Simulator (in macOS) it looks good. However in Simulator earlier it was
fine even when the iPhone 14 Pro Max was not.
In responsive mode in Safari with a small width (400px) it is the same
result as the iPhone 8 Plus.
Finally with Safari in macOS with the window decreased in width it is
fine but it already was fine because it doesn't go to the size of a
phone (though it has helped fix problems with phones).
I have changed the font-style to normal (was italic) in blockquotes also
as this way italics can show up specially if requested.
The guidelines had some line breaks in the blockquotes that were
problematic; these have been removed as they are not necessary and it
did not look good either with smaller width screens.
More testing will likely be useful but it should be a lot better now.
The new FAQ is about how to report bugs in mkiocccentry tools. The rules
and guidelines link to this FAQ.
The rules and guidelines have been corrected and clarified in a number
of ways.
This is more for those who are interested in how they can run each step
of the mkiocccentry tool as well as how to make it easier to edit a
submission tarball.
Although it looks okay (the rendered html) a more thorough review will
have to be done, tomorrow if possible.
A typo that was missed because I did not look at that part of the file
was 'quidelines' instead of 'guidelines'. This has been fixed in inc/
and next/.
The guidelines had many fixes and where necessary updates (about new
tools for instance) plus some fun for people to discover.
The FAQ was slightly updated as well for the guidelines.
Cody Boone Ferguson