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.
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.
The topbar, by way of JavaScript, now works
on mobile devices such as cell phones and
tablets.
Internal links for entries from 1984 thru 2015
have been adjusted.
Ran `make www` to perform the above.
TODO: Fix some color issues on topbar.
TODO: More testing!
We added a space between the markdown triple code mark
and language that was enclosed in HTML comments.
So a line of the form:
````
```<!---c--->
````
became:
````
``` <!---c--->
````
This was done to **help** some code see that the HTML comment
string was not a markdown code specifier. Not all code
understands this after this changed. For example, `pandoc(1)`
still forms HTML classes of the form "<!---c-->"
when it encounters the above mentioned change.
We also fixed a problem with `2019/dogon/README.md` regarding
a markdown code block.
We also fixed a problem with `2020/yang/README.md` regarding
a markdown code block.
When language is specified in a markdown code block such as:
````
```c
printf("Hello, world!\n");
```
````
is used, the resulting HTML as produced by `pandoc(1)` combined
with our revised `ioccc.css` is not intent the code block well.
A temporary "_hack-a-round_" is to turn the "markdown code language
specifier" into an HTML comment. For example:
````
```<!---c-->
printf("Hello, world!\n");
```
````
This commits turns off existing markdown code language specifiers
for now, while preserving our ability to restore them in the future
when a better "_hack-a-round_" to the "markdown code language
specifier" problem is found.
The HTML impact if this "_hack-a-round_" is to produce HTML that
looks like this:
```
<pre class="<!---c-->"><code> .. </code></pre>
```
We might be able to create a complex set of classes for each markdown
code language (there won't be very many) in `ioccc.css`, or we might
find a more general CSS (or maybe `pandoc(1)`?) solution.
For now, this hack-a-round will have to do.
All code blocks in markdown have been intended by at least 4 spaces.
We add `--tab-stop=8` to all `pandoc(1)` executions in order to set
a better tab stop indentation, especially for tab intended code blocks.
Changed `bin/pandoc-wrapper.sh` VERSION from "1.5.3 2024-03-26"
to "1.6 2024-03-31".
Fixed `1991/brnstnd/sorta.README.md` so that the sorta code
is code blocks.
Removed unneeded paragraph group in copyright in `inc/footer.default.html`.
Fixed excess whitespace after list Author on entry `index.html` page.
Changed `bin/output-index-author.sh` VERSION from "1.5.2 2024-03-26"
to "1.6 2024-03-31".
Performed `make www` to perform the above and test under macOS.
TODO: Fix the problem of the initial line of code being extra intended.
TODO: Fix excess whitespace around code that is inline.
The inc/footer.default.html now has a common Copyright and CC BY-SA
4.0 License section for all generated HTML files.
All markdown files have a similar Copyright and CC
at the bottom in the form of an HTML comment.
Entry source is now prog.c for IOCCC years 2014 thru 2020,
or is now dirname.c IOCCC years 1984 thru 2013.
To achieve this state, we renamed the following:
renamed: 2004/hibachi/src/hibachi.c -> 2004/hibachi/hibachi.c
renamed: 2012/omoikane/nyaruko.alt.c -> 2012/omoikane/omoikane.alt.c
renamed: 2012/omoikane/nyaruko.alt2.c -> 2012/omoikane/omoikane.alt2.c
renamed: 2012/omoikane/nyaruko.c -> 2012/omoikane/omoikane.c
renamed: 2012/omoikane/nyaruko.orig.c -> 2012/omoikane/omoikane.orig.c
Modified `bin/subst.entry-index.sh` to add to entry `index.html` file,
links to the `Makefile` and the _C code_ to the top navigation bar.
Changed `bin/subst.entry-index.sh` VERSION from "1.2.2 2024-02-25"
to "1.3 2024-03-02".
Moved printing the Inventory link in the top navigation bar
from `bin/subst.entry-navbar.awk` to `bin/subst.entry-index.sh`.
Changed `bin/subst.entry-navbar.awk` VERSION from "1.0.1 2024-02-23"
to "1.1 2024-03-02".
Moved printing the Inventory link in the top navigation bar
from `bin/subst.year-navbar.awk` to `bin/subst.year-index.sh`.
Changed `bin/subst.year-index.sh` VERSION from "1.0 2024-02-11"
to "1.1 2024-03-02".
Changed `bin/subst.year-navbar.awk` VERSION from "1.0 2024-02-11"
to "1.1 2024-03-02".
Added location names (both default and common) to `author.html`.
Changed `tmp/gen_author_json.sh` VERSION from "1.0 2023-06-06"
to "1.1 2024-03-04".
Added location names (both default and common) to `author.html`.
Changed `bin/gen-authors.sh` VERSION from "1.2 2024-03-09"
to "1.3 2024-03-04".
The manifest and the resulting `.entry.json` files have been changed
for `2004/hibachi` and `2012/omoikane`.
The Makefiles for `2004/hibachi` and `2012/omoikane` copy the
source file into the "previously used location". The `make clobber`
rule removes the copied source. The `.gitignore` files have been
updated accordingly.
Improved how the concept of IOCCC terms _entry_, _author_ and _submission_ are
used in markdown files.
Links to markdown files (files ending in .md) within the repo were
changed to link to HTML files (files ending in .html). Special cases
where `README.md` became `index.html` were modified accordingly.
Fixed URL for `bugs.html` in Makefile comments.
Fixed name of `bin/sgi.sh` referenced in comments in `.gitignore` files.
Links to locations within the repo are now relative. For example a
link to `/contact.html` may become `../contact.html' or '../../contact.html`
depending on the directory level of the markdown file.
Nearly all links with absolute URLs under _https://www.ioccc.org_
or `https://ioccc-src.github.io/temp-test-ioccc_ have been changed to
relative paths within the repo. Some exceptions to this (such as
referring to a GitHub repo) were preserved.
Fixed a number of inside `faq.md` and `bugs.md`.
Added HTML name tags (in the form of an _entry_id_) for each entry
referenced in `bugs.md`. Fixed links from outside of `bugs.html`
into `bugs.html` accordingly.
Where FAQ entries are referenced, a named tag is used so that if a
FAQ is ever renumbered, links outside of `faq.html` will still work.
Changed the _inventory_order_ of a compressed tarball from _300_
to _100000_. While this may have been done for the manifest,
this changed had not yet been propagated into the `.entry.json` files.
Links to web sites that were in the for <URL> are now [URL](URL).
Performed `name www` to process all of the above.
Improved format of `authors.html`. Full names are now bold.
Location codes are now links back into `location.html` and
location names (both default and common) are now italics.
Added _author_handle_ each author.
Changed `bin/gen-authors.sh` VERSION from "1.1 2024-02-25"
to "1.2 2024-03-09".
Improved format of `location.html` as location codes are now bold,
author counts in a given location are now bold, and location names
(both default and common) are now italics.
Changed `bin/gen-location.sh` VERSION from "1.0.1 2024-02-23"
to "1.1 2024-03-04".
Added italic location name after location code in entry
`index.html` files.
Changed `bin/output-index-author.sh` VERSION from "1.4.1 2024-02-23"
to "1.5 2024-03-04".
Added _Location of authors_ to the sidebar as a link to `location.html`.
TODO: While nearly all of the above mentioned changes are likely correct,
they likely introduced a few errors that need correcting.
The alt code should work for Windows, based on the author's remarks.
Format and typo check README.md file.
I believe this completes this entry's review.
As requested on GitHub: a tool that will be written, readme2index, will,
as explained:
'... will take the converted HTML from the README.md markdown and
inject it into an HTML template. Things such title, award one and
author information will be injected into the HTML page ahead of the
HTML that was converted from the README.md markdown. Without going
into details of HOW at this time, the result will be a coherent HTML
index.html page with the winner title / award, winning author
information, and important file links come from other sources and
NOT from the README.md file.
The text from the 1st award line, thru the authorship information,
and up to but not including the "## To build:" line in the README.md
file will just get in the way. Moreover authors might be tempted to
try and maintain that top of README.md text instead of working with
the author/_author_handle_.json and winner .winner.json files.
This was done with my[0] sgit(1) (https://github.com/xexyl/sgit) tool like:
sgit -o -n -e '/^## To build:/,$p' '[12][0-9][0-9][0-9]/*/README.md'
[0] Is that shameless self-promotion? I don't know but I don't care: it
is generally a very useful tool and has been used in other repos too.
Besides, I've done it many times before and it's a great example that I
will be adding to the README.md file of the tool, one I hadn't thought
of doing.
As in:
sgit -e 's/# To run/# To use/g' '*README.md'
This makes consistent the message for how to use the program. 'How to
use' was chosen because one can run a program just by doing './foo' but
that doesn't imply that's how to use it but the purpose of the section
is how to use it.
The use of the markdown trailing whitespace to indicate
line break should NOT be done when the following line is empty.
This removes such improper use of whitespace in README.md files.
Fix command in README.md for macOS:
-preview lena.ppm # On MacOS
+open -a Preview lena.ppm # On macOS
Move warning that the program does not protect against invalid input to
the top of the author's comments (seems the best place).
Format fixes.
Add to .gitignore files that are generated by suggested commands.
There were many many README.md files with the wrong heading level for
different sections. These have been changed.
To help go through the changes it should be noted I used sgit and also
here is what is changed:
The 'Try', 'To build' and 'To run' lines have two '#'s. Some had one and
others had three.
An exception is that in 1984/anonymous/README.md for the alternative
code that had three '#'s. This is not consistent yet and it might be
that only two are desired. But for now that one at least has three.
Cody Boone Ferguson