From 51130083c4a701e1ab30b9d7b8deb6748097ca95 Mon Sep 17 00:00:00 2001 From: Landon Curt Noll Date: Mon, 24 Jun 2024 14:52:00 -0700 Subject: [PATCH] check for any ASCII tabs anywhere in markdown files 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. --- Makefile | 13 +++---- markdown.html | 75 ++++++++++++++++++++++---------------- markdown.md | 86 ++++++++++++++++++++++++++------------------ next/guidelines.html | 5 +++ next/guidelines.md | 12 +++++++ 5 files changed, 120 insertions(+), 71 deletions(-) diff --git a/Makefile b/Makefile index ec1f8a3c2..a0951218c 100644 --- a/Makefile +++ b/Makefile @@ -277,7 +277,7 @@ help: @echo @echo '# Rules for building a local copy of the IOCCC website:' @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 genfilelist - generate YYYY level .filelist' @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 tab_check: @echo '=-=-=-=-= IOCCC begin make $@ =-=-=-=-=' - @LEADING_TAB_LIST="$$(find * \( -name NOTES -o -name tmp \) -prune -o -type f -name '*.md' -print0 | \ - xargs -0 grep -E -l '^ *\t')"; \ - if [[ -n $$LEADING_TAB_LIST ]]; then \ - echo "$@: ERROR: leading ASCII tab found in leading whitespace in markdown file(s)" 1>&2 ; \ + @TAB_LIST="$$(find * \( -name NOTES -o -name tmp -o -name markdown.md \) -prune -o \ + -type f -name '*.md' -print0 | \ + xargs -0 grep -E -l '\t')"; \ + 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 "$${LEADING_TAB_LIST}" 1>&2 ; \ + echo "$${TAB_LIST}" 1>&2 ; \ echo "$0: Warning: list of offending markdown file(s) ends above" 1>&2 ; \ exit 1; \ fi diff --git a/markdown.html b/markdown.html index a2e5ca1ea..8ebd8fc38 100644 --- a/markdown.html +++ b/markdown.html @@ -415,8 +415,8 @@ for the given page URL.

# This will work </div>

While some browsers will still recognize the HTML construct <a name="string">...</a>, it is possible they might NOT in the future.

-

Please do NOT use the <strike> or <s> HTML element

-

Please NOT use the obsolete <strike> or <s> (strikeout) HTML elements:

+

Please do NOT use the <strike> nor the <s> HTML element

+

Please NOT use the obsolete <strike> nor the obsolete <s> (strikeout) HTML elements:

    <strike>...</strike>                                      <=== no thank you
     <s>...</s>                                                <=== no thank you

Use instead:

@@ -430,45 +430,58 @@ for the given page URL.

Please do NOT use the obsolete <tt> (teletype) HTML element:

    <tt>The obsolete tt element is obsolete</tt>              <=== no thank you

Instead use either a monospaced span:

-
    <span style="font-family: monospace;">Use of monospaced font is one option</span>
-

Or better and easier still, use an inline markdown code block:

-
    `inline markdown code block is easier and much better`
+
    <span style="font-family: monospace;">Use of a monospaced font
+                                          is one option,
+                                          however ... </span>
+

We recommend using the inline markdown code block method instead:

+
    Using the `inline markdown code block` is easier and is `preferred`.

Please do NOT use unindented code blocks

Please do NOT start code blocks at the left-hand edge.

-
```
-This code block is NOT indented                                 <=== no thank you
+
For example:

+
``` <!---sh-->
+echo "This code block is NOT indented\"                       <=== no thank you
 ```

-
We request that you indent the code block by 4 ASCII spaces

-
```
-    This code block
-    is indented 4 spaces
+
We request that you indent the code block by multiples of 4 ASCII spaces:

+
``` <!---sh-->
+    echo "This code block is intended by mutiples of 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.
 ```

-
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:

+
Moreover:

 
```
-    main() {
-|       void please_do_not_submit_this() {
-|           printf("The machine that goes BING!\n");
-        }
-|       please_do_not_submit_this();
-    }
+    The same thing applies to any markdown block surrounded by ``` lines.
 ```

-
Please do NOT use ASCII tabs to indent text

-
When indenting a code block in markdown, indent 4 ASCII spaces per level.
-If you need to indent 2 or more levels, use multiples of 4 ASCII spaces.
-Please do NOT indent with ASCII tabs!

+
Please do NOT indent using ASCII tab characters in markdown files.

+
Please do NOT use ASCII tabs in markdown files

+
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:

 
```
-        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.
-
-    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.
+        We      don't   mind    tabs    in      general,        <=== no thank you
+     We just ask that you NOT use them in markdown files.
 ```

+
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

 
We request that (fenced) markdown code blocks NOT specify a language.

 
For example:

diff --git a/markdown.md b/markdown.md
index 44bb56bb2..60ff0f2a8 100644
--- a/markdown.md
+++ b/markdown.md
@@ -61,9 +61,9 @@ While some browsers will still recognize the HTML construct `...`, it is possible they might NOT in the future.
 
 
-## Please do NOT use the `` or `` HTML element
+## Please do NOT use the `` nor the `` HTML element
 
-Please NOT use the obsolete `` or `` (_strikeout_) HTML elements:
+Please NOT use the obsolete `` nor the obsolete `` (_strikeout_) HTML elements:
 
 ```
     ...                                      <=== no thank you
@@ -103,13 +103,15 @@ Please do **NOT** use the obsolete `` (Use of monospaced font is one option
+    Use of a monospaced font
+                                          is one option,
+                                          however ... 
 ```
 
-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.
 
+For example:
+
 ````
-```
-This code block is NOT indented                                 <=== no thank you
+``` <%%NO_COMMENT%%!---sh-->
+echo "This code block is NOT indented\"                       <=== no thank you
 ```
 ````
 
-
-We request that you indent the code block by 4 ASCII spaces
+We request that you indent the code block by multiples of 4 ASCII spaces:
 
 ````
-```
-    This code block
-    is indented 4 spaces
+``` <%%NO_COMMENT%%!---sh-->
+    echo "This code block is intended by mutiples of 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.
 ```
 ````
 
-
-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:
+Moreover:
 
 ````
 ```
-    main() {
-|       void please_do_not_submit_this() {
-|           printf("The machine that goes BING!\n");
-        }
-|       please_do_not_submit_this();
-    }
+    The same thing applies to any markdown block surrounded by ``` lines.
 ```
 ````
 
+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.
-If you need to indent 2 or more levels, use multiples of 4 ASCII spaces.
-Please do **NOT** indent with ASCII tabs!
+## Please do NOT use ASCII tabs in markdown files
+
+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:
 
 ````
 ```
-        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.
-
-    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.
+	We	don't	mind	tabs	in	general,        <=== no thank you
+     We just ask that you NOT use them in markdown files.
 ```
 ````
 
+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
 
diff --git a/next/guidelines.html b/next/guidelines.html
index ce27639d5..7dfa5f5a7 100644
--- a/next/guidelines.html
+++ b/next/guidelines.html
@@ -933,6 +933,11 @@ and state:

 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.

 
+
| 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:

 
Legal abuse of the IOCCC rules is somewhat encouraged. Legal rule abuse
 may involve, but is not limited to, doing things that are technically allowed by
diff --git a/next/guidelines.md b/next/guidelines.md
index 9903efbbd..8935bb19c 100644
--- a/next/guidelines.md
+++ b/next/guidelines.md
@@ -752,6 +752,18 @@ and state:
 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.
 
+**`|`**   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: