The fixes in bin/README.md include typo fixes, link fixes, format fixes
as well as adding a couple terms that are now used by the IOCCC
(submission and submitter).
The typo fixes in bin/csv2entry.sh were deemed worth putting in this
commit as a lot of the changes in the document are related.
Fixed typo in `make csv2entry` rule in `Makefile`.
Fixed how exit codes triggered deep within loops are realized.
Regularize how raising an exit codes with loops are announced.
The use of `-n` does NOT prevent the creation of temporary files:
only permanent files are not modified with `-n`. NOTE: While
CSV files are NOT permanent files, they too are not modified with `-n`.
Fixed the canonical sort of `manifest.csv`. Now running
`bin/csv2entry.sh` immediately after `bin/entry2csv.sh` will not
modify `manifest.csv`.
If `bin/csv2entry.sh` encounters an author handle for which
there is no `author/author_handle.json` file, the tool will
complete the formation of the CSV file set and then exit 9
at the very end.
Fixed a few comments in `bin/csv2entry.sh` and `bin/entry2csv.sh`.
In `bin/entry2csv.sh` changed VERSION from "1.0.3 2024-07-19"
to "1.0.4 2024-07-19".
In `bin/csv2entry.sh` changed VERSION from "1.0 2024-07-19"
to "1.0.1 2024-07-19".
Performed `make www` to accomplish the above and to test under macOS.
TODO: Incorporate as needed, more processing of `author/author_handle.json` files.
TODO: Remove the `tmp` directory (after saving contents into private storage).
The Makefile rules now have a comment for what they do. The help rule
has not been updated.
The bin/README.md has had some format fixes and some typo fixes as well.
Rebuilt bin/index.html but these two files will have to be checked more
thoroughly later.
Added `bin/csv2entry.sh` VERSION "1.0 2024-07-19".
In `bin/entry2csv.sh` changed VERSION from "1.0.2 2024-07-14"
to "1.0.3 2024-07-19".
The `bin/entry2csv.sh` tool converts all entry `.entry.json` files
into canonicalized `author_wins.csv`, `manifest.csv`, and `year_prize.csv`
CSV files.
The `bin/csv2entry.sh` tool converts `author_wins.csv`, `manifest.csv`,
and `year_prize.csv` (canonicalizing them if needed) `.entry.json`
files for all entries.
To change the manifest for one or more entries:
```sh
bin/entry2csv.sh -v 1
# ((import `manifest.csv` into a spreadsheet tool))
# ((modify in the spreadsheet tool, the content as needed))
# ((export the spreadsheet contents, as the CSV file `manifest.csv`))
bin/csv2entry.sh -v 1
make www
``
To change the award for one or more entries:
```sh
bin/entry2csv.sh -v 1
# ((import `year_prize.csv` into a spreadsheet tool))
# ((modify in the spreadsheet tool, the content as needed))
# ((export the spreadsheet contents, as the CSV file `year_prize.csv`))
bin/csv2entry.sh -v 1
make www
``
To change the authorship of one or more entries:
```sh
bin/entry2csv.sh -v 1
# ((import `author_wins.csv` into a spreadsheet tool))
# ((modify in the spreadsheet tool, the content as needed))
# ((export the spreadsheet contents, as the CSV file `author_wins.csv`))
bin/csv2entry.sh -v 1
# ((modify winning_entry_set of `author/author_handle.json` files as needed))
make www
``
Performed `make www` to accomplish the above and to test under macOS.
TODO: Review and improve/expand as needed, changes that were made to `bin/README.md`.
TODO: Remove the `tmp` directory (after saving contents into private storage).
We move `tmp/format-headers.sh` into `bin/format-headers.sh`.
We also add a few missing empty lines to `README.md`.
We add `bin/format-headers.sh` to the `bin/README.md`.
We run `bin/format-headers.sh` to perform the above.
Performed `make www` to accomplish the above and to test under macOS.
We use the `status_codes=("${PIPESTATUS[@]}")` method to
collect all of the bash exit codes from a pipe in one go,
and then test for any failure with `[[ ${status_codes[*]} =~ [1-9] ]]`.
There are other cases where an exit code is obtained,
however in each of those cases only a single exit code
from just one of the commands in the pipe is needed.
In `bin/gen-sitemap.sh` changed VERSION from "1.3.9 2024-06-21"
to "1.3.10 2024-07-18".
In `bin/gen-status.sh` changed VERSION from "1.5.4 2024-07-18"
to "1.5.5 2024-07-18".
Performed `make www` to accomplish the above and to test under macOS.
We improve the language in `SECURITY.md` and the resulting
`SECURITY.html` page, and add an important disclaimer. We also add
that same disclaimer to the bottom of the of the main `index.html`
we page (via `index.md`).
The location of the link is in the About menu under the 'Contacting the
IOCCC' and above 'Thanks for the help'. At first I had it at the very
bottom, under 'IOCCC markdown guidelines', but it seemed better to have
it closer to contacting the IOCCC. This is the same location in the no
JavaScript menu (which, for those who do not know or forget, is not a
requirement except for some screen sizes).
The top level Makefile has a new 'security' rule. Updated make help.
Typo fixes in make help.
SECURITY.html has had a few updates as well: change the wording of entry
code is unsupported (it now says 'ALL CODE IN ALL IOCCC ENTRIES IS
UNSUPPORTED!!') and it now links to the mkiocccentry repo and how to
report a possible security vulnerability in that repo; as that IS
supported - and since there was reference to discussing security
concerns is in SECURITY.html - even though the entries will not receive
security updates - it seemed a good idea to have a link to report such
security issues in the mkiocccentry repo. Perhaps the FAQ needs to be
updated for this too.
We add a new `bin/entry2csv.sh` tool VERSION "1.0 2024-07-14"
that will convert entry `.entry.json` files into 3 CSV files
`author_wins.csv`, `manifest.csv`, and `year_prize.csv`.
The `bin/entry2csv.sh` tool uses `bin/manifest.csv.entry.awk`.
The new `bin/manifest.csv.entry.awk` VERSION is "1.0 2024-07-14".
This tool will be used to convert entry `.entry.json` file into
CSV files suitable for importing into a spreadsheet application
for further processing.
TODO: Write the `bin/csv2entry.sh` tool, for a given entry, to
convert 3 CSV files into that entry's c`.entry.json` file.
Also removed what seems to be unnecessary quotes, much along the lines
in some FAQ links (that will be having the quotes removed).
Added SECURITY.md to bin/md2html.cfg and updated bin/gen-top-html.sh to
build SECURITY.html. The configuration can be improved for keywords and
other things and the file is not linked into the website either but
presumably it should be.
While the use of `**font-weight: bold;` helps links standout in
most cases, there a few "_link heavy_" pages were the **MANY BOLD
LINK IN CLOSE PROXIMITY** looks excessive to the point of being
distracting. In areas where **nearly everything is BOLD, nothing
seems to stand out**.
Fortunately there seems to be only a very few places where this is a problem:
* `faq.html` - the table of contents
* `authors.html` - nearly the entire page
* `location.html` - nearly the entire page
* `years.html` - nearly the entire page
As an **bold** 😎 experiment we added to the CSS:
```css
/*
* To make a link non-bold, use: <a class="normal" href="url">link text</a>
*/
a.normal {
font-weight: normal;
}
```
And then modified select tools and a markdown file to "_unbold_"
those "_link heavy_" areas of the 4 pages above.
We don't claim that this is the best solution and there may be an
even better way to solve this, nevertheless we **do** think the it
improves the look and feel of the "_link heavy_" areas of the 4
pages above. For example, in `faq.html` beyond the table of
contents, the bold links look reasonable (although again there are
some quasi-"_link heavy_" areas down in the page look a bit too
bold, but perhaps not enough to warrant changing so we only altered
the table of contents).
In a few cases, while we were editing code that generated links,
we remove a few "**.**"'s where we didn't think they helped the
look and feel.
Change `bin/gen-authors.sh` VERSION from "1.10.3 2024-05-24"
to "1.10.4 2024-07-13".
Change `bin/gen-location.sh` VERSION from "1.4.2 2024-05-19"
to "1.4.3 2024-07-13".
Change `bin/gen-years.sh` VERSION from "1.3.3 2024-07-07"
to "1.3.4 2024-07-13".
Performed `make www` to accomplish the above and to test under macOS.
Repaired the output_award function in `bin/gen-years.sh`
and `bin/output-year-index.sh`.
Previous modifications to the output_award function made
is impossible to detect if output was empty.
Modifications also ran counter the Unix concept that a function
should ideally to one thing and one thing well.
Changed so that the code that called the output_award function
would decorate the award with bold markdown syntax.
Changed `bin/gen-years.sh` VERSION from "1.3.2 2024-05-19"
to "1.3.3 2024-07-07".
Changed `bin/output-year-index.sh` VERSION from "1.4.1 2024-04-28"
to "1.4.2 2024-07-07".
Ran `make www` to perform the above and test under macOS.
Instead of using just git use "$GIT_TOOL" as the script already
establishes what git to use.
The comment I added also explains the rationale about this a bit, as it
might not seem immediately clear why it's useful over find(1).
And although it was already tested I forced what would have caused a
failure before, to happen, so that I could verify that this works as I
had originally imagined it: put a file in an entry directory that does
not belong there and then run the script again, to make sure it does not
detect any problem.
Of course with this change one still has to make sure to add valid files
to git but that always was how it was anyway.
Thanks to @xexyl for the suggestion.
Changed `bin/chk-entry.sh` VERSION from "1.1.7 2024-04-28"
to VERSION="1.1.8 2024-07-06".
Performed `make test` to test the above.
Given how problematic leading tabs in markdown files can be,
we have expanded all leading tabs in markdown files by:
```sh
find * -type f -name '*.md' -print |
while read -r file; do
rm -f "$file.tmp" ;
expand < "$file" > "$file.tmp" ;
mv -f -v "$file.tmp" "$file" ;
done
```
Given the previous changes to `bin/pandoc-wrapper.sh` and other recent
commits and recent pull requests, the were were **NO** changes to
any HTML files. This is a **good thing** as the expression goes.
No there are no leading tabs in any markdown files.
A check to catch any re-introduction of leading tabs
into any markdown file is on the way.
BTW: We do not have anything against leading tabs in files,
even though we have had to deal with their impact on forming
HTML from markdown files (as well as the calc source code).
It is just that this is one of those cases where tabs conflict
(sometimes caused by people wanting to change the classic
8-space tab model) with a desired outcome.
Perform `make www` to perform the above and test under macOS.
The `bin/pandoc-wrapper.sh` tool will use `expand(1)` to expand
leading ASCII TAB characters into multiples of 8 ASCII space
characters on all markdown data before piping it into `pandoc(1)`.
Thus, any leading ASCII TAB character in markdown files will be
automatically converted into spaces using 8 character tabs.
Changed `bin/pandoc-wrapper.sh` VERSION from "1.6.3 2024-06-22"
to "1.7 2024-06-22" to preform the above.
Perform `make www` to perform the above and test under macOS.
It turns out that only one other HTML file was impacted: `bugs.html`.
All other leading ASCII tab characters have been rendered
[Mostly Harmless](https://en.wikipedia.org/wiki/Mostly_Harmless). :)
When `bin/pandoc-wrapper.sh` encounters a fatal error, it will
leave behind `debug.input.md` and `debug.output.html`.
Added `debug.input.md` and `debug.output.html` to `.gitignore`.
The `.gitignore` file comment noew refers to `sgi.sh` not sgi.
Changed `bin/pandoc-wrapper.sh` VERSION from "1.6.2 2024-04-18"
to 1.6.3 2024-06-22" to preform the above.
Perform `make www` to perform the above and test under macOS.
While not strictly necessary, replacing the two ASCII tab characters
in the markdown copyright comment makes it easier to detect problematic
TAB indentation within markdown files.
After this commit, only 90 markdown files have leading ASCII TAB
characters. And again, while not strictly necessary, we can consider
running expand on those 90 markdown files to see what effect that
might have on the HTML files they produce.
Replace leading ASCII TAB characters with multiples of 8 ASCII SPACE
characters (the default action of the `expand(1)` tool) might have
an negative effect on some HTML formatting where **hack-a-round**
formatting was attempted to fix broken indentation caused by
problematic ASCII TAB characters.
Think of this as a baseline for evaluating leading
TAB characters within markdown files.
TODO: Consider either using `expand(1)` to replace leading ASCII
TAB characters with multiples of 8 ASCII SPACE characters AND/OR
modifying the appropriate `bin` tool to convert leading ASCII TAB
characters into multiples of 8 ASCII SPACE characters.
One must **NOT** use ASCII TAB characters to intent text. Down the TAB-ed
road is nothing but trouble! There are _quasi-solutions_, however those
have side effects that lead to a different set of problems.
The `markdown.md` was updated to ask that text not be intended with ASCII tabs.
See [Please do NOT use ASCII tabs to indent
text](https://ioccc-src.github.io/temp-test-ioccc/markdown.html#markdown.html#please-do-not-specify-a-language-for-a-code-block).
We discovered this awhile ago and fixed it in markdown files. Sorry
(tm Canada 🇨🇦), we forgot to mention this this in `markdown.md`.
BTW: It took some **deep magic** to be able to show an HTML comment
after a starting fenced markdown code block! See the **NO_COMMENT=**
line in `bin/md2html.cfg`. :-)
TODO: Stamp out indenting TABs in markdown files, especially in code blocks.
TODO: Consider a rule to detect problematic ASCII TAB intendation
within makrkdown files.
Detect were the stat tool is located. If no stat tool is found,
set `$STAT_TOOL` to `false`. Cleanup comments related to
determining the modification time of a file.
Changed `bin/gen-sitemap.sh` VERSION from "1.3.8 2024-04-28"
to "1.3.9 2024-06-21".
Changed `bin/gen-status.sh` VERSION from "1.5.2 2024-04-30"
to "1.5.3 2024-06-21".
Perform `make www` to perform the above and test under macOS.
Make link to entries and award titles bold like the other files that
have links to entries with the award title. This is done by modifying
the bin/gen-authors.sh script.
Make it consistent with my improvement to bin/gen-years.sh: the entry
awards in the links (to each entry) are now in bold and so are the link
names. This helps them stand out a bit more.
The script set the URL for the tarball of all entries in the year to:
$YYYY/$YYYY.tar.bz2 but the link is relative so for 1984, for example,
it would link to 1984/1984/1984.tar.bz2 which obviously is a 404.
I also changed the formatting and wording of the link. It now is all
bold and it says instead (for example with 1984): 'Download all winning
entries from 1984'. Before it still referred to 'entry source' but it is
all entries and more than just the source.
This commit does not mean that the YYYY/index.html files have been
checked (though it's likely that all should be okay at this point) but
the manifest of entries and the tarball of all entries of the year
should at least be good.
It should be 'Location of winning authors' (as it is now) but by mistake
there was an extra space ('Location of winning authors'). Obviously
this is a huge commit as every html file with a menu (almost all) had to
be updated.
A few page names were changed and menu link (titles) were changed too.
By page names it means either DESCRIPTION or HEADER_2 in
bin/md2html.cfg. Although it looks better and is more consistent, there
might be one or two that can be further improved.
Naturally every html file that is markdown based was updated.
This is a very large commit not only because I forgot to run make www
after updating the menus but I also forgot to do that after the update
to some of the award titles (only quick-readme2index.sh was used).
There is a typo fix in bin/README.md.
This commit does mean that md2html.cfg has to be added to bin/README.md
but that can be done later.
The steps run to verify this works okay:
make www
git status
git diff
git add -u
make update
git status
git restore $(git check)
The last is important as it is not time for make update. 'git check' is
an alias:
git diff --name-only
In some pages at the top it had 'and' but in the menu it had instead a
'&'. The menus (JavaScript and otherwise) now has 'and' to match the
pages. The file nojs-menu.html has been checked for broken links and
indeed one at least was fixed. Very few top level html files need to be
checked now. Some that are entirely generated should be okay but links
will still be checked to be sure.
Some cases of '(Mis)features' from the previous commit were also
corrected to '(mis)features' as this is also part of menu and page
consistency.
The files markdown.{md,html} have had the menus updated too but there
are some other changes that were works in progress. This file is not
thus completed but will be sometime soon.
This completes bin/ except that one file is likely to be moved to bin/
which will mean that the file has to be updated again but not in a big
way.
Very few top level html files (including inc/ and some other
subdirectories that are not the years) have to be checked now, I
believe. Some did not require any fixes at all. Still it might be a
couple days before this is done. It is hoped that the entry html files
will go quicker and then the final FAQ and bugs checks can be done.
... including the index.{md,html} which was in all caps ..
The bin/README.md file (and index.html) was updated slightly with an
added comma: not strictly necessary but for some it might be easier to
read. This was discovered as I was going through the links (not done
checking them yet but so far so good).
Usage for scripts where the usage was missing added, even if that's just
that it is used in another file.
The script links have been changed to use %%REPO_URL%% for the GitHub
syntax highlighting. Some other files have also been changed to this.
Other changes were probably made too.
Links still have to be checked but this has to be done next time.
The PANDOC_WRAPPER did not have a default value which not only caused
the help string to show something like: '(def: use )' but it meant one
had to specify the option -p to specify the pandoc wrapper tool (which
is bin/pandoc-wrapper.sh).
A few typos were fixed.
One tool had the description reworded a bit to make it (hopefully) a bit
clearer.
A link was fixed but I am not sure if, since it's a script, it should
link to the GitHub repo or not, like with other markdown files. I
changed it to use the %%var%% that the bin/README.md file uses. This is
one reason links have not been checked. The other reason is I have not
gone through the entire file yet.
I notice some tools do not have example usage and those could be added
too.
There was an apparent typo in bin/find-missing-links.sh and this same
typo was fixed in bin/README.md. I am not sure exactly what was meant,
however, so it might need further modifications.
I have (the caveats above notwithstanding) gone up through
pandoc-wrapper.sh or just before it.
Regenerated bin/index.html.
The links in the html file now are a bit more consistent in form and
the titles make a bit more sense.
By that I mean that it used to be that it would say 'About the 1st IOCCC' but only '1st IOCCC' was a link
and 'About' was bold but now it's all bold and now it's all a link (to suggest that the link is actually about
the first IOCCC). The download links were also improved in this way and
they now say 'winning entries' rather than say (for 1984) '1984 entry
source' (that was for all entries). Also, since it would otherwise say
something like:
...
Download all 1985 IOCCC winning entries.
Download all 1984 IOCCC winning entries.
I reworded it to say:
...
Download all IOCCC winning entries of 1985.
Download all IOCCC winning entries of 1984.
As other link titles were in bold in the file now each entry link is in
bold as well and so is the title - to help it stand out a bit better. I
am not quite sure about the bold title yet but the link should be bold
anyway to match others. I think the bold title does seem like a good
idea though.
Rebuilt years.html.
Note that most of the links have been checked in this file but I will
look at each entry link again as I verify links and formatting in the
entries' html files.
For the improvements to the script, besides a typo, a link to the FAQ
(for submitting entries) has been added and a link to the GitHub issues
page (the new issue page) has been added in the case where an unknown
status appears in the status.json file.
The news update is that more progress has been made in that one of the
longer files to check for invalid links is done (thanks file) and that
two long files are left but that instead of looking at those two first
the other html files will be looked at first as it's quite possible that
both will have to be updated in some way or another as the other files
are being edited. Indeed this has happened numerous times already. This
way will save time and prevent having to look at those files a second
time. It also notes that some of the top level html files have also been
reviewed (see below) and a link was fixed (added a <div id="news"> for a
link that was linked to). I am fairly certain that I also fixed some
formatting problems and some links were fixed as well.
The status.md/status.html file has been updated with some links added,
more div blocks (for each section describing the status.json file),
which are used, slight formatting updates and possibly some other things
as well. As for some of the links we might say that it's 'statuses all
the way down' :-)
With this commit I am happy to report that some other top level files
have also been verified for invalid links:
judges.html
news.html
status.html
As the news.html file will be updated it is entirely possible that some
fixes will have to be made but the links up to and including 08 June
2024 (unless more changes are made today of course) need not be checked
again.
More top level html files (which include those in next/ and other
subdirectories that are not of the entries) also have to be checked but
these should also go relatively quickly.
Regenerated status.json file as the news has been updated.
Cody Boone Ferguson