Changed `markdown.md` VERSION from "28.1 2025-02-02"
to "28.2 2025-04-28".
Updated sitemap.
Tested the above via `make www gen_status gen_sitemap timestamp` on macOS.
Fixed vimrc typo relating to noexpandtab in `markdown.md`.
Added missing top level and 2nd level markdown and HTML files
to the sitemap.
Changed `bin/gen-sitemap.sh` VERSION from "2.0.0 2025-03-13"
to "2.0.1 2025-04-28".
Updated sitemap.
Tested the above via `make www gen_status gen_sitemap timestamp` on macOS.
Renamed some FAQs (typos and/or other things).
Fix a number of typos in various files (including markdown format
errors).
Rules and guidelines should be relatively good although as there is a
lot to get through and not much time left maybe I missed something (I
also kind of cheated doing the final checks with the guidelines rather
than going through them all again).
The next/try.sh and next/try.alt.sh scripts have had updates as well and
the next/Makefile.example was modified too.
The index.html page now has an anchor for goals of the contest so that
the goals in the rules could simply link to it in index.html.
Although some text had to be added (and some corrected) a reasonable
amount of text was also removed as it was elsewhere or was extraneous in
some way.
In the case of html void elements (not having the trailing '/') I have
merged the 'no thank you' and 'instead use'. At the same time I fixed a
typo where one 'no thank you' referred to the wrong 'instead use' (in
particular it was '<hr/>' -> '<br>' rather than '<hr/>' -> '<hr>').
The next/remarks.example.md filename is kind of a misnomer but it was
named this way to match Makefile.example. It has brief instructions
along with a link to the FAQ about what one should put in their
remarks.md file (and the FAQ links to the new file as a starting point
as it has instructions).
The markdown guidelines were updated to note that if one does use
sections in remarks.md file they should start out at heading level 3
(###) and for each subsection increment it by one (up to level 6).
The menu in all html pages for the FAQ was fixed to link to the step 0
(of how to enter the contest) and also it was renamed ('Enter the
IOCCC').
I also went through the most important sections of the FAQ (how to
enter and the mkiocccentry related questions) and checked the
register.html, pw-change.html and submit.html pages. It is possible I
have missed something but I think it's in pretty good shape nonetheless.
Added a new `next/submit.html` to move the "how to submit" form "in-line"
of the top FAQ entry into a new page managed by `next/submit.md`.
Thus, `next/submit.html` is a parallel to `next/register.html`
and `next/submit.md` is a parallel to `next/register.md`.
Changed the FAQ "faq.html#submit" and into "faq.html#enter".
Added individual tags for the steps in FAQ0.0.
Moved "faq.html#register" down to FAQ 0.0 step 2.
Added "faq.html#submit" for FAQ 0.0 step 5,
however elsewhere often "next/submit.html" is used.
Changed references for "faq.html#upload" to "next/submit.html".
We made a number of changes to the following markdown files to reflect the above:
- `about.md`
- `faq.md`
- `index.md`
- `markdown.md`
- `next/README.md`
- `next/README.md`
- `next/guidelines.md`
- `next/register.md`
- `next/rules.md`
- `nojs-menu.md`
- `status.md`
as well as these files:
- `bin/gen-top-html.sh`
- `bin/md2html.cfg`
and added:
- `next/submit.html`
- `next/submit.md`
Perform `make www` and `make gen_status` to perform the above and test under macOS.
TODO: Add images about the mailing list to `next/register.md`. See the line:
```
XXX - **put images and other details about joining the mailing list here** - XXX
```
The sections have been modified a fair amount. The Entries menu has been
extended to have: Fixing entries, Updating author info, Thanks for the
help. The first two were moved from FAQ and the last one from About.
The rationale for these, in order: entries and authors have to do with
entries and most of the help involves entries. It also has to do with
website but in 'about' it does not seem the right place, unless maybe it
is renamed to 'Credits' or something (I am not suggesting this one way
or the other). This one is debatable but that was the rationale.
The Status menu has been extended to have: Markdown guidelines and
Security policy. The rationale is that the markdown guidelines are part
of contest guidelines and the security policy is about the status of the
entries and how if there are any security problems they will not be
addressed (instead of about the IOCCC).
The FAQ was extended to have: Compiling entries, Running entries, How to
help. The reason to not have compiling and running entries under Entries
is because this is 'how to' and also the menu was too long. How to help
seems like a good idea under FAQ too (was in About).
About was extended to have the new 'about.html' page (from about.md).
This is a rare case where a new file is useful as it fits under 'About'.
The menu now is: Home page, About the IOCCC, The Judges, Contact us. I
was pondering the 'About [the IOCCC]' at the top and also naming it
'About us' but it seemed like a link to index.html was necessary and as
for 'about us' it seemed less clear as to whether it was about the
judges or the contest itself. The FAQ has been updated slightly for
this.
After further inspection the bin/index.html and the inc/index.html links
were removed from the about section.
With these changes, renaming an item or slight reordering
notwithstanding, I believe that #2006 is probably in good shape.
Amongst the changes here is that we do not need to have the hex or html
code (numbers) for open and close parentheses (in links) as there are
names. '(' is & followed by lpar; and the ')' is the same but 'rpar;'
instead. This makes it easier to remember and type and it generates the
same html as well (they are all valid). Now the markdown files are
consistent in this (in some cases hex was used and in others the html
code).
Although many markdown files were updated no html files needed to be
updated as it generates the same html. Even so I ran the appropriate
rules to do so just to verify this.
Added `make markdown` to the top level `Makefile` to just build
the `markdown.html` file.
Sorted make rules that build individual HTML files.
Performed `make gen_top_html` to accomplish the above and to test under macOS.
Improved wording of some of the titles.
Added div ids to each guideline so that we can link directly to them if
necessary.
The code block examples now specify a language so that when language
highlighting is available it will show up better. I added this for those
that are not wanted and those that are in the hopes it will stand out
more.
I added a guideline that for italics one should use underscores (_) as
using single asterisks is known to cause some parsers problems (and this
goes more so, perhaps, when it is bold italic text which would otherwise
be three asterisks in a row). I first became aware of this from a
document on some markdown parsers and it seems like a good idea to note.
Added that it is preferable and easier to use markdown links if possible
(along the lines of how it's easier and preferable to use inline code
blocks instead of spans). This would also help with consistency.
Typo fixes (some in code blocks, perhaps some outside as well).
For tabs/spaces discussion I added a tip for vim users. Maybe this
should be in the FAQ instead but I am not sure.
Move rule about not including literal parentheses in markdown links to
right below the rule about not ending markdown links with '))'.
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.
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.
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.
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.
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
Something that was not noted in the other commit that touched this file
is that because this is markdown which renders to html I changed the
comments in the form of:
<=== no thank you
to
<!-- no thank you -->
This was not strictly necessary but and for non html it might not even
make sense except that it is still rendered to html and in most cases
(if not all) it is html. This was done for the rest of the file now too.
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.
We have fixed cases where markdown code blocks were not properly intended.
Updated `markdown.md` to discuss how markdown code blocks should be indented
and how blank lines should follow a markdown code block.
We used this shell script to find problematic code blocks:
```sh
find . -name '*.md' ! -name markdown.md -print | xargs pcregrep -M '^``.*\n[^|`\n \t]'
```
Ran `make www` to perform the above.
Added `bin/find-missing-links.sh` tool to check for
markdown links to missing local files.
Regarding the missing link tool:
```
Here be extended regular expression magic dragons! :-)
```
Added `make find_missing_links` to the top level Makefile.
Added `make find_missing_links` to `make www` and `make quick_www`.
Ran `make www` to perform the above.
TODO: Fix markdown links to missing local files.
We fix more markdown links in markdown files that refer to files
internally to the web site.
Added tmp tools to find and print various markdown links:
* `tmp/md-links.sh` - print all markdown links
* `tmp/md-token-links.sh` - print all markdown links that start with a **%%TOKEN%%**
* `tmp/md-local-links.sh` - print all markdown links to a local file
* `tmp/md-link-paths.sh` - print local file paths referenced in markdown links
Fixed a number of markdown formatting problems with `thanks-for-help.md`.
Fixed markdown links to files in `thanks-for-help.md`. Improved
heading levels in `thanks-for-help.md`, and made entry sections consistent.
Changed all markdown links that end in "))" to end in a better way.
Explained in `markdown.md` why we are avoiding markdown links that
end in "))".
Ran `make www` to perform the above.
TODO: Fix stuff we broke by mistake doing the above.
TODO: Fix more broken markdown links.
Add `markdown.md` which generates `markdown.html`
to document IOCCC markdown best practices.
Changed `bin/gen-top-html.sh` VERSION from to "1.4.1 2024-04-16"
to "1.4.2 2024-04-21".
Added FAQ 0.6 about IOCCC mark requirements.
Run `make gen_top_html timestamp` to perform the above.
Landon Curt Noll