improve markdown references to FAQ entries

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 commit is contained in:
Landon Curt Noll committed 2024-07-17 03:11:19 -07:00
1 parent d852734d98
commit 0bc6c3e413
104 files changed
+1051 -687

No files matched your search

+5 -4
View File
@@ -392,8 +392,9 @@
<h3 id="please-follow-the-ioccc-on-mastodon">Please follow the <a href="https://fosstodon.org/@ioccc">IOCCC on Mastodon</a></h3>
<p>We use Mastodon to make minor announcements, in addition to announcing
major events such as the opening of a new IOCCC, or who won.</p>
<p>See “<a href="faq.html#try_mastodon">FAQ 6.12: What is Mastodon and why does IOCCC use it?</a>” for more
information on Mastodon.</p>
<p>See
FAQ on “<a href="faq.html#try_mastodon">Mastodon</a>”
for more information on Mastodon.</p>
<h1 id="news">News</h1>
<h2 id="section">2024-06-08</h2>
<p>We continue to make good progress on the
@@ -403,7 +404,7 @@ via the <a href="https://github.com/ioccc-src/temp-test-ioccc">temp-test-ioccc</
files</a> has
been checked for broken links which leaves two longer files to go. These two
files are the <a href="bugs.html">bugs.html</a>
file and the <a href="faq.html">FAQ</a>.</p>
file and the “<a href="faq.html">IOCCC FAQ</a>”.</p>
<p>However, where it was thought that those two files would be looked at before the
other html files, it has been decided that they will be done after the other
files as it is very possible that some things in these two files will have to be
@@ -419,7 +420,7 @@ June 2024</em> have been checked for invalid links so that only new news updates
will have to be checked.</p>
<p>Once those are done the html files of all the entries will be looked at. As
those are being reviewed it the <a href="bugs.html">bugs.html</a> might very well be
updated and the <a href="faq.html">FAQ</a> might be as well. This is why, as noted above,
updated and the “<a href="faq.html">IOCCC FAQ</a>” might be as well. This is why, as noted above,
we have decided to review these files last, in order to save time and effort in
not having to look at them more than once on a whole, other than possible
entries that have to be added at the end, like the example below.</p>