Enhancement: improve the look and feel of the constructed HTML files

[lcn2]

All generated HTML web pages are covered by this issue.

This issue covered all generated HTML files, including generated entry index.html files, top level web pages (both constructed form data such as authors.html and years.html as well as top level HTML files generated from markdown such as judges.html and news.html) and year level 'index.htmlweb pages,bin/index.htmlandarchive/historic/index.html`, etc. If the web page is generated or updated by a bin tool, then that page a candidate for this include the "look and feel" issue.

This issue focuses on these web pages "look and feel".

This is NOT about fixing content errors. (Well if you see something glaring, go ahead and fix it). This is about how the generated HTML pages look in a web browser.

Here are the types of questions ask about a generated HTML web page as viewed in a browser:

• Some formatting that looks obnoxious?
• Information displayed in way that is difficult to read?
• Have too much to too little whitespace that makes the web page awkward to read?
• Do links to viewable content fail by forcing you to download it?
• Do links fail because the link is broken?

We are NOT focusing on the accuracy of the generated web page per se (although if you see something glaring, feel free to fix it under the guide of something that slipped passed the issue #3 effort). We are focusing on HOW it LOOKS with an emphasis on correcting dysfunctional presentations.

In many cases, corrections can be addressed by editing some markdown file such as the entry's README.md file. Please modify the entry's README.md file and re-build the entry's index.html in a pull request.

If, however, you see an issue that may be more a matter of changing ioccc.css or the related bin tool, please raise the matter as a comment in this issue #2239 so we can discuss the matter before editing the CSS and/or bin tool. Again, this is less likely to happen, but if it does, we recommend a comment related discussion first. Modification to the entry's README.md file can be done directly via pull requests.

We also want to address any fix all REASONABLE "validation errors and warnings" as reported by the "Nu HTML check this web page". We emphasize REASONABLE because in the past, we have found some of those "validation errors and warnings" to be on the pedantic side of things. Moreover, when it comes to the HTML generated by pandoc(1) we may not have much room to fix things.

See also comment-2101733908 regarding links to markdown files, links to GitHub, relative links, and links with %%TOKEN%% symbols.

Please note that the top index page of this repo, as rendered by GitHub, is https://ioccc-src.github.io/temp-test-ioccc/index.html.

A review of commit 4d6009b, and commit 3aec80f, and commit 85c9916, and commit 5dd3311 should be done to consider changes impacted by the move away from "spoiler" language and towards language such as "deobfuscation".

[xexyl]

The generated winner index.html files need to have their "look and feel" improved.

NOTE: As of the time this issue was created, the procedure to generate HTML files other than winner index.html files has not been completed, this issue restricts itself to just the "look and fee" of the winner index.html files.

Using the method outlined in issue #1933, the winner index.html files may still be improved.

HINT: One may generate a single winner index.html file by using the bin/readme2index.sh tool on a single winner. For example, to regenerate 2020/ferguson1/index.html:

bin/readme2index.sh -v 3 2020/ferguson1

:-)

About that entry .. didn't you say I needed to fix something there in the README.md and maybe other markdown files? What did you have in mind (well besides the markdown file references on GitHub should be removed which I'll get to)?

Thanks.

HINT: We recommend using the method outlined in comment 1893176110 on a macOS machine to examine HTML files before pushing changes to the repo.

Good call on linking there.

Probably the most obvious way is to improve the winner README.md file itself. A number of "undesirable" nits and formatting issues may be addressed by changing the markdown content.

As above. Of course I think I've done much of this work but it'll be helpful to see how the index.html files come out to know what has to change further.

A somewhat less disable way to address a "Look and Feel" issue for a partical IOCCC winner would be to add a special line to the inc/md2html.cfg file that controls the way the bin/ tools and inc/ files form the winner index.html file. One would need to be sure the configuration line that matches the particular winner markdown line appears BEFORE more general configuration line. For example:

