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.
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.
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.
Rather than have a literal vertical bar (|) for lines that indicate a
change from the last contest, it is now a CSS class which has a solid
black left border of 4 pixels. This not only makes it easier to see but
it fixes some formatting issues too (see below for tests).
This means that if a change mark is needed one can do:
<p class="leftbar">
...
</p>
A tip for vim users: in the .vimrc file add the following line
(temporarily or otherwise):
abbr leftbar <p class="leftbar">
Then you only need to type:
leftbar
and it will automatically add the proper block.
As for testing how this looks I have checked it with Safari with:
- an iPhone 14 Pro Max
- an iPhone 8 Plus
- a MacBook Pro 16 inch (both at full width and smallest width)
- an iPad Pro 11 inch 4th generation in both portrait and landscape
orientations
An important point that one needs to remember when using this CSS class
in lists is that one cannot do:
<p class="leftbar">
* foo
</p>
<p class="leftbar">
* bar
</p>
but rather do:
* <p class="leftbar">foo</p>
* <p class="leftbar">bar</p>
A problem was discovered in blockquotes for really long text, in
particular in the guidelines: 2305567963945518424753102147331756070. The
problem was that the number flowed outside the border. That should no
longer happen. Below is what should happen instead, though it's hard to
be sure how it will look in every case.
In Safari on a 16" MacBook Pro with Safari all across the screen it is
not a problem but shorter text will be in a smaller box (this means
the green box will vary in size depending on what is in it but this does
not seem to be a big problem).
With Safari in an old iPhone 8 Plus the box can go a bit further beyond
the screen width but text does not go beyond the boundary and one can
scroll left/right at need.
With Safari in an iPhone 14 Pro Max there is currently a cache issue but
earlier (when playing with different options) it seemed to fit and in
Simulator (in macOS) it looks good. However in Simulator earlier it was
fine even when the iPhone 14 Pro Max was not.
In responsive mode in Safari with a small width (400px) it is the same
result as the iPhone 8 Plus.
Finally with Safari in macOS with the window decreased in width it is
fine but it already was fine because it doesn't go to the size of a
phone (though it has helped fix problems with phones).
I have changed the font-style to normal (was italic) in blockquotes also
as this way italics can show up specially if requested.
The guidelines had some line breaks in the blockquotes that were
problematic; these have been removed as they are not necessary and it
did not look good either with smaller width screens.
More testing will likely be useful but it should be a lot better now.
The new FAQ is about how to report bugs in mkiocccentry tools. The rules
and guidelines link to this FAQ.
The rules and guidelines have been corrected and clarified in a number
of ways.
This is more for those who are interested in how they can run each step
of the mkiocccentry tool as well as how to make it easier to edit a
submission tarball.
Although it looks okay (the rendered html) a more thorough review will
have to be done, tomorrow if possible.
A typo that was missed because I did not look at that part of the file
was 'quidelines' instead of 'guidelines'. This has been fixed in inc/
and next/.
The guidelines had many fixes and where necessary updates (about new
tools for instance) plus some fun for people to discover.
The FAQ was slightly updated as well for the guidelines.
Harmonized and improve the headers that are prepended
to the rules and guidelines given the IOCCC state.
Attempted to make the headers that are prepended
to the rules and guidelines more consistent.
Make reference to, where applicable, FAQs
about feedback and questions in those headers.
Perform `make www` to perform the above and test under macOS.
Unless one is mentioned one will not get a push notification so one
should refresh the IOCCC mastodon feed every so often. This is at the
top of the file, though, and seemingly part of a file in inc/ so this
might have to be done differently than how this change was done.
There were numerous things that had to be fixed and there will likely
have to be some discussion as well.
Some formatting fixes and additional links were also added.
This commit involves some updates to the FAQ and while I was at it I
fixed some references of 'entry'/'entries' to 'submission'/'submissions'
(those that should not be 'entry' or 'entries').
Fixed a number of typos, inconsistencies, and problems with the
rules and guidelines.
Improved how the closed version of the rules and guidelines declare
themselves at the top of the markdown and HTML file.
Changed `next/rules.md` VERSION from "2024-06-29-v28"
to "28.1 2024-06-29" in order to be more consistent
with IOCCC tool version format.
Changed `next/guidelines.md` VERSION from "2024-06-29-v28"
to "28.1 2024-06-29" in order to be more consistent
with IOCCC tool version format.
Make a minor format fix to `faq.md`.
Performed `make status` and `make www` to test the above umder macOS.
Added a `#weverything` div tag to the FAQ.
Expanded and improved(?) a number of rules and guidelines.
In particular, the consequences of the new mkiocccentry
repo have been put into the rules and guidelines.
This is a checkpoint from which we can review,
edit and improve.
The way that markdown quotes are currently formatted (with a gray
vertical line) looks too much like a change bar. The change bar
is an important tool to help notice new and changed rules and
guidelines. Unfortunately the current quotes style looks too much
like a change bar, so we use markdown quotes **ONLY** for literal
quotes (such as from Mark Twain) in the `guidelines.md` file.
Clarified and simplified the request to not use ASCII tabs within
markdown file content.
Added _guidelines_ to `next/guidelines.md` about not using ASCII
tab characters in markdown files while stating that is just fine
to use ASCII tabs in non-markdown files and C code.
The `make tab_check` rule now simply checks for ASCII tabs within
markdown files, except `markdown.md` where they are required to
serve as examples of what not to do.
Perform `make quick_www` to perform the above and test under macOS.
Perform `make www` to perform the above and test under macOS.
There were several places where a code block was used for text that is
more like a quote (and in one case it is a quote) and these have been
converted to a blockquote.
A few links were added instead of having the link in a code block.
In a case where a paragraph was split with blank lines in between each
line (with the '|' marker at each line) I added a <br> to it so that it
looked more natural.
With the recent changes to this file and the rules file more checks have
to be made as well.
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 '{', '}' and other chars that are referred to are now in code blocks
(surrounded by single quotes) to help make them stand out better. The
single quotes are there as depending on the person's perception (or if
they're tired or ...) the colour difference might not be enough (in fact
it's barely enough for me at this point and others are more colour blind
than I am). The block quote colour is being experimented with still,
too, so that is another reason to have the 's.
Added make gen_next rule to Makefile which builds next/index.html from
next/README.md, next/rules.html from next/rules.md and
next/guidelines.html from next/guidelines.md. The make help rule was
updated for this.
Each individual IOCCC rule has its own div tag.
References to a specific IOCCC rule is now a link.
We now use the term **IOCCC rules** more consistency when
referring to the rules.
We now use the term **IOCCC guidelines** more consistency when
referring to the guidelines.
In the **IOCCC guidelines**, we use _guideline_ when
referring to a general guideline.
Updated **IOCCC rules** and **IOCCC guidelines** to 2024-06-23-v28.
Added guidelines about the recent Rule 2a changes.
Improved to order of the guidelines related to Rule 2.
Added a ">" formatted quote about the iocccsize summary to the IOCCC guidelines.
Perform `make www` to perform the above and test under macOS.
Landon Curt Noll