At least one link in the FAQ was fixed (not to a file but a named
reference). The FAQ has not been checked entirely for broken links
because the changes have got a bit out of hand and an entire make www
will have to be performed due to a problem I discovered doing the below.
Other improvements were made.
When going through the FAQ for broken links another problem was
discovered, one that broke the scripts that rely on jstrdecode(1). These
have been fixed but need further testing with make www. Some index.html files
were modified; for why this can be done without make quick_readme2index
see below on what changed and why it could be done this way.
When going through the FAQ for broken links I discovered some
issues with some entries' synopsis. This means that a number of
index.html and .entry.json files have been updated. The reason the
index.html files could be modified without running the scripts which
would were broken due to the jstrdecode(1) issue (a missing option in
the scripts) is because I used sgit(1). However, a single README.md file
was modified and the index.html file was not modified just yet. That
will happen with make www. The change is not significant, however, so
this should be okay this time. As the next step is a long process I
therefore decided to commit these things to get them out of the way to
try and prevent the commit from being even larger.
Minor fixes in next/try.sh and next/try.alt.sh were also discovered when
going through the FAQ.
Minor typos were made in the FAQ.
The .gitignore file was also updated: with the last change I
accidentally made it so vim swap files without a filename are not
ignored. That means there have to be two vim swap file globs.
Rather than have several globs for vim swap files it is now a single
glob (explanation below):
.s[a-zA-Z][a-zA-Z0-9]
I encountered another letter, 'v', after the '.s', and instead of having
several globs the glob just has [a-zA-Z] followed by [a-zA-Z0-9]. I
believe this new way should cover everything. I have not checked the vim
source code so I don't know if numbers are necessary and I don't know if
it ever (if there were an incredible amount of swap files which might
indicate rather a problem with the tree on the user's system) has more
than three characters but this should theoretically cover everything and
it is not a problem as no files in this glob should ever be in the
website and definitely not in an entry as txzchk(1) and chkentry(1)
verify.
A typo fix was made which until corrected did not make sense.
Some other minor changes were made, to account for some missing things.
I believe that unless something glaringly bad is noticed, this should be
the last update of this file, unless of course something new comes up,
but if that does I guess it'll be after the great fork merge and
IOCCC28.
New screenshots have been added with new explanations. A couple files
were either deleted or renamed.
There were some fixes as well.
I have looked at the result on the web server and it appears to look and
read well and hopefully this will suffice for this part of the how to
submit FAQ.
It might be worth pointing out that the screenshots might be better
done. For instance some of the longer lines are in some cut off. This
was to try and fit it in smaller screens but it might not be desirable.
Another issue is the scaling of one of the smaller images might make it
too small, at least for people like me who are practically blind.
The wording could definitely be improved as well but I wanted this
initial update in so it can be looked at better and any improvements
necessary can be discussed.
Remove the install rule as that's included in 1337.mk.
Remove the indent.c rule as that's included in 1337.mk.
Add to make clobber removal of *.dSYM.
Removed -g3 from OPT variable. This is more useful in macOS but with
optimised code debug symbols are not nearly as useful anyway.
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.
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 question of why did it jump from
28.1.3 2024-10-25
to
28.1.6 2024-12-05
can be explained as such. There were three edits since the last version
update so there should be three version updates. As for why 5 December
2024 when today is 6 December 2024: it's because the last update to the
contents was yesterday, 5 December 2024, although I believe there could
be some improvements (menu wise) for Makefile.example. This has to be
looked into and if it is done the version will be bumped again.
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.
In the thanks file the try.sh/try.alt.sh example files were linked to in
next/ but they're actually under template/entry, as discussed in the
previous commit.
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.
When jparse is not found it did not show how to install it, which is
needed for the script to function. It might be worth pointing out that
it does not use the jparse repo as that requires one to install the
libraries needed, whereas the mkiocccentry clone of the repo has the
libraries needed as part of its ecosystem.
This happened because when focusing on a bug for several days that had
to do with decoding code points (which so happens to be encoding but in
JSON it should be converted to unicode even when decoding) I lost sight
of the fact that jstrencode is meant to be **JSON** encoder. In the
process of this I have uncovered a number of other bugs but that's with
jstrencode and the website uses jstrdecode so this should not delay the
contest at all.
It now translates the characters '|' (pipe), '=' (equals) and '%'
(percent).
Checks were added in md2html.sh in the -s token=value so that token
cannot contain an = (equal), | (pipe) or a % (percent) and the value
cannot contain a | (pipe).
The reason that we cannot disallow a ';' or '&' is because the html
entities use those characters so if the sed script were to translate the
problematic characters it would cause a problem in the script.
Ran make www which updated 1988/robison/index.html and
1990/theorem/index.html.
1986/bright/README.md was fixed with the number of blank lines between
sections.
The file bin/html.sed has been fixed so that it works with
bin/md2html.sh (which has been modified and which is used via
bin/subst.entry-index.sh and output-index-inventory.sh). The script
output-index-inventory.sh was already updated to use html.sed so this
file has not been modified but the md2html.sh and subst.entry-index.sh
scripts have, along with bin/html.sed itself.
Tested make www which rebuilt several index.html files.
Updated bin/README.md as well as bin/index.html.
Testing that all the html files now are correct wrt Nu checker will have
to be done another time, however.
The script, for now, translates the following characters to their html
entity:
&, <, >
An important note that is in a comment is that the & MUST come first as
otherwise the & in the others will be corrupted.
One script uses this but in order to make sure it is okay make www will
have to be run first. Another script, the one that needs it even more,
has a problem that has to be discussed, before it can be used.
Nonetheless the html.sed file is at least added for the scripts once
things are tested okay.
The way the abstract is used for the index.html files does not allow for
parsing by pandoc so it did not work as expected (I did not verify the
two entries this is a problem).
The index.html files of these two entries have been modified. Unless the
script is updated the only other way is to update the abstract to use
< but this can be discussed.
In the case of two which had an abstract (.entry.json file) that
includes one (in one case) '<' or two (in another case) '<'s a markdown
code block had to be used as otherwise the abstract would have to have a
< which looks even worse. This is not ideal but if we want it to pass
lint this is what has to be done. Use of json \uxxxx won't work as that
encodes it to < literally.
In the case of 2018/burton[12] the author had a section called Coda.
This conflicted with the problem that all generated html files have such
a section. To fix this problem I renamed it 'Final remarks'. Not ideal
but at least it now passes as valid.
There were a number of different kinds of problems and in one case the
symbols < and > could be fixed by changing it to a code block (which it
should have been anyway) - that was 2020/ferguson1 I think.
A typo in markdown meant that a link was not formed.
Renamed enigma.html to enigma.txt. Although it was to be set to viewed
as text the problem is that as a html file running a linter on it will
cause errors (obviously).
The .entry.json and all files that referred to the file enigma.html (not
in remote web servers, obviously, but just this website) now refer to
enigma.txt, except that enigma.html was now added to .gitignore and the
recode.md (in the example command) redirects to enigma.html as that
should be a html file, assuming they have the right key (of the
selection I gave).
These problems were not discovered due to trying to get the html files
in a good state (ironically) and knowing that I had written a lot.
I believe now that the files should be okay.
Although I did use sgit I did it carefully and I still ran make
quick-readme2index and make gen_other_html.
In the previous commit when the missing files status was removed I
forgot to change that there is also a bug in part and in particular the
word 'also'.
With thanks to Leo, the filenames have been corrected in the
README.md/index.html file. As the manifest already has them (they were
under different names) the .entry.json file did not have to be updated.
The new file, greasymouse.man, IS the cat man page noted by the author
in their remarks. This file was provided by Leo as remark.txt but to
make it render better I have made it a .man file and, for syntax
highlighting, I moved the section titles to the first column of the
file.
I thought of making it a true man page but as the author suggested that
it is a cat man page I decided against this.
After the swap in the jparse repo of jstrencode and jstrdecode, due to
mix-up in terminology, originally in the mkiocccentry repo, the website
tools that used jstrdecode now have to use jstrencode, with a minimum
version of 2.0.0.
The scripts have been updated to do this. After doing a make install
from the jparse repo I did a make www with no html files changed. Then
doing the same thing after make install from the mkiocccentry/jparse
directory, no changes were made either, indicating that all should be
okay.
The bin/index.html was however modified to refer to jstrencode, not
jstrdecode.
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.
Typos were fixed in bin/md2html.cfg, bin/subst.default.sh,
nojs-menu.html and nojs-menu.md.
The nojs-menu.html now links to bin/index.html and inc/index.html but
the rest of the html files for now do not. It seems like it might be
good if they do, at least bin/index.html, but if that is decided against
this can be rolled back instead.
The first one is now simpler and simply says some of the things that
might have changed. The other one, a sub-question, discusses the
Makefile rules and such.
In the case of JSON code blocks many had lines that ended in ',' which
would, when syntax highlighting works, be flagged as a syntax error.
A typo was fixed in a JSON code block (for the IOCCC affiliation).
In entry_set JSON description the formatting was wrong and it also had a
syntax error. Instead it now has the full set of the author in question
(Yusuke Endoh) as of this time.
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.
It incorrectly calculated the number of invalid JSON files.
Redirect jparse stderr to /dev/null as the script will be able to tell
without the extra clutter.
That is I did:
sgit -e '/^<\/li>$/d' -e '/^<li>$/d' \
-e '/^<ol>$/d' -e -e 's/^<\/ol>$/g' faq.md
The next steps are to move the question/answers to the appropriate
sections and to try and shorten as many answers as possible, possibly
merging some or even getting rid of some.
This does not mean that there aren't other question/answers under this
section just yet but the first questions are those that are in the table
of contents and in the correct order.
More work must be done but to make sure that things are safe I am
committing what has been done so far as this is very error prone and
right now it seems okay.
New sections were added. Not all anchors work yet. The questions/answers
are not yet in the right order. That is the next step.
Instead of relying on having to manually add numbers use ordered lists.
The sections are in unordered lists so we have control over the number.
The downside with this is with the long file it is harder to find the
section one is in but as each question/answer has a jump to the top that
should be worth the gain of not having to manually edit every question
(in the table of contents as well as the question/answers) every time a
question is moved to another place (or a new one is added) above others.
Another downside is minor: it does not allow for 0 as html lists do not
start with 0 but 1.
Another thing that has to be done is to make sure that the html lint is
correct. That can be done once this is merged. Any thing that needs to
be fixed can then be fixed.
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.
This commit is the first step in reordering/restructuring the FAQ.
Something important to notice is that except for the FAQ sections, the
anchor names starting with the regexp '^faq[0-9]' have been removed. The
numbers have not been removed otherwise, however, and as one FAQ was a
duplicate there might be a labelling problem too.
As the FAQ links do not refer to the number but rather what they are
about, and since the FAQ is being heavily restructured, the numbers are
a burden. Even after everything is reordered it could be a potential
problem when adding a new FAQ (though that should hopefully be pretty
rare). Perhaps a list that's not numbered (unordered instead of ordered
in html terms) is what is needed but this can be decided later.
This is a work in progress but since a lot was done I wanted this in.
The next step will be to move things about and perhaps remove the
numbers, whether temporary or not.
This commit also adds the faq.html and bugs.html file that should have
been committed with 2013. The reason the faq.md is updated with only the
version update (backdated to yesterday) is because the version was not
updated with the previous update.
Cody Boone Ferguson