I can see how that would be less desirable yes.

# Fake example:We must disable pandoc warnings for 1984/anonymou because those warnings
# are not valid and we need a fake example.

1984/anonymous/README.md         -o bin/subst.default.sh -o bin/subst.winner-index.sh -b bin/gen-author.sh -a bin/gen-inventory.sh -P '-f markdown -t html --quiet`

# Unless matched above, default process all winner README.md files

[12][0-9][0-9][0-9]/*/README.md         -o bin/subst.default.sh -o bin/subst.winner-index.sh -b bin/gen-author.sh -a bin/gen-inventory.sh
mock/*/README.md                        -o bin/subst.default.sh -o bin/subst.winner-index.sh -b bin/gen-author.sh -a bin/gen-inventory.sh

This is an example of disabling warnings i.e. the less desirable way, right?

Or next might be to use a slightly modified inc/begin-rightcolumn.default.html file (lets pretend this file is called inc/begin-rightcolumn.1984_anonymous.html), by adding a special line to the inc/md2html.cfg file before BEFORE more general configuration line. For example:

# Fake example: We must disable pandoc warnings for 1984/anonymous because those warnings
# are not valid and we need a fake example.

1984/anonymous/README.md         -o bin/subst.default.sh -o bin/subst.winner-index.sh -b bin/gen-author.sh -a bin/gen-inventory.sh -P '-f markdown -t html --quiet` -H begin-rightcolumn=1984_anonymous

# Unless matched above, default process all winner README.md files

[12][0-9][0-9][0-9]/*/README.md         -o bin/subst.default.sh -o bin/subst.winner-index.sh -b bin/gen-author.sh -a bin/gen-inventory.sh
mock/*/README.md                        -o bin/subst.default.sh -o bin/subst.winner-index.sh -b bin/gen-author.sh -a bin/gen-inventory.sh

See the inc/md2html.cfg file comments for more information.

Again, we suggest you try and fix it by changing the README.md file first, before you try and setup a special case inc/md2html.cfg line.

Perhaps it'll be helpful to have all the html files generated so we can see what they look like here so I can know what to fix? And do feel free to assign this to me!

Another somewhat complex way to address a "Look and Feel" problem is to modify the default inc/_something_.default.html file. As an example, if the problem being address in the inc/begin-rightcolumn.default.html file is wide spread, instead adding a bunch of special case lines to the inc/md2html.cfg file using a bunch of special case inc/begin-rightcolumn.XYZZY.html files, one might be better off modifying the inc/begin-rightcolumn.default.html file.

I guess in general complex ways should be weighed against the easier ways and what is gained/lost. Of course in some cases more complex is the right way to go but not always. I can see how a widespread problem would be better fixed at the source of course.

This approach would require one to regenerate ALL HTML files that use inc/begin-rightcolumn.default.html, which because it is a default file for the "begin-rightcolumn" phase, is nearly all (if not all) HTML files. One cannot use the bin/quick-readme2index.sh either one can to force the rebuild of ALL HTML files and then test ALL HTML files to verify that the fix did not create a bunch of new problems.

Speaking of such. What will the other html files (from other markdown files I mean) be using?

Another more complex way to address a "Look and Feel" problem is to modify the ioccc.css file. By "more complex" and "less desirable" we mean that changing the ioccc.css file may impact ALL HTML files on the web site, forcing one to check the impact on ALL HTML files from the point of view of several common browses, and with various window sizes AND with printing files. This can be done (and there could be cases where it must be done), but hopefully this method can be avoided.

Agreed it would be good if this can be avoided!

Probably the most complex way to address a Look and Feel" problem to change the way scripts in bin/ work. This will impact ALL HTML files on the web site, forcing one to check the impact on ALL HTML files in addition to having to modify the bin/ code.

True. That seems even worse than modifying the CSS file. I guess you agree there. Anyway feel free to assign this (and every other one .. I'll mention that in 5) to me. I'll be asking for a priority list too.

[lcn2]

This is an example of disabling warnings i.e. the less desirable way, right?

Probably it is: that is untested and likely not needed. It was just a fake example.

[xexyl]

This is an example of disabling warnings i.e. the less desirable way, right?

Probably it is: that is untested and likely not needed. It was just a fake example.

Just making sure. Thanks for assigning it to me. I presume you'll get back to me on the other things later on.

[lcn2]

The generated winner index.html files need to have their "look and feel" improved.
NOTE: As of the time this issue was created, the procedure to generate HTML files other than winner index.html files has not been completed, this issue restricts itself to just the "look and fee" of the winner index.html files.
Using the method outlined in issue #1933, the winner index.html files may still be improved.
HINT: One may generate a single winner index.html file by using the bin/readme2index.sh tool on a single winner. For example, to regenerate 2020/ferguson1/index.html:

bin/readme2index.sh -v 3 2020/ferguson1

:-)

About that entry .. didn't you say I needed to fix something there in the README.md and maybe other markdown files? What did you have in mind (well besides the markdown file references on GitHub should be removed which I'll get to)?

We just needed a fake example to use.

[lcn2]

Or next might be to use a slightly modified inc/begin-rightcolumn.default.html file (lets pretend this file is called inc/begin-rightcolumn.1984_anonymous.html), by adding a special line to the inc/md2html.cfg file before BEFORE more general configuration line. For example:

# Fake example: We must disable pandoc warnings for 1984/anonymous because those warnings
# are not valid and we need a fake example.

1984/anonymous/README.md         -o bin/subst.default.sh -o bin/subst.winner-index.sh -b bin/gen-author.sh -a bin/gen-inventory.sh -P '-f markdown -t html --quiet` -H begin-rightcolumn=1984_anonymous

# Unless matched above, default process all winner README.md files

[12][0-9][0-9][0-9]/*/README.md         -o bin/subst.default.sh -o bin/subst.winner-index.sh -b bin/gen-author.sh -a bin/gen-inventory.sh
mock/*/README.md                        -o bin/subst.default.sh -o bin/subst.winner-index.sh -b bin/gen-author.sh -a bin/gen-inventory.sh

See the inc/md2html.cfg file comments for more information.
Again, we suggest you try and fix it by changing the README.md file first, before you try and setup a special case inc/md2html.cfg line.

Perhaps it'll be helpful to have all the html files generated so we can see what they look like here so I can know what to fix?

They ARE generated ‼️ Well OK, only all of the winner index.html files are generated. 😉 Maybe we did not announce that fact with enough fanfare? 😀

OK, as mentioned the higher level HTML files and the winner HTML files that are not index.html still need to be generated. 😉

It was a milestone that we had been working on for months. It was why we asked to hold off on edits being made to the manifest numbers spreadsheet until now. It was the reason for the creation of all those new issues, etc.

start side note

