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

tmp/README.md
+29 -75
View File
@@ -392,7 +392,7 @@ rm -rf ../author ; ./gen_author_json.sh author_handle.txt author.csv author_win
### [gen_winner_json.sh](gen_winner_json.sh)
Generate a `.winner.json` and `inventory.html' for a given winner.
Generate a `.winner.json` for a given winner.
### [gen_path_list.found.sh](gen_path_list.found.sh)
@@ -434,77 +434,56 @@ This file as the following fields:
Path under the IOCCC/directory. In a few cases this is a path,
not just a simple filename under the IOCCC/directory.
4. winners_rank:
4. inventory_order:
If a number, then this is the winners rank showing the order
This number is the winners rank showing the order
that this file is to be listed for the given entry's in
[winners.html](winners.html), or null if the file is not to be listed.
[winners.html](winners.html).
5. created_by:
If the number is 9 digits or less, then the given file
is considered a primary file when listed in the inventory
of files for a given winner.
The name of the program that creates this file, or null if the
file is an original file.
If the number is 10 digits or more, then the given file
is considered a secondary file when listed in the inventory
of files for a given winner. We recommend using the
value **4294967295** (2^32-1) for secondary files.
NOTE: A null created_by value indicates that the file is part
of the primary content. A non-null created_by value indicates
that the contents of the file is created by given program from
primary content files.
5. OK_to_edit:
6. prog:
If the value is `true`, then the file is one that may be
edited directly.
This field indicates if the file main program. This filed is one of:
If the value is `false`, then the file should **NOT** be
edited, because the given file is generated by a tool.
One should **NOT** modify such a file directly, but
instead modify source files (i.e., markdown files,
JSON files, etc.)
main The main source code to display.
alt The alternative source code.
orig The original version of the source code (may be the same as main).
null Not a primary, nor alternative, nor original source code file.
6. display_as:
7. filetype:
The type of given file.
The type of file.
7. display_via_github
8. winners_show:
If `true`, then the contents of the file should be viewed
via the GitHub repo.
A JSON boolean indicating of the file is listed on `winners.html` or not.
If `false`, then the contents of the file should be viewed
in the web browser directly. In some cases this may
result in the file being downloaded instead of being displayed.
The winners_show value must be either true or false.
NOTE: When winners_show is false, display_via MUST be null.
9. display_via:
A string indicating how the file is to be displayed from `winners.html`.
Possible files include:
browser The file is to be displayed directly from the browser.
github The file should be linked to the GitHub repo so that
it may be rendered directly by GitHub. In the future
this may changed to allow a suitable browser to
directly display this file instead of via GitHub.
download The file is intended to be downloaded from the browser
instead of being displayed.
null This file not listed in `winners.html`.
NOTE: When display_via is null, winners_show MUST be false.
10. winners_text:
8. winners_text:
Any text that should be displayed at the end of line in `winners.html`
(with a preceding " - "), or null is no such text is to be displayed.
11. ext:
This ending filename extension, or null if no extension.
This field is not used.
The 11 field names in [manifest.numbers](manifest.numbers), must
The 8 field names in [manifest.numbers](manifest.numbers), must
match the JSON member names found in
[example.dot_winner.json](example.dot_winner.json).
NOTE: Cells containing null are a JSON NULLs.
NOTE: Cells containing true or false are JSON booleans.
NOTE: Empty cells are TBD and need to be filled in.
NOTE: The winners_rank cells are either JSON null or JSON numbers.
NOTE: All other cells are JSON strings that need to be double quoted, including the year.
NOTE: Do not put commas, nor quotes, nor newlines in fields as these are bound to cause problems.
@@ -580,31 +559,6 @@ entries where the "created_by" (5th) field is non-null. See
This file is formed by the [fix_csv.sh](fix_csv.sh) tool.
### [readme2index.sh](readme2index.sh)
This tool is a prototype of the tool that will generate an `index.html`
from a `README.md` file in the winner directory. This tool perfomed
multi-phase getopt parse model as documented in the `inc/md2html.cfg`
configuration file. The `inc/md2html.cfg` configuration file is
scanned for a "yyyy/dir/README.md" match.
Try:
```sh
./readme2index.sh -v 1 2020/ferguson1
./readme2index.sh -v 3 2020/ferguson1
./readme2index.sh -v 5 2020/ferguson1
./readme2index.sh -v 7 2020/ferguson1
```
This tool was based on the (now removed) "sample_getopt.sh" getopt
command line parse demo.
As of the time this text was written, the `README.md` file was
not (yet) generated. And while some _inc/something.sh_ are
exexuted, those scripts are just executable stub demos.
### [sql/winners.sql](sql/winners.sql)
This is a SQL file, extracted from another SQL file that was used in the past