mirror/ioccc
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

release readme2index.sh version 1.0 2024-01-14

Browse Source 
The initial release of `bin/readme2index.sh` tool that converts
`READMD.md` and various JSON files such as `.winner.json`
as well as "author/author_handle.json" files.

Applied the `readme2index.sh` tool to generate `2020/ferguson1/index.html`.

We generated the  `2020/ferguson1/index.html` by executing:

```sh
./bin/readme2index.sh -v 3 2020/ferguson1
```

NOTE: This above tool requires **pandoc to be installed**.
See the [pandoc web site](https://pandoc.org) for how
to install.  We used _HomeBrew_ to install it,
but there is also a _macports_ process as well.

NOTE: While the above web page does have formatting issues, it is
a first attempt data driven programmatic web page generation.

Some adjustments can be made by mostly improving `ioccc.css`,
and some perhaps by modifying how `bin/pandoc_wrapper.sh`
invokes pandoc.  But probably most of the improvements can
be made by fixing and improving `ioccc.css`.

TODO: Fix and improve the `2020/ferguson1/index.html`
web page by fixing and improving `ioccc.css`.

Moved scripts and tools needed to generate HTML pages
into a new `/bin` subdirectory.

TODO: Consider getting rid of the [build-ioccc
repo](https://github.com/ioccc-src/build-ioccc) and just use the
`/bin` subdirectory.

NOTE: Some links in the `2020/ferguson1/index.html`
web page do not (yet) exist.

TODO: Once the basic format of the `2020/ferguson1/index.html` web
page is somewhat reasonable, generate `index.html` pages for other
winners.  Generate the year level `index.html' files.
Generate the top level HTML files, including the missing
`location.html` file.

Greatly simplified the `.winner.json` file format,
removing a number of fields that were not strictly needed
for generating an inventory on a `index.html` page.

Updated various versions:

* `bin/gen-author.sh` VERSION="1.3 2024-01-14"
* `bin/gen-inventory.sh` VERSION="1.0 2024-01-14"
* `bin/manifest.winner.json.awk` VERSION="1.0 2024-01-14"
* `bin/pandoc_wrapper.sh` VERSION="1.3 2024-01-14"
* `bin/readme2index.sh` VERSION="1.0 2024-01-14"
* `bin/subst.default.sh` VERSION="1.1 2024-01-14"
* `bin/subst.winner-index.sh` VERSION="1.1 2024-01-14"
* `tmp/gen_path_list.found.sh` VERSION="1.1 2024-01-14"
* `tmp/gen_winner_json.sh` VERSION="1.1 2024-01-14"

The `.winner.json` file format from winner_JSON_format_version
"0.5 2023-11-04" to "1.0 2024-01-14".

All `.winner.json` files have been updated to use the
new `.winner.json` file format.

The manifest (`tmp/manifest.numbers` and `tmp/manifest.csv`) has
updated to use the new `.winner.json` file format.

The following procedure was used to generate the
`tmp/manifest.csv` manifest file:

0. open [manifest.numbers](manifest.numbers) in numbers: modify if/as needed

NOTE: Please try to keep the [manifest.numbers](manifest.numbers) spreadsheet
      in order order.  Use Organize -> Sort -> ((Sort Now)) to sort.

NOTE: Empty fields in the [manifest.numbers](manifest.numbers) spreadsheet
      are not allowed.  By default, a cell that is empty is colored
      as a warning.

1. File -> Export To -> CSV...
    * 1a. `[ ]` Include table names (unset)
    * 1b. Text Encoding: Unicode (UTF-8)
    * 1c. Click ((Save..))

2. Save As: manifest.csv
    * 2a. Select the `tmp` directory

3. Click ((Export))
    * 3a. If needed click ((Replace))

4. Execute ./tmp/[fix_csv.sh](fix_csv.sh)

NOTE: You must run the [fix_csv.sh](fix_csv.sh) in the above
      step in order to make the CSV file usable by other tools.

NOTE: If no changes are needed in the above step, the
      original file content will be restored.

5. Execute ./tmp/[gen_path_list.found.sh](gen_path_list.found.sh)

NOTE: The above step silently performs a `make clobber` at the
      top level, and so it takes a bit of time.

NOTE: If no changes are needed in the above step, the
      original file content will be restored.

6. Execute ./tmp/[check_path_list.sh](check_path_list.sh)

NOTE: The above step prints nothing and for an exit 0, then
      all is well.  If there is a problem, such as files
      found that are not part of the manifest, or files
      in the manifest that are not found, then an error
      message will be printed and the tool will exit non-zero.
      If errors are reported, go back to step 0 and
      correct the errors.

7. Execute ./tmp/[run_all.sh](run_all.sh) ./gen_winner_json.sh

NOTE: The above step will take a few seconds to run.  It will rebuild
      all `.winner.json` files for all winners.

NOTE: If no changes are needed in the above step, the
      original file content will be restored.

8. Execute `git status` and inspect changes

NOTE: Check in changes if and as needed.

NOTE: In a number of shell scripts under `bin/*.sh`,
      and in the `bin/manifest.winner.json.awk` script
      you will find comments of the form:

```
```

This is a note that when tools such as `jnamval` (and `jval` and `jfmt`) are
ready, these gross hacks should be replaced with calls to those tools.
Until they are ready, some must be careful with the layout of JSON files.

A number of bugs and typos have been fixed.

NOTE: Fixing typos in the files touched by this comment is welcome.
      This includes scripts, data files, text files, etc.

The _inventory_order_, _display_as_, _display_via_github_.  and
_winners_text_ fields of the [manifest.numbers](manifest.numbers)
spreadsheet were just set to have some initial values.
As they impact the inventory displayed on `index.html` pages,
their content needs to be improved.

NOTE: Improving the above mentioned fields of the
      [manifest.numbers](manifest.numbers) spreadsheet is welcome.
This commit is contained in:
Landon Curt Noll committed 2024-01-14 22:03:28 -08:00
1 parent f5a259d3b3
commit c6e6201209
366 files changed
+29369 -31783
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

inc/README.md
+4 -202
View File
@@ -1,212 +1,14 @@
# inc
The [inc](/inc) directory holds content that is used by the
[build-ioccc repo](https://github.com/ioccc-src/build-ioccc/tree/master)
**HOWEVER ...** XXX
While the build-ioccc repo is not ready, tools under
[temp-test-ioccc repo tmp directory](https://github.com/ioccc-src/temp-test-ioccc/tree/master/tmp)
will use files in this directory.
The [inc](README.md) directory holds content that is used by the
tools in the [bin](../bin/README.md) 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](/inc) are not really included
the contents of HTML files under [inc](README.md) are not really included
by the web server or the browser. Content of HTML files is
processed by tools in the [build-ioccc repo](https://github.com/ioccc-src/build-ioccc/tree/master).
processed by tools the [bin](../bin/README.md) directory.
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](/inc) directory contain HTML fragments that the
[build-ioccc repo](https://github.com/ioccc-src/build-ioccc/tree/master)
tools use to form HTML content for the [official IOCCC web site](https://www.ioccc.org).
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:
0. inc/top.default.html
1. inc/head.default.html
2. inc/body.default.html
3. inc/header.default.html
4. inc/topnav.default.html
5. inc/begin-row.default.html
6. inc/begin-leftcolumn.default.html
7. inc/sidenav.default.html
8. inc/end-leftcolumn.default.html
9. inc/begin-rightcolumn.default.html
10. inc/before-content.default.html
Phases 11-19 are reserved for future use.
20. ((insert before pandoc tool output))
21. ((insert pandoc tool output))
22. ((insert after pandoc tool output))
Phases 23-29 are reserved for future use.
30. inc/after-content.default.html
31. inc/end-rightcolumn.default.html
32. inc/end-row.default.html
33. inc/footer.default.html
34. 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](https://github.com/ioccc-src/build-ioccc/tree/master)
tool, and perhaps modified via [md2html config file](/inc/md2html.cfg) 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](/inc/md2html.cfg) 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](/inc/md2html.cfg) 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](https://www.ioccc.org):
**HOWEVER ...** XXX
Well, until the [official IOCCC web site](https://www.ioccc.org), via the
[IOCCC winner repo](https://github.com/ioccc-src/winner) is ready for the mass pull request/merge,
these files are used to form **MOST** of the HTML content
on the [experimental web site](https://ioccc-src.github.io/temp-test-ioccc/).
... and in particular files under [inc](/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](/inc/md2html.cfg) 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](https://github.com/ioccc-src/build-ioccc/tree/master)
when there other solutions available to form web pages.
### <a name="static-only"></a>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](https://www.ioccc.org) via [GitHub pages](https://pages.github.com).
As of the time this file written, **only static web pages are supported**.
### Cannot use server side include
We use [static web pages](#static-only), so use of "server side include" is not available to the IOCCC.
For example, Apache SSI "#include" does not work on [GitHub pages](https://pages.github.com).
### Cannot use a back-end database
We use [static web pages](#static-only), so use of "back-end database" is not available to the IOCCC.
### <a name="why-github"></a>Cannot use non-GitHub web servers
The [GitHub pages](https://pages.github.com) have the distributed server capacity needed to handle
the **huge download volume** or [Slashdot effect](https://en.wikipedia.org/wiki/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](https://en.wikipedia.org/wiki/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](https://www.ioccc.org) is, after all, primarily C source code
with some supporting documentation. As such it is a natural fit for GitHub and
[GitHub pages](https://pages.github.com).
### 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](/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](/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 _<_ iframe _>_ 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](/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](https://www.ioccc.org)
content with JavaScript disabled.
The IOCCC will **NOT MANDATE USE OF JavaScript** to view [official IOCCC web site](https://www.ioccc.org).
For this reason, we cannot use JavaScript include HTML content.