We are actively working on generating the rest of the HTML files (see the TODO list of issue #4): racing to try and finish issue #4 before the other ((top primary)) issues are completed. For a number of people, work on issue #2 and issue #3 might seem nice, but as they might not take the time to try all of the IOCCC winners of the past, they might not understand the full benefit .. that it until they are looking at past winners for ideas and discover that they actually have a reasonable change to download the core, compile it and run it today. Sadly it will be the look and feel that will catch the attention of most people.

The winner index.html files are ready for review and improvement on their look at feel. Again this isn't to say that the tremendous work on issue #2 and issue #3 are not important: they are very important and your efforts on behalf of the IOCCC website are very much appreciated.

If we were make a new accouchement now about the work done so far, and people see a bunch of broken links, missing HTML files, etc. it will be hard for some people to perceive the tremendous progress that was made by issue #2 and issue #3. Thus we have be working very hard to race to try and get the look and feel ready so that your important efforts may present themselves in a good light for others to see.

end side note

And as the top comment suggests, much of the work will likely involve editing the README.md file, running bin/readme2index.sh for the given winner, looking at the resulting winner index.html locally using the method outlined in comment 1893176110. Because what really matters now is what the resulting winner index.html looks like from a web browser.

[lcn2]

This approach would require one to regenerate ALL HTML files that use inc/begin-rightcolumn.default.html, which because it is a default file for the "begin-rightcolumn" phase, is nearly all (if not all) HTML files. One cannot use the bin/quick-readme2index.sh either one can to force the rebuild of ALL HTML files and then test ALL HTML files to verify that the fix did not create a bunch of new problems.

Speaking of such. What will the other html files (from other markdown files I mean) be using?

For this issue, only the winner index.html files are involved. As it states in the issue title "... winner index.html files".

When other HTML files are generated, there will be other issues to review them: likely 2 more issues that will be created, one for the winner non-index.html files and one more for all of the top level HTML files, one those HTML files are generated in the first place.

[xexyl]

This approach would require one to regenerate ALL HTML files that use inc/begin-rightcolumn.default.html, which because it is a default file for the "begin-rightcolumn" phase, is nearly all (if not all) HTML files. One cannot use the bin/quick-readme2index.sh either one can to force the rebuild of ALL HTML files and then test ALL HTML files to verify that the fix did not create a bunch of new problems.

Speaking of such. What will the other html files (from other markdown files I mean) be using?

For this issue, only the winner index.html files are involved. As it states in the issue title "... winner index.html files".

When other HTML files are generated, there will be other issues to review them: likely 2 more issues that will be created, one for the winner non-index.html files and one more for all of the top level HTML files, one those HTML files are generated in the first place.

Sure .. but I was thinking of in general. But I'll worry about that later on. Thanks.

Still what problem existed in I think you said 2020/ferguson1/README.md ? That way I can correct it.

[xexyl]

The generated winner index.html files need to have their "look and feel" improved.
NOTE: As of the time this issue was created, the procedure to generate HTML files other than winner index.html files has not been completed, this issue restricts itself to just the "look and fee" of the winner index.html files.
Using the method outlined in issue #1933, the winner index.html files may still be improved.
HINT: One may generate a single winner index.html file by using the bin/readme2index.sh tool on a single winner. For example, to regenerate 2020/ferguson1/index.html:

bin/readme2index.sh -v 3 2020/ferguson1

:-)
About that entry .. didn't you say I needed to fix something there in the README.md and maybe other markdown files? What did you have in mind (well besides the markdown file references on GitHub should be removed which I'll get to)?

We just needed a fake example to use.

Right but I thought you said some days back that that file needed some fixes?

[xexyl]

Or next might be to use a slightly modified inc/begin-rightcolumn.default.html file (lets pretend this file is called inc/begin-rightcolumn.1984_anonymous.html), by adding a special line to the inc/md2html.cfg file before BEFORE more general configuration line. For example:

# Fake example: We must disable pandoc warnings for 1984/anonymous because those warnings
# are not valid and we need a fake example.

1984/anonymous/README.md         -o bin/subst.default.sh -o bin/subst.winner-index.sh -b bin/gen-author.sh -a bin/gen-inventory.sh -P '-f markdown -t html --quiet` -H begin-rightcolumn=1984_anonymous

# Unless matched above, default process all winner README.md files

[12][0-9][0-9][0-9]/*/README.md         -o bin/subst.default.sh -o bin/subst.winner-index.sh -b bin/gen-author.sh -a bin/gen-inventory.sh
mock/*/README.md                        -o bin/subst.default.sh -o bin/subst.winner-index.sh -b bin/gen-author.sh -a bin/gen-inventory.sh

See the inc/md2html.cfg file comments for more information.
Again, we suggest you try and fix it by changing the README.md file first, before you try and setup a special case inc/md2html.cfg line.

