release readme2index.sh version 1.0 2024-01-14
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
1 parent
f5a259d3b3
commit
c6e6201209
366 files changed
+29369
-31783
No files matched your search
+247
@@ -0,0 +1,247 @@
|
||||
# bin
|
||||
|
||||
The directory holds [bin](README.md) directory
|
||||
holds tools that builds files, such as HTML content, for the
|
||||
[official IOCCC web site](https://www.ioccc.org).
|
||||
|
||||
For HTML content, the [bin](README.md) directory tools
|
||||
makes use of HTML fragments from the [inc](../inc/README.md) directory
|
||||
as well as various JSON files and other content from the
|
||||
[IOCCC GitHub repo](https://github.com/ioccc-src/temp-test-ioccc).
|
||||
|
||||
|
||||
## bin tools
|
||||
|
||||
|
||||
### [gen-author.sh](gen-author.sh)
|
||||
|
||||
Output winning author(s) Related HTML.
|
||||
|
||||
|
||||
### [gen-inventory.sh](gen-inventory.sh)
|
||||
|
||||
Output the inventory in HTML form for a winner index.html page.
|
||||
|
||||
|
||||
### [manifest.winner.json.awk](manifest.winner.json.awk)
|
||||
|
||||
Output manifest table from a winner .winner.json file.
|
||||
|
||||
|
||||
### [pandoc_wrapper.sh](pandoc_wrapper.sh)
|
||||
|
||||
Wrapper tool to run pandoc.
|
||||
|
||||
|
||||
### [readme2index.sh](readme2index.sh)
|
||||
|
||||
Convert README.md into index.html.
|
||||
|
||||
|
||||
### [subst.default.sh](subst.default.sh)
|
||||
|
||||
Print default substitutions.
|
||||
|
||||
|
||||
### [subst.winner-index.sh](subst.winner-index.sh)
|
||||
|
||||
Print substitutions for a winner index.html.
|
||||
|
||||
|
||||
### [subst.winner-navbar.awk](subst.winner-navbar.awk)
|
||||
|
||||
Output substitutions for navbar on behalf of a winner.
|
||||
|
||||
|
||||
## How HTML content is built
|
||||
|
||||
Files under the [inc](../inc/README.md) directory contain HTML fragments that the
|
||||
tools in the [bin](README.md) directory
|
||||
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 tool' output))
|
||||
21. ((insert 'pandoc wrapper tool' output))
|
||||
22. ((insert 'after 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 phase numbers, except during HTML phase numbers 20-29, symbols of the form %%TOKEN%% are substituted.
|
||||
Any %%TOKEN%% printed by the 'before tool' (-b tool), the 'pandoc wrapper tool' (-p tool), and the 'after tool' (-a tool)
|
||||
are ignored (i.e., not substituted).
|
||||
|
||||
See the tool [readme2index.sh](readme2index.sh) for an example of
|
||||
how HTML phases are implemented.
|
||||
|
||||
|
||||
### Tool command line
|
||||
|
||||
The command line of tools in the [bin](README.md) directory,
|
||||
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.
|
||||
See also, the tool [readme2index.sh](readme2index.sh) for an example of
|
||||
how such command lines are used.
|
||||
|
||||
|
||||
## 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).
|
||||
|
||||
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/README.md) 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](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 [bin](README.md) directory
|
||||
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.
|
||||
Reference in new issue
Block a user