mirror/ioccc
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

check for any ASCII tabs anywhere in markdown files

Browse Source 
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.
This commit is contained in:
Landon Curt Noll committed 2024-06-24 14:52:00 -07:00
1 parent 836d5308f4
commit 51130083c4
5 files changed
+120 -71
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

Makefile
+7 -6
View File
@@ -277,7 +277,7 @@ help:
@echo @echo
@echo '# Rules for building a local copy of the IOCCC website:' @echo '# Rules for building a local copy of the IOCCC website:'
@echo @echo
@echo 'make tab_check - check for leading ASCII tabs in leading whitespace in markdown files' @echo 'make tab_check - check for ASCII tabs in markdown files'
@echo 'make genpath - form top level .top, YYYY level .year and winner .path files' @echo 'make genpath - form top level .top, YYYY level .year and winner .path files'
@echo 'make genfilelist - generate YYYY level .filelist' @echo 'make genfilelist - generate YYYY level .filelist'
@echo 'make verify_entry_files - check to be sure all files in all entries exist' @echo 'make verify_entry_files - check to be sure all files in all entries exist'
@@ -317,12 +317,13 @@ help:
# verify that there are no leading ASCII tabs in leading whitespace in markdown files # verify that there are no leading ASCII tabs in leading whitespace in markdown files
tab_check: tab_check:
@echo '=-=-=-=-= IOCCC begin make $@ =-=-=-=-=' @echo '=-=-=-=-= IOCCC begin make $@ =-=-=-=-='
@LEADING_TAB_LIST="$$(find * \( -name NOTES -o -name tmp \) -prune -o -type f -name '*.md' -print0 | \ @TAB_LIST="$$(find * \( -name NOTES -o -name tmp -o -name markdown.md \) -prune -o \
xargs -0 grep -E -l '^ *\t')"; \ -type f -name '*.md' -print0 | \
if [[ -n $$LEADING_TAB_LIST ]]; then \ xargs -0 grep -E -l '\t')"; \
echo "$@: ERROR: leading ASCII tab found in leading whitespace in markdown file(s)" 1>&2 ; \ if [[ -n $$TAB_LIST ]]; then \
echo "$@: ERROR: ASCII tab found in markdown file(s)" 1>&2 ; \
echo "$0: Warning: list of offending markdown file(s) starts below" 1>&2 ; \ echo "$0: Warning: list of offending markdown file(s) starts below" 1>&2 ; \
echo "$${LEADING_TAB_LIST}" 1>&2 ; \ echo "$${TAB_LIST}" 1>&2 ; \
echo "$0: Warning: list of offending markdown file(s) ends above" 1>&2 ; \ echo "$0: Warning: list of offending markdown file(s) ends above" 1>&2 ; \
exit 1; \ exit 1; \
fi fi
markdown.html
+44 -31
View File
@@ -415,8 +415,8 @@ for the given page URL.</p>
# This will work # This will work
&lt;/div&gt;</code></pre> &lt;/div&gt;</code></pre>
<p>While some browsers will still recognize the HTML construct <code>&lt;a name="string"&gt;...&lt;/a&gt;</code>, it is possible they might NOT in the future.</p> <p>While some browsers will still recognize the HTML construct <code>&lt;a name="string"&gt;...&lt;/a&gt;</code>, it is possible they might NOT in the future.</p>
<h2 id="please-do-not-use-the-strike-or-s-html-element">Please do NOT use the <code>&lt;strike&gt;</code> or <code>&lt;s&gt;</code> HTML element</h2> <h2 id="please-do-not-use-the-strike-nor-the-s-html-element">Please do NOT use the <code>&lt;strike&gt;</code> nor the <code>&lt;s&gt;</code> HTML element</h2>
<p>Please NOT use the obsolete <code>&lt;strike&gt;</code> or <code>&lt;s&gt;</code> (<del><em>strikeout</em></del>) HTML elements:</p> <p>Please NOT use the obsolete <code>&lt;strike&gt;</code> nor the obsolete <code>&lt;s&gt;</code> (<del><em>strikeout</em></del>) HTML elements:</p>
<pre><code> &lt;strike&gt;...&lt;/strike&gt; &lt;=== no thank you <pre><code> &lt;strike&gt;...&lt;/strike&gt; &lt;=== no thank you
&lt;s&gt;...&lt;/s&gt; &lt;=== no thank you</code></pre> &lt;s&gt;...&lt;/s&gt; &lt;=== no thank you</code></pre>
<p>Use instead:</p> <p>Use instead:</p>
@@ -430,45 +430,58 @@ for the given page URL.</p>
<p>Please do <strong>NOT</strong> use the obsolete <code>&lt;tt&gt;</code> (<span style="font-family: monospace;"><em>teletype</em></span>) HTML element:</p> <p>Please do <strong>NOT</strong> use the obsolete <code>&lt;tt&gt;</code> (<span style="font-family: monospace;"><em>teletype</em></span>) HTML element:</p>
<pre><code> &lt;tt&gt;The obsolete tt element is obsolete&lt;/tt&gt; &lt;=== no thank you</code></pre> <pre><code> &lt;tt&gt;The obsolete tt element is obsolete&lt;/tt&gt; &lt;=== no thank you</code></pre>
<p>Instead use either a monospaced span:</p> <p>Instead use either a monospaced span:</p>
<pre><code> &lt;span style=&quot;font-family: monospace;&quot;&gt;Use of monospaced font is one option&lt;/span&gt;</code></pre> <pre><code> &lt;span style=&quot;font-family: monospace;&quot;&gt;Use of a monospaced font
<p>Or better and easier still, use an inline markdown code block:</p> is one option,
<pre><code> `inline markdown code block is easier and much better`</code></pre> however ... &lt;/span&gt;</code></pre>
<p>We recommend using the inline markdown code block method instead:</p>
<pre><code> Using the `inline markdown code block` is easier and is `preferred`.</code></pre>
<h2 id="please-do-not-use-unindented-code-blocks">Please do NOT use unindented code blocks</h2> <h2 id="please-do-not-use-unindented-code-blocks">Please do NOT use unindented code blocks</h2>
<p>Please do <strong>NOT</strong> start code blocks at the left-hand edge.</p> <p>Please do <strong>NOT</strong> start code blocks at the left-hand edge.</p>
<pre><code>``` <p>For example:</p>
This code block is NOT indented &lt;=== no thank you <pre><code>``` &lt;!---sh--&gt;
echo &quot;This code block is NOT indented\&quot; &lt;=== no thank you
```</code></pre> ```</code></pre>
<p>We request that you indent the code block by 4 ASCII spaces</p> <p>We request that you indent the code block by multiples of 4 ASCII spaces:</p>
<pre><code>``` <pre><code>``` &lt;!---sh--&gt;
This code block echo &quot;This code block is intended by mutiples of 4 spaces&quot;
is indented 4 spaces
# The top level starts with a 4 ASCII space indent.
#
# Only indent with multiples of 4 ASCII spaces.
# 2nd level indent needs 8 ASCII spaces (no tabs).
# 3rd level indent needs 12 ASCII spaces (no tabs).
# etc.
```</code></pre> ```</code></pre>
<p>One exception is where change bars are needed, such as <p>Moreover:</p>
those used in <code>next/rules.md</code> and in <code>next/guidelines.md</code>.</p>
<p>For example, <code>next/guidelines.md</code> uses this markdown code block:</p>
<pre><code>``` <pre><code>```
main() { The same thing applies to any markdown block surrounded by ``` lines.
| void please_do_not_submit_this() {
| printf(&quot;The machine that goes BING!\n&quot;);
}
| please_do_not_submit_this();
}
```</code></pre> ```</code></pre>
<h2 id="please-do-not-use-ascii-tabs-to-indent-text">Please do NOT use ASCII tabs to indent text</h2> <p>Please do <strong>NOT</strong> indent using ASCII tab characters in markdown files.</p>
<p>When indenting a code block in markdown, indent 4 ASCII spaces per level. <h2 id="please-do-not-use-ascii-tabs-in-markdown-files">Please do NOT use ASCII tabs in markdown files</h2>
If you need to indent 2 or more levels, use multiples of 4 ASCII spaces. <p>While we have nothing against the ASCII tab character in general,
Please do <strong>NOT</strong> indent with ASCII tabs!</p> we have discovered that ASCII tab characters create problems when
used as part of the leading whitespace within a markdown file.</p>
<p>If you need to indent 2 or more levels, use multiples of 4 ASCII
spaces. Please do <strong>NOT</strong> indent with ASCII tabs, <strong>NOR</strong> use any
ASCII tab characters anywhere inside a markdown file:</p>
<p>For example:</p> <p>For example:</p>
<pre><code>``` <pre><code>```
Please do **NOT** indent with ASCII tabs. &lt;=== no thank you Please do **NOT** use ASCII tabs in markdown files. &lt;=== no thank you
Please do **NOT** indent markdown with ASCII tabs. &lt;=== no thank you
The top level starts with a 4 ASCII space indent. We don&#39;t mind tabs in general, &lt;=== no thank you
We just ask that you NOT use them in markdown files.
Only indent with multiples of 4 ASCII spaces.
2nd level indent needs 8 ASCII spaces (no tabs).
3rd level indent needs 12 ASCII spaces (no tabs).
etc.
```</code></pre> ```</code></pre>
<p>And to clarify, we are only talking about markdown files,
not C code nor any other non-markdown content:</p>
<pre><code> printf(&quot;Is is fine to use tabs in Obfucated C code.\n&quot;);
/* if you wish */
// We ask that you to NOT use ASCII tab characters in your remarks.md writeup,
// nor in any other markdown files within your entry, please.</code></pre>
<p><strong>NOTE</strong>: Again, you are <strong>perfectly welcome</strong> to use ASCII tab characters in
your C code and other non-markdown files. We simply ask that you <strong>NOT</strong> use any
ASCII tab characters in markdown files.</p>
<h2 id="please-do-not-specify-a-language-for-a-code-block">Please do NOT specify a language for a code block</h2> <h2 id="please-do-not-specify-a-language-for-a-code-block">Please do NOT specify a language for a code block</h2>
<p>We request that (fenced) markdown code blocks <strong>NOT</strong> specify a language.</p> <p>We request that (fenced) markdown code blocks <strong>NOT</strong> specify a language.</p>
<p>For example:</p> <p>For example:</p>
markdown.md
+52 -34
View File
@@ -61,9 +61,9 @@ While some browsers will still recognize the HTML construct `<a
name="string">...</a>`, it is possible they might NOT in the future. name="string">...</a>`, it is possible they might NOT in the future.
## Please do NOT use the `<strike>` or `<s>` HTML element ## Please do NOT use the `<strike>` nor the `<s>` HTML element
Please NOT use the obsolete `<strike>` or `<s>` (<del>_strikeout_</del>) HTML elements: Please NOT use the obsolete `<strike>` nor the obsolete `<s>` (<del>_strikeout_</del>) HTML elements:
``` ```
<strike>...</strike> <=== no thank you <strike>...</strike> <=== no thank you
@@ -103,13 +103,15 @@ Please do **NOT** use the obsolete `<tt>` (<span style="font-family: monospace;"
Instead use either a monospaced span: Instead use either a monospaced span:
``` ```
<span style="font-family: monospace;">Use of monospaced font is one option</span> <span style="font-family: monospace;">Use of a monospaced font
is one option,
however ... </span>
``` ```
Or better and easier still, use an inline markdown code block: We recommend using the inline markdown code block method instead:
``` ```
`inline markdown code block is easier and much better` Using the `inline markdown code block` is easier and is `preferred`.
``` ```
@@ -117,61 +119,77 @@ Or better and easier still, use an inline markdown code block:
Please do **NOT** start code blocks at the left-hand edge. Please do **NOT** start code blocks at the left-hand edge.
For example:
```` ````
``` ``` <%%NO_COMMENT%%!---sh-->
This code block is NOT indented <=== no thank you echo "This code block is NOT indented\" <=== no thank you
``` ```
```` ````
We request that you indent the code block by multiples of 4 ASCII spaces:
We request that you indent the code block by 4 ASCII spaces
```` ````
``` ``` <%%NO_COMMENT%%!---sh-->
This code block echo "This code block is intended by mutiples of 4 spaces"
is indented 4 spaces
# The top level starts with a 4 ASCII space indent.
#
# Only indent with multiples of 4 ASCII spaces.
# 2nd level indent needs 8 ASCII spaces (no tabs).
# 3rd level indent needs 12 ASCII spaces (no tabs).
# etc.
``` ```
```` ````
Moreover:
One exception is where change bars are needed, such as
those used in `next/rules.md` and in `next/guidelines.md`.
For example, `next/guidelines.md` uses this markdown code block:
```` ````
``` ```
main() { The same thing applies to any markdown block surrounded by ``` lines.
| void please_do_not_submit_this() {
| printf("The machine that goes BING!\n");
}
| please_do_not_submit_this();
}
``` ```
```` ````
Please do **NOT** indent using ASCII tab characters in markdown files.
## Please do NOT use ASCII tabs to indent text
When indenting a code block in markdown, indent 4 ASCII spaces per level. ## Please do NOT use ASCII tabs in markdown files
If you need to indent 2 or more levels, use multiples of 4 ASCII spaces.
Please do **NOT** indent with ASCII tabs! While we have nothing against the ASCII tab character in general,
we have discovered that ASCII tab characters create problems when
used as part of the leading whitespace within a markdown file.
If you need to indent 2 or more levels, use multiples of 4 ASCII
spaces. Please do **NOT** indent with ASCII tabs, **NOR** use any
ASCII tab characters anywhere inside a markdown file:
For example: For example:
```` ````
``` ```
Please do **NOT** indent with ASCII tabs. <=== no thank you Please do **NOT** use ASCII tabs in markdown files. <=== no thank you
Please do **NOT** indent markdown with ASCII tabs. <=== no thank you
The top level starts with a 4 ASCII space indent. We don't mind tabs in general, <=== no thank you
We just ask that you NOT use them in markdown files.
Only indent with multiples of 4 ASCII spaces.
2nd level indent needs 8 ASCII spaces (no tabs).
3rd level indent needs 12 ASCII spaces (no tabs).
etc.
``` ```
```` ````
And to clarify, we are only talking about markdown files,
not C code nor any other non-markdown content:
````
printf("Is is fine to use tabs in Obfucated C code.\n");
/* if you wish */
// We ask that you to NOT use ASCII tab characters in your remarks.md writeup,
// nor in any other markdown files within your entry, please.
````
**NOTE**: Again, you are **perfectly welcome** to use ASCII tab characters in
your C code and other non-markdown files. We simply ask that you **NOT** use any
ASCII tab characters in markdown files.
## Please do NOT specify a language for a code block ## Please do NOT specify a language for a code block
next/guidelines.html
+5
View File
@@ -933,6 +933,11 @@ and state:</p>
given enough time and memory. If the value is not a proper integer, the program given enough time and memory. If the value is not a proper integer, the program
will insult a fish named Eric, even if such a fish does not exist.</p> will insult a fish named Eric, even if such a fish does not exist.</p>
</blockquote> </blockquote>
<p><strong><code>|</code></strong> We <strong>DISLIKE</strong> the use of use ASCII tab characters in markdown files, such as in the required <code>remarks.md</code> file.</p>
<p><strong><code>|</code></strong> We don’t mind the use ASCII tab characters in your C code. Feel free to use ASCII tab characters if that suits your obfuscation needs. If is perfectly <strong>OK</strong> to use tab characters elsewhere in your submission, just not in markdown files as this tends complicate and annoys us when be comes to rendering your markdown content.</p>
<p><strong><code>|</code></strong> If you do use ASCII tab characters in your non-markdown files, be aware that some people may use tab stop that is different than the common 8 character tab stop.</p>
<p><strong><code>|</code></strong> We enjoy a reading <code>remarks.md</code> files, especially if they contain useful, informative, and even humorous content about your entry.</p>
<p><strong><code>|</code></strong> We <strong>RECOMMEND</strong> you put a reasonable amount effort into the content of the <code>remarks.md</code> file: it is a required for for a reason. :-)</p>
<h1 id="abusing-the-rules">ABUSING THE RULES:</h1> <h1 id="abusing-the-rules">ABUSING THE RULES:</h1>
<p>Legal abuse of the <a href="rules.html">IOCCC rules</a> is somewhat encouraged. Legal rule abuse <p>Legal abuse of the <a href="rules.html">IOCCC rules</a> is somewhat encouraged. Legal rule abuse
may involve, but is not limited to, doing things that are technically allowed by may involve, but is not limited to, doing things that are technically allowed by
next/guidelines.md
+12
View File
@@ -752,6 +752,18 @@ and state:
given enough time and memory. If the value is not a proper integer, the program given enough time and memory. If the value is not a proper integer, the program
will insult a fish named Eric, even if such a fish does not exist. will insult a fish named Eric, even if such a fish does not exist.
**`|`** We **DISLIKE** the use of use ASCII tab characters in markdown files, such as in the required `remarks.md` file.
**`|`** We don't mind the use ASCII tab characters in your C code. Feel free to use ASCII tab characters if that suits your obfuscation needs. If is perfectly **OK** to use tab characters elsewhere in your submission, just not in markdown files as this tends complicate and annoys us when be comes to rendering your markdown content.
**`|`** If you do use ASCII tab characters in your non-markdown files, be aware that some people may use tab stop that is different than the common 8 character tab stop.
**`|`** We enjoy a reading `remarks.md` files, especially if they contain useful, informative, and even humorous content about your entry.
**`|`** We **RECOMMEND** you put a reasonable amount effort into the content of the `remarks.md` file: it is a required for for a reason. :-)
# ABUSING THE RULES: # ABUSING THE RULES: