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.
This code is based on a 'fix' that causes another issue, and could
potentially be 'wrong' to have. It is better, I think, to pose the
challenge to the viewer to see if they can solve the problem themselves,
and if so if there are any issues with such a fix.
It seems that the problem was (or perhaps not .. we'll see :-) ) is that
the 'run:' part of each task in the workflow file should not have a '-'.
If this is the case then this should solve the problem and if so the
problem was that some had it and others had it and in a rush I thought,
forgetting the syntax, that the problem was the missing ones were
incorrect.
Q: What do you call the time when a person tries to fix something when
they only have a minute?
A: Rush minute!
Anyway hopefully this is the final typo fixed needed. If not I have more
time now, however, so the problem can be remedied.
This is because the mkiocccentry repo has offending markdown files.
Hopefully this resolves the workflow problem with find-invalid-json.sh
script and rule added to make test.
This script is run from 'make test' too so that if someone changes a
JSON file and it is invalid the GitHub workflow will report an error.
This script is based on bin/find-missing-links.sh. It can be cleaned up
with exit codes (and consistency checks need to be made) but other
issues have higher priorities so I will leave this the way it is for
now.
Requires verge to be installed and the jparse version to be 1.2.0 or
greater.
This video unfortunately comes from YouTube and so even if the link
eventually dies we should not have it here. A link was provided.
Updated the .entry.json and manifest in the index.html plus checked
other formatting issues.
It had:
#build authors.html if out of date with author JSON files'!/usr/bin/env make
so it was changed to:
!/usr/bin/env make
It seems like this was somehow yanked pasted from make help.
The FAQ now notes that there can be times where the jparse repo
(https://github.com/xexyl/jparse/) is different from the mkiocccentry
repo's subdirectory jparse. This is one of the reasons the tools in the
mkiocccentry and the jparse repo show the jparse API with the -V
(version) option.
I believe that this is all that's needed for the jparse repo in the FAQ
but time will tell on that.
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.
A problem existed where in a superscript if there is a line immediately
above it the superscript text would cover part of the line and in
subscript the same problem occurred with the line below it.
This change can possibly be improved but it now does not cover text
(though admittedly I did not test the subscript before the change, only
after, but it seems highly unlikely it was not a problem).
Something that has bothered me VERY MUCH for A VERY LONG TIME is that
the honour roll (under my name) was not very humble and in some respects
rather redundant. I have fixed this a great deal and improved the
readability of it too (grammar and so on).
I also added a point about fixing many entries that no longer worked and
I also did this for Yusuke Endoh too as he was responsible for fixing
numerous (at the least) entries that no longer worked (and it should be
acknowledged and honoured just as much as what I did).
The FAQ I improved is related to one of the things that is in the above,
to do with alternate code. It now explains some of the purposes of
alternate code and why (in some cases) alt code was added when it might
or might not be useful (a judgement call that invariably is not always
perfect). It notes that in many cases the alternate code comes from the
author directly.
With these changes a problem that I felt was a VERY BIG problem should
be resolved now.
Cody Boone Ferguson