Perhaps it'll be helpful to have all the html files generated so we can see what they look like here so I can know what to fix?

They ARE generated ‼️ Well OK, only all of the winner index.html files are generated. 😉 Maybe we did not announce that fact with enough fanfare? 😀

No .. you did indeed mention it. I was thinking of something specific but I'm afraid I don't know what it is now. Maybe it's already fine as it is. That's possible - it might just be I have to look at the rendered files to find errors.

OK, as mentioned the higher level HTML files and the winner HTML files that are not index.html still need to be generated. 😉

Of course.

It was a milestone that we had been working on for months. It was why we asked to hold off on edits being made to the manifest numbers spreadsheet until now. It was the reason for the creation of all those new issues, etc.

I remember you saying that yes. And I wish I had thought of the fact that I know of some errors in one of my entries. Wrong file name. Well I won't do that today. The manifest task is taking too much for me today. I really don't know why I am so exhausted today but I am.

start side note

We are actively working on generating the rest of the HTML files (see the TODO list of issue #4): racing to try and finish issue #4 before the other ((top primary)) issues are completed. For a number of people, work on issue #2 and issue #3 might seem nice, but as they might not take the time to try all of the IOCCC winners of the past, they might not understand the full benefit .. that it until they are looking at past winners for ideas and discover that they actually have a reasonable change to download the core, compile it and run it today. Sadly it will be the look and feel that will catch the attention of most people.

Hmm yes I can imagine that. I don't think nearly as many people understand how many entries no longer worked and how almost all of them now do. And the ones that don't I think work in some platforms. In one case I'm pretty sure it has to do with the version of perl in macOS, as to why it crashes. I think this based on the author's remarks.

Even those that do they might not care as much as the look and feel as you say. Presentation etc. seems to get to people in ways that sometimes goes to quite some extremes. The flashy websites being something that so many people like (even if the content is not quality) is a classic example.

The winner index.html files are ready for review and improvement on their look at feel. Again this isn't to say that the tremendous work on issue #2 and issue #3 are not important: they are very important and your efforts on behalf of the IOCCC website are very much appreciated.

Thank you very much! I needed to hear that! When I'm done with that other issue, 3, I will look at the rendered files and then go from there. It is probably better that order anyway since that way I can be sure the html files are up to date. As noted in another issue some are not now (though they're being updated). Then if a file name changes or a file is added or removed or that also means the index.html is out of date. So better to finish that first. Though I have to say today the manifest one is getting to me. But that's because I'm extremely tired - more than usual - and also probably because it's my first time with the very long process.

If we were make a new accouchement now about the work done so far, and people see a bunch of broken links, missing HTML files, etc. it will be hard for some people to perceive the tremendous progress that was made by issue #2 and issue #3. Thus we have be working very hard to race to try and get the look and feel ready so that your important efforts may present themselves in a good light for others to see.

That's true and it's also true that there will be broken links. Let me say that differently: there ARE broken links. That includes from typos on my part (normal typos that I haven't gone back to 'zoom in on' yet and also it's possible I had the wrong link to type .. and then there are other things too).

end side note

And as the top comment suggests, much of the work will likely involve editing the README.md file, running bin/readme2index.sh for the given winner, looking at the resulting winner index.html locally using the method outlined in comment 1893176110. Because what really matters now is what the resulting winner index.html looks like from a web browser.

Yes. I'm still doing that of course.

I think manifest issue is about done, what I'm working on, so I'll post this and hopefully be making a pull request shortly.

[lcn2]

Added an "UPDATE 0" to the top level comment.

[xexyl]

Added an "UPDATE 0" to the top level comment.

I did like the 2020 version of the entries' index.html files and the year's index.html too but I also liked the way you had the index.html files here. Speaking of such I thought you had linked to an example index.html that was rendered as html. I can't find it now though. Can you post it again please? Thanks. That'll help I think.