Instead of code blocks the bug / (mis)features statuses are quoted
rather than in a code block. In the case that there is more than one a
line break was added at the end of all but the last one.
A bug status was renamed to be slightly more correct (maybe more than
one was renamed for the same purpose but at least one was).
The bug statuses in the quotes are now bold to let them stand out
better.
It is preferable that unobfuscated code is by the author if they have
(and many have done exactly that).
It would also be preferable to include the author or authors of the entry or
entries if at all possible.
This update includes a link to how to find more information about an
author and I think that FAQ was slightly improved as well.
We quasi-canonicalized markdown links to FAQ entries.
**IMPORTANT NOTE**: This is a useful step in completing issue #2417. This commit is consistent with the top level TODO comment requirements. Nevertheless, this changes made by this commit needs to be examined and in some cases improved.
A link to an FAQ entry is of the form:
```
FAQ on "[the link text](....faq.html#string)"
FAQ on "[the link text](....faq.html#string)"
```
The "FAQ" is at the start of the line, or in rare cases is preceded only by whitespace.
The reference to the FAQ starts outside of the markdown link with the string **FAQ ON "**.
After the markdown link is a **"** followed by either the end of line or a single punctuation character such as a period or comma.
We reduced the size of "the link text" that refer to an FAQ to at most 3 words. In some cases the sentence and/or text surrounding the markdown link to a FAQ may need to be further adjusted to better accommodate this new style.
**IMPORTANT NOTE**: References to a FAQ entry are on a separate line.
p.s. When linking to the `faq.html` file itself, we use markdown of the form "`the [IOCCC FAQ](..../faq.html)`" and place the word "the" outside of the "IOCCC FAQ" link text.
Given the above system (and because references to an FAQ entry is on a separate line), the following command shows links to FAQ entries, sorted by FAQ entry "link #name" so that one may evaluate the way a given FAQ entry is referenced:
```sh
find * -name '*.md' -print0 | xargs0 grep -E '^[[:space:]]*FAQ on "' | sed -e 's/^\([^:]*\):\( *FAQ on "[^#]*\)#\([^)]*\)\()".*\)$/#\3\t\1\t\2#\3\4/' | sort
```
The above command shows the value of consistency when it comes to FAQ references.
**NOTE**: There are a few differences on how a given FAQ is references. That is probably OK as there is NOT an "total mandate" that all references to a given FAQ must have the same "link text" for example. On the other hand if references to a given FAQ can be identical, that might be helpful. We are certain that in some contexts the "link text" might need to change.
Should we decide to change the way FAQ are referenced, we will be able to modify identify and modify them with greater ease.'
Examine the changes made by this commit and adjust and/or improve as needed.
Performed `make www` to accomplish the above and to test under macOS.
This solves a problem with smaller screens where the code would wrap to
the next line which ruins the formatting of the code on smaller devices.
A downside to this is that it makes it not fit on the screen but since
it technically did not fit on the screen before and this way line breaks
are not added this seems a much better way. It also will mean we
shouldn't need to try and fix all the other long lines in code blocks
(which not only can be problematic but in some cases it can be wrong -
plus it is taking too much time away from moving from entry to the next
entry to the next entry).
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`).
This code was found on the author's web page about the entry and has
been added as prog.alt.c. I added the try.alt.sh script as well.
Manifest updated and rebuilt .entry.json and index.html files.
The previous url was the GitHub url but he has his own domain. The
alt_url is his article about the winning entry of his (of course if he
wanted something different he could do that but it's a good enough guess
for now).
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.
As a trial, we change the `<pre>..</pre>` and `<code>..</code>`
blocks form "_Indigo_" to "_DarkGreen_".
We needed a colour that was **NOT** on the "_blue_ thru _purple_" colour
range, nor "_red_" that is currently used by links.
We choose "_DarkGreen_" as this is the same colour as the box around
quotes. Given that `<pre>..</pre>` and `<code>..</code>` text
is unlikely to be confused with a box around a quote, we felt this
was a safe colour to try.
We add a FAQ version of "28.0 2024-07-14" to `faq.md`
using a similar form of version strings as `next/rules.md`
and `next/guidelines.md`.
Ran `make faq` to perform and test the above under macOS.
These are very detailed as they are very important parts of the
mkiocccentry toolkit. The guidelines will likely refer to these for
those who want to know more details but that is for another commit.
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.
In case someone wants more of a challenge in a subsection of the judges'
remarks it has the notice about trying to figure it out by looking at
the code and only (unless they are not looking for an additional
challenge) if they get stuck should they come back to read the author's
remarks.
This includes updates from a recent change in txzchk and more details
about the tools and what they check (warnings and errors) and how to use
them individually.
This does need to be reviewed further, possibly being shorted or
referring to an FAQ, but it's a good start.
The rules had a typo fix as well.
Some of these are very important technical fixes as they stated things
that were not accurate. Other things were (hopefully) clarified. Another
check will have to be done sometime soon.
This does mean that in some cases there is now redundant markdown '**'s
to make the links bold but those can be removed as they are discovered -
or not.
Landon Curt Noll