From ba80b354570571bc249a4ff65038a551c809d1da Mon Sep 17 00:00:00 2001 From: Landon Curt Noll Date: Tue, 28 May 2024 14:06:42 -0700 Subject: [PATCH] improve markdown.md Move notes about HTML elements to the top. Align the "<=== no thank you" notices. Say please more. :-) Fixed a few minor nits. --- markdown.html | 172 ++++++++++++++++--------------- markdown.md | 273 +++++++++++++++++++++++++------------------------- 2 files changed, 227 insertions(+), 218 deletions(-) diff --git a/markdown.html b/markdown.html index b28cf82cf..b0d8eb116 100644 --- a/markdown.html +++ b/markdown.html @@ -390,10 +390,10 @@ See also CommonMark Spec.

Some these relate to use of markdown directly, others relate to injecting HTML into the markdown file.

In particular there are things we ask people to please do NOT use in -markdown files:

-

Do NOT use name attributes in HTML a tags

+markdown files for the IOCCC:

+

Please do NOT use the HTML construct:

-
    <a name="string">...</a>    <=== no thank you
+
    <a name="string">...</a>                                  <=== no thank you

as those are NOT part of the HTML 5 standard.

Instead use:

    <div id="string">...</div>
@@ -401,83 +401,36 @@ markdown files:

encapsulates the HTML you want to name: i.e., the target of some <a href="#string"> or some other <a href="URL#string"> for the given page URL.

-

There are certain HTML Elements that cannot have internal <div id="string">...</div>. For example you cannot do this:

-
    # <div id="string">This will NOT work</div>
+

There are certain HTML Elements that cannot have internal <div id="string">...</div>.

+

For example:

+
    # <div id="string">THIS WILL NOT WORK!</div>              <=== this will not work

For things like headings, you have to surround them as in:

    <div id="string">
     # 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.

-

Do NOT use trailing backslash outside of a code block

-

Unless the line is inside a markdown code block, please do NOT -end a markdown line with a trailing backslash (\). Instead use -a trailing <br>.

-

Instead of:

-
    In markdown,\                       <=== no thank you
-    do NOT use trailing\
-    backslashes outside of\
-    a code block
-

use:

-
    In markdown,<br>
-    use trailing<br>
-    br's outside of<br>
-    a code block
-

Again, use of a trailing backslash (\) inside a markdown code block is fine:

-
```
-    This is OK\
-    inside a\
-    markdown code\
-    block
-```
-

This will prevent pandoc(1) from generating deprecated HTML elements such as -<br />.

-

Do NOT use markdown image elements

-

Please do NOT use the markdown embedded image element.

-

Instead of using this markdown element to embed an image:

-
    ![alt text](filename.png "Title")           <=== no thank you
-

Use an img HTML element with alt, width and length -attributes:

-
    <img src="filename.png"
-     alt="describe the filename.png image for someone who cannot view it"
-     width=PIXEL_WIDTH height=PIXEL_HEIGHT>
-

For example, instead of:

-
    ![1984-anonymous-tattoo.jpg](1984-anonymous-tattoo.jpg)     <=== no thank you
-

use this HTML:

-
    <img src="1984-anonymous-tattoo.jpg"
-     alt="image of a tattoo of the 1984 anonymous C code"
-     width=600 height=401>
-

The problem goes beyond the fact that pandoc(1) generates problematic -HTML from the markdown image construct, the resulting HTML does NOT -have width and height information so browsers have to slow down -on rendering text around the image until it can internally determine -the image size.

-

Do NOT use markdown style horizontal lines

-

Please do NOT use **---**-style lines in markdown to create horizontal -lines or to separate sections.

-

Unless something is inside a markdown code block, do NOT start a -line with 3 or more dashes (-s).

-

Such causes pandoc(1) to generate <hr />. The <hr /> has no effect in -standard HTML 5 and interacts badly with unquoted attribute values.

-

If a horizontal line is really needed, use:

-
    <hr>
-

If a short line is needed, use:

