Landon Curt Noll
0c6628d667
Moved thanks-for-fixes.md -> thanks-for-help.md References to thanks-for-help.md are referred to as just the _thanks file_. Updated links to reflect the above file change. Links to winner files in bugs.md now start with /. Updated the `/inc/sidenav.default.html` file to use an improved sidenav menu that includes a link to "How to enter the IOCCC". Fixed reference to FAQ entry regarding 'gets()' in `bugs.md`. Removed some trailing whitespace in `bugs.md`. Removed some trailing whitespace in `faq.md`. Fixed links into specific thanks file entries. Added more info to FAQ 0.0 "How may I submit to the IOCCC?". The temporary top level HTML files (contact.html, index.html, judges.html, news.html, winners.html, years.html) have a consistent set of links (w/o any bold links) that match the revised `/inc/sidenav.default.html` sidenav menu. These temporary top level HTML files are not yet being built and so they do not yet use the `inc/*.html` system. TODO: Turn contact.html, index.html, judges.html, news.html, winners.html, and years.html into markdown files that markdown to HTML tools will generate.
inc
The inc directory holds content that is used by the build-ioccc repo
HOWEVER ... XXX
While the build-ioccc repo is not ready, tools under temp-test-ioccc repo tmp directory will use files in this directory.
Why the name inc?
We use inc because "include" would be misleading for both C and because the contents of HTML files under inc are not really included by the web server or the browser. Content of HTML files is processed by tools in the build-ioccc repo. Processing can include substitution of strings of the form %%CURDS%% with some command line supplied value by the tool in question.
How HTML content is built
Files under the inc directory contain HTML fragments that the build-ioccc repo tools use to form HTML content for the official IOCCC web site.
The canonical way that HTML content is built uses, by default, files of the form:
*.default.html
HTML phases
The following HTML phase files are used to build HTML content:
- inc/top.default.html
- inc/head.default.html
- inc/body.default.html
- inc/header.default.html
- inc/topnav.default.html
- inc/begin-row.default.html
- inc/begin-leftcolumn.default.html
- inc/sidenav.default.html
- inc/end-leftcolumn.default.html
- inc/begin-rightcolumn.default.html
- inc/before-content.default.html
Phases 11-19 are reserved for future use.
- <>
- <>
- <>
Phases 23-29 are reserved for future use.
- inc/after-content.default.html
- inc/end-rightcolumn.default.html
- inc/end-row.default.html
- inc/footer.default.html
- inc/bottom.default.html
Phases 35-39 are reserved for future use.
In the above HTML phases, except HTML phases 20-29, symbols of the form %%TOKEN%% are substituted.
Tool command line
The command line of a build-ioccc repo tool, and perhaps modified via md2html config file file may change to using a different filename for a given phase.
For example when forming the HTML from 2020/ferguson2/chocolate-cake.md,
a different "topnav" navigation bar is needed. So instead of the
usual top navigation bar that normally directs people to the previous
entry for the year, or go up to the year page, or to the next entry
for the year, a top navigation bar to just go up to the entry's
main page is needed. A line the md2html config file file
that refers to 2020/ferguson1/chocolate-cake.md may specify use
of topnav.up2index.html instead of using the topnav.default.html default.
The HTML phase may be skipped resulting in no HTML output during a given phase. Furthermore, forming HTML content from a given markdown file altogether.
See comments in the md2html config file file for details.
Use CAUTION when modifying inc files
Some of the files under this directory are used to form MOST of the HTML content on the official IOCCC web site:
HOWEVER ... XXX
Well, until the official IOCCC web site, via the IOCCC winner repo is ready for the mass pull request/merge, these files are used to form MOST of the HTML content on the experimental web site.
... and in particular files under inc that are of the form (called default HTML files) ...:
*.default.html
... contain default content used to form IOCCC HTML / IOCCC web pages.
Instead of editing the default HTML files in order to fix a special web page, consider making a copy of the default file and modifying the md2html config file to refer to the copy instead. That way your special case situation will not impact MOST of the HTML content.
Why do we do not use certain well know HTML technology
You may wonder why we need these files in the first place. You may wonder why we even need the tools in the build-ioccc repo when there other solutions available to form web pages.
Static web pages only
Here are some reasons why we are using these files and special tools to create HTML content / IOCCC web pages:
We host official IOCCC web site via GitHub pages. As of the time this file written, only static web pages are supported.
Cannot use server side include
We use static web pages, so use of "server side include" is not available to the IOCCC.
For example, Apache SSI "#include" does not work on GitHub pages.
Cannot use a back-end database
We use static web pages, so use of "back-end database" is not available to the IOCCC.
Cannot use non-GitHub web servers
The GitHub pages have the distributed server capacity needed to handle the huge download volume or Slashdot effect that happens when a IOCCC winners are published.
Most so-called low cost web hosting sites have a somewhat hidden excessive bandwidth charge and/or cap bandwidth when the volume gets too high, and/or do not have the infrastructure that can handle the Slashdot effect.
The IOCCC had experience with people offering web mirrors and even free hosting only to find that the generous benefactor moves on, or their service is purchased by someone else who is not so generous. While it is possible that GitHub might someday suffer a similar fate, for the time being we are betting that GitHub will remain willing to host the IOCCC.
The official IOCCC web site is, after all, primarily C source code with some supporting documentation. As such it is a natural fit for GitHub and GitHub pages.
cannot use the HTML object tag
The < object > HTML tag does not work for our needs.
The browser context relationship between the HTML content holds the HTML tag does not extend into the content that the tag includes. For example, menu bars will not operate as specified by the ioccc CSS.
cannot use the HTML embed tag
The < embed > HTML tag does not work for our needs.
This tag wants one to specify the width and height in pixels. Use of a percentage is not officially supported even if some browsers might do so. Our Responsive Web Design on the ioccc CSS needs to be responsive to small-sized cell phone-like screens, mid-sized table-like screens, as well as large-sized desktop-like screens. Specifying a width and height in pixels will not work well in all of those screen size contexts.
cannot use the HTML iframe tag
The < iframr > HTML tag does not work for our needs.
This tag wants one to specify the width and height in pixels. Use of a percentage is not officially supported even if some browsers might do so. Our Responsive Web Design on the ioccc CSS needs to be responsive to small-sized cell phone-like screens, mid-sized table-like screens, as well as large-sized desktop-like screens. Specifying a width and height in pixels will not work well in all of those screen size contexts.
cannot use JavaScript to include content
We do not use JavaScript to include HTML content.
While the IOCCC may use JavaScript in the future to directly render things like C source code, we will do so in such a way that someone will be able to view official IOCCC web site content with JavaScript disabled.
The IOCCC will NOT MANDATE USE OF JavaScript to view official IOCCC web site.
For this reason, we cannot use JavaScript include HTML content.