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.
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.
Amongst the changes here is that we do not need to have the hex or html
code (numbers) for open and close parentheses (in links) as there are
names. '(' is & followed by lpar; and the ')' is the same but 'rpar;'
instead. This makes it easier to remember and type and it generates the
same html as well (they are all valid). Now the markdown files are
consistent in this (in some cases hex was used and in others the html
code).
Although many markdown files were updated no html files needed to be
updated as it generates the same html. Even so I ran the appropriate
rules to do so just to verify this.
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.
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.
Harmonized and improve the headers that are prepended
to the rules and guidelines given the IOCCC state.
Attempted to make the headers that are prepended
to the rules and guidelines more consistent.
Make reference to, where applicable, FAQs
about feedback and questions in those headers.
Perform `make www` to perform the above and test under macOS.
Fixed a number of typos, inconsistencies, and problems with the
rules and guidelines.
Improved how the closed version of the rules and guidelines declare
themselves at the top of the markdown and HTML file.
Changed `next/rules.md` VERSION from "2024-06-29-v28"
to "28.1 2024-06-29" in order to be more consistent
with IOCCC tool version format.
Changed `next/guidelines.md` VERSION from "2024-06-29-v28"
to "28.1 2024-06-29" in order to be more consistent
with IOCCC tool version format.
Make a minor format fix to `faq.md`.
Performed `make status` and `make www` to test the above umder macOS.
Added a `#weverything` div tag to the FAQ.
Expanded and improved(?) a number of rules and guidelines.
In particular, the consequences of the new mkiocccentry
repo have been put into the rules and guidelines.
This is a checkpoint from which we can review,
edit and improve.
The way that markdown quotes are currently formatted (with a gray
vertical line) looks too much like a change bar. The change bar
is an important tool to help notice new and changed rules and
guidelines. Unfortunately the current quotes style looks too much
like a change bar, so we use markdown quotes **ONLY** for literal
quotes (such as from Mark Twain) in the `guidelines.md` file.
Clarified and simplified the request to not use ASCII tabs within
markdown file content.
Added _guidelines_ to `next/guidelines.md` about not using ASCII
tab characters in markdown files while stating that is just fine
to use ASCII tabs in non-markdown files and C code.
The `make tab_check` rule now simply checks for ASCII tabs within
markdown files, except `markdown.md` where they are required to
serve as examples of what not to do.
Perform `make quick_www` to perform the above and test under macOS.
Perform `make www` to perform the above and test under macOS.
Cody Boone Ferguson