-
    <hr style="width:10%;text-align:left;margin-left:0">
-

Do NOT use the strike HTML element

-

Please NOT use HTML elements:

-
    <strike>...</strike>        <=== no thank you
+

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

+

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

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

Use instead:

    <del>...</del>
-

Do NOT use the <tt> HTML element

-

Please do NOT use the <tt> HTML elements:

-
    <tt>The HTML 5 obsolete tt element is obsolete</tt>         <=== no thank you
+

Please do NOT use the <u> HTML element

+

Please NOT use the obsolete <u> (underline) HTML element:

+
    <u>...</u>                                                <=== no thank you
+

Use instead:

+
    <ins>...</ins>
+

Please do NOT use the <tt> HTML element

+

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

Do NOT use unindented code clocks

+

Please do NOT use code blocks that are NOT indented

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

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

We request that you indent the code block by 4 spaces:

@@ -496,7 +449,7 @@ those used in next/rules.md and in next/guidelines.md. | please_do_not_submit_this(); } ``` -

Do NOT add trailing slash on void HTML elements

+

Please do NOT add trailing slash to HTML elements

Please do NOT use a trailing slash on void HTML elements.

See also this note on trailing slashes in void-element start @@ -504,35 +457,89 @@ tags.

The trailing slash on void HTML elements has no effect and interacts badly with unquoted attribute values.

For example, please do NOT use:

-
    <br/>       <=== no thank you
+
    <br/>                                                     <=== no thank you

Instead use just:

    <br>

And for example, please do NOT use:

-
    <hr/>       <=== no thank you
+
    <hr/>                                                     <=== no thank you

Instead use just:

    <hr>

And for example, please do NOT use:

    <img src="1984-anonymous-tattoo.jpg"
      alt="image of a tattoo of the 1984 anonymous C code"
-     width=600 height=401 />                                    <=== no thank you
+ width=600 height=401 /> <=== no thank you

Instead use just:

    <img src="1984-anonymous-tattoo.jpg"
      alt="image of a tattoo of the 1984 anonymous C code"
      width=600 height=401>

etc.

- +

Please do NOT use trailing backslash outside of a code block

+

Unless the line is inside a markdown code block, please do NOT +end a markdown line with a trailing backslash (\). Instead use +a trailing <br>.

+

Instead of:

+
    In markdown,\                                             <=== no thank you
+    do NOT use trailing\
+    backslashes outside of\
+    a code block
+

use:

+
    In markdown,<br>
+    use trailing<br>
+    br's outside of<br>
+    a code block
+

Again, use of a trailing backslash (\) inside a markdown code block is fine:

+
```
+    This is OK\
+    inside a\
+    markdown code\
+    block
+```
+

This will prevent pandoc(1) from generating deprecated HTML elements such as +<br />.

+

Please do NOT use markdown style images

+

Please do NOT use the markdown embedded image element.

+

Instead of using this markdown element to embed an image:

+
    ![alt text](filename.png "Title")                         <=== no thank you
+

Use an <img ..> HTML element with alt=, width= and length= +attributes:

+
    <img src="filename.png"
+     alt="describe the filename.png image for someone who cannot view it"
+     width=PIXEL_WIDTH height=PIXEL_HEIGHT>
+

For example, instead of:

+
    ![1984-anonymous-tattoo.jpg](1984-anonymous-tattoo.jpg)   <=== no thank you
+

use this HTML:

+
    <img src="1984-anonymous-tattoo.jpg"
+     alt="image of a tattoo of the 1984 anonymous C code"
+     width=600 height=401>
+

The problem goes beyond the fact that pandoc(1) generates problematic +HTML from the markdown image construct, the resulting HTML does NOT +have width and height information so browsers have to slow down +on rendering text around the image until it can internally determine +the image size.

+

Please do NOT use markdown style horizontal lines

+

Please do NOT use **---**-style lines in markdown to create horizontal +lines or to separate sections.

+

Unless something is inside a markdown code block, do NOT start a +line with 3 or more dashes (-s).

+

Such causes pandoc(1) to generate <hr />. The <hr /> has no effect in +standard HTML 5 and interacts badly with unquoted attribute values.

+

If a horizontal line is really needed, use:

+
    <hr>
+

If a short line is needed, use:

+
    <hr style="width:10%;text-align:left;margin-left:0">
+

Please do NOT end a markdown links with a double closed parenthesis “))”.

Markdown links that end in “))” complicate parsing and sometimes lead to incorrect URLs or file paths.

Instead of:

-
    [some text](https://example.com/foo_(bar))  <=== no thank you
+
    [some text](https://example.com/foo_(bar))                <=== no thank you

Use:

    [some text](https://example.com/foo_&#x28;bar&#x29;)

Instead of:

-
    This thing, ([some text](some/path)), is NOT ideal. <=== no thank you
+
    This thing, ([some text](some/path)), is NOT ideal.       <=== no thank you

Use:

    This thing, [some text](some/path), is better.
-

Do NOT place text on the next line after a markdown code block

+

Please do NOT place text on the next line after a markdown code block

Please do NOT place text on the next line after a markdown code block. Instead, place a blank line after the end of a markdown code block as this makes it easier to detect when markdown code blocks are @@ -545,7 +552,7 @@ NOT properly indented.

return foo; } ``` -C compilers cannot be given a -Wno-main-arg-errors flag. <=== no thank you +C compilers cannot be given a -Wno-main-arg-errors flag. <=== no thank you

Use:

```
     int
@@ -555,17 +562,16 @@ C compilers cannot be given a -Wno-main-arg-errors flag.         <=== no than
     }
 ```
 
-C compilers cannot be given a -Wno-main-arg-errors flag.
-
-BTW: note the blank line after the code block.
- +C compilers cannot be given a -Wno-main-arg-errors flag. +

BTW: Please note the blank line after the code block.

+

Please do NOT use parenthesis inside the markdown link titles.

Instead of:

-
    [some (text)](https://example.com/cyrds)      <=== no thank you
+
    [some (text)](https://example.com/cyrds)                  <=== no thank you

Use:

    [some &#x28;text&#x29;](https://example.com/cyrds)

Instead of:

-
    [ls(1)](https://example.com/ls-man-page.1)      <=== no thank you
+
    [ls(1)](https://example.com/ls-man-page.1)                <=== no thank you

Use:

    [ls&#x28;1&#x29;](https://example.com/ls-man-page.1)
diff --git a/markdown.md b/markdown.md index 92c065df8..76c07a833 100644 --- a/markdown.md +++ b/markdown.md @@ -16,15 +16,15 @@ Some these relate to use of markdown directly, others relate to injecting HTML into the markdown file. In particular there are things we ask people to please do **NOT** use in -markdown files: +markdown files for the IOCCC: -## Do NOT use name attributes in HTML a tags +## Please do NOT use name attributes in HTML `` hyperlink elements Please do **NOT** use the HTML construct: ``` - ... <=== no thank you + ... <=== no thank you ``` as those are **NOT** part of the HTML 5 standard. @@ -41,10 +41,12 @@ encapsulates the HTML you want to name: i.e., the target of some for the given page URL. There are certain HTML Elements that cannot have internal `
...
`. For example you cannot do this: +id="string">...`. + +For example: ``` - #
This will NOT work
+ #
THIS WILL NOT WORK!
<=== this will not work ``` For things like headings, you have to surround them as in: @@ -59,115 +61,13 @@ While some browsers will still recognize the HTML construct `...`, it is possible they might NOT in the future. -## Do NOT use trailing backslash outside of a code block +## Please do NOT use the `` nor `` HTML element -Unless the line is inside a markdown code block, please do **NOT** -end a markdown line with a trailing backslash (`\`). Instead use -a trailing `
`. - -Instead of: +Please NOT use the obsolete `` nor `` ( _strikeout_ ) HTML elements: ``` - In markdown,\ <=== no thank you - do NOT use trailing\ - backslashes outside of\ - a code block -``` - -use: - -``` - In markdown,
- use trailing
- br's outside of
- a code block -``` - -Again, use of a trailing backslash (`\`) inside a markdown code block is fine: - -```` -``` - This is OK\ - inside a\ - markdown code\ - block -``` -```` - -This will prevent `pandoc(1)` from generating deprecated HTML elements such as -`
`. - - -## Do NOT use markdown image elements - -Please do **NOT** use the markdown embedded image element. - -Instead of using this markdown element to embed an image: - -``` - ![alt text](filename.png "Title") <=== no thank you -``` - -Use an `img` HTML element with `alt`, `width` and `length` -attributes: - -``` - describe the filename.png image for someone who cannot view it -``` - -For example, instead of: - -``` - ![1984-anonymous-tattoo.jpg](1984-anonymous-tattoo.jpg) <=== no thank you -``` - -use this HTML: - -``` - image of a tattoo of the 1984 anonymous C code -``` - -The problem goes beyond the fact that `pandoc(1)` generates problematic -HTML from the markdown image construct, the resulting HTML does NOT -have `width` and `height` information so browsers have to slow down -on rendering text around the image until it can internally determine -the image size. - - -## Do NOT use markdown style horizontal lines - -Please do **NOT** use `**---**`-style lines in markdown to create horizontal -lines or to separate sections. - -Unless something is inside a markdown code block, do NOT start a -line with 3 or more dashes (`-`s). - -Such causes `pandoc(1)` to generate `
`. The `
` has no effect in -standard HTML 5 and interacts badly with unquoted attribute values. - -If a horizontal line is really needed, use: - -``` -
-``` - -If a short line is needed, use: - -``` -
-``` - - -## Do NOT use the `` HTML element - -Please NOT use HTML elements: - -``` - ... <=== no thank you + ... <=== no thank you + ... <=== no thank you ``` Use instead: @@ -177,12 +77,12 @@ Use instead: ``` -## Do NOT use the `` HTML element +## Please do NOT use the `` HTML element -Please NOT use HTML elements: +Please NOT use the obsolete `` (_underline_) HTML element: ``` - ... <=== no thank you + ... <=== no thank you ``` Use instead: @@ -192,17 +92,17 @@ Use instead: ``` -## Do NOT use the `` HTML element +## Please do NOT use the `` HTML element -Please do **NOT** use the `` HTML elements: +Please do **NOT** use the obsolete `` (_teletype_) HTML element: -```html - The HTML 5 obsolete tt element is obsolete <=== no thank you +``` + The obsolete tt element is obsolete <=== no thank you ``` Instead use either a monospaced span: -```html +``` Use of monospaced font is one option ``` @@ -213,13 +113,13 @@ Or better and easier still, use an inline markdown code block: ``` -## Do NOT use unindented code clocks +## Please do NOT use code blocks that are NOT indented Please do **NOT** start code blocks at the left-hand edge. ```` ``` -This code block <=== no thank you +This code block <=== no thank you is NOT indented ``` ```` @@ -252,7 +152,7 @@ For example, `next/guidelines.md` uses this markdown code block: ```` -## Do NOT add trailing slash on void HTML elements +## Please do NOT add trailing slash to HTML elements Please do **NOT** use a trailing slash on [void HTML elements](https://github.com/validator/validator/wiki/Markup-»-Void-elements). @@ -266,7 +166,7 @@ unquoted attribute values. For example, please do NOT use: ``` -
<=== no thank you +
<=== no thank you ``` Instead use just: @@ -278,7 +178,7 @@ Instead use just: And for example, please do NOT use: ``` -
<=== no thank you +
<=== no thank you ``` Instead use just: @@ -292,7 +192,7 @@ And for example, please do NOT use: ``` image of a tattoo of the 1984 anonymous C code <=== no thank you + width=600 height=401 /> <=== no thank you ``` Instead use just: @@ -306,7 +206,110 @@ Instead use just: etc. -## Do NOT end markdown links in "))" +## Please do NOT use trailing backslash outside of a code block + +Unless the line is inside a markdown code block, please do **NOT** +end a markdown line with a trailing backslash (`\`). Instead use +a trailing `
`. + +Instead of: + +``` + In markdown,\ <=== no thank you + do NOT use trailing\ + backslashes outside of\ + a code block +``` + +use: + +``` + In markdown,
+ use trailing
+ br's outside of
+ a code block +``` + +Again, use of a trailing backslash (`\`) inside a markdown code block is fine: + +```` +``` + This is OK\ + inside a\ + markdown code\ + block +``` +```` + +This will prevent `pandoc(1)` from generating deprecated HTML elements such as +`
`. + + +## Please do NOT use markdown style images + +Please do **NOT** use the markdown embedded image element. + +Instead of using this markdown element to embed an image: + +``` + ![alt text](filename.png "Title") <=== no thank you +``` + +Use an `` HTML element with `alt=`, `width=` and `length=` +attributes: + +``` + describe the filename.png image for someone who cannot view it +``` + +For example, instead of: + +``` + ![1984-anonymous-tattoo.jpg](1984-anonymous-tattoo.jpg) <=== no thank you +``` + +use this HTML: + +``` + image of a tattoo of the 1984 anonymous C code +``` + +The problem goes beyond the fact that `pandoc(1)` generates problematic +HTML from the markdown image construct, the resulting HTML does NOT +have `width` and `height` information so browsers have to slow down +on rendering text around the image until it can internally determine +the image size. + + +## Please do NOT use markdown style horizontal lines + +Please do **NOT** use `**---**`-style lines in markdown to create horizontal +lines or to separate sections. + +Unless something is inside a markdown code block, do NOT start a +line with 3 or more dashes (`-`s). + +Such causes `pandoc(1)` to generate `
`. The `
` has no effect in +standard HTML 5 and interacts badly with unquoted attribute values. + +If a horizontal line is really needed, use: + +``` +
+``` + +If a short line is needed, use: + +``` +
+``` + + +## Please do NOT end markdown links in "))" Please do **NOT** end a markdown links with a double closed parenthesis "))". @@ -316,7 +319,7 @@ to incorrect URLs or file paths. Instead of: ``` - [some text](https://example.com/foo_(bar)) <=== no thank you + [some text](https://example.com/foo_(bar)) <=== no thank you ``` Use: @@ -328,7 +331,7 @@ Use: Instead of: ``` - This thing, ([some text](some/path)), is NOT ideal. <=== no thank you + This thing, ([some text](some/path)), is NOT ideal. <=== no thank you ``` Use: @@ -338,7 +341,7 @@ Use: ``` -## Do NOT place text on the next line after a markdown code block +## Please do NOT place text on the next line after a markdown code block Please do **NOT** place text on the next line after a markdown code block. Instead, place a blank line after the end of a markdown code block @@ -355,7 +358,7 @@ Instead of: return foo; } ``` -C compilers cannot be given a -Wno-main-arg-errors flag. <=== no thank you +C compilers cannot be given a -Wno-main-arg-errors flag. <=== no thank you ```` Use: @@ -370,19 +373,19 @@ Use: ``` C compilers cannot be given a -Wno-main-arg-errors flag. - -BTW: note the blank line after the code block. ```` +**BTW**: Please note the blank line after the code block. -## Do NOT put "("s nor ")"s in markdown link titles + +## Please do NOT put "("s nor ")"s in markdown link titles Please do **NOT** use parenthesis inside the markdown link titles. Instead of: ``` - [some (text)](https://example.com/cyrds) <=== no thank you + [some (text)](https://example.com/cyrds) <=== no thank you ``` Use: @@ -394,7 +397,7 @@ Use: Instead of: ``` - [ls(1)](https://example.com/ls-man-page.1) <=== no thank you + [ls(1)](https://example.com/ls-man-page.1) <=== no thank you ``` Use: