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

Split examples into incorrect and correct code blocks; move the

Browse Source 
cross and tick marks out of the examples and apply a `<span
style="color:name">` to assert correct viewing for all browsers
and fonts.
This commit is contained in:
Anthony Howe committed 2025-11-27 15:02:39 -05:00
1 parent 3011f32757
commit 28323ee356
1 file changed
+184 -141
Download Patch File Download Diff File Expand all files Collapse all files
markdown.md
+184 -141
View File
@@ -35,24 +35,34 @@ and ✔️ for preferred correct one.
If (it is not required) you do use sections in your `remarks.md` file (this does If (it is not required) you do use sections in your `remarks.md` file (this does
not apply to other markdown files), **PLEASE** start at level three up to level six: not apply to other markdown files), **PLEASE** start at level three up to level six:
<span style="color:red">❌</span> Reserved in `remarks.md` only.
```<!---markdown--> ```<!---markdown-->
❌ # Section Reserved # Section Reserved
❌ ## Section Reserved ## Section Reserved
✔️ ### Section Level 3 ```
✔️ #### Section Level 4
✔️ ##### Section Level 5 <span style="color:green">✔</span> Available every where.
✔️ ###### Section Level 6 ```
### Section Level 3
#### Section Level 4
##### Section Level 5
###### Section Level 6
``` ```
<div id="anchor-name"></div> <div id="anchor-name"></div>
## Replace `<a name="anchor_name"></a>` construct. ## Replace `<a name="anchor_name"></a>` construct.
<span style="color:red">❌</span> Incorrect.
```<!---html--> ```<!---html-->
❌ <a name="old_way">...</a> <a name="old_way">Section title</a>
✔️ <div id="new_way">...</div> ```
✔️
✔️ ### Section title <span style="color:green">✔</span> Correct.
```<!---html-->
<div id="new_way"></div>
### Section title
``` ```
@@ -60,71 +70,93 @@ not apply to other markdown files), **PLEASE** start at level three up to level
## Markdown links instead of `<a>...</a>` ## Markdown links instead of `<a>...</a>`
<span style="color:red">❌</span> Incorrect.
```<!---html--> ```<!---html-->
❌ This <a href="#link_target>HTML link text</a> works, but we prefer This <a href="#link_target>HTML link text</a> works, but we prefer see below...
✔️ [markdown link text](#link_target) ```
<span style="color:green">✔</span> Correct.
```<!---html-->
[markdown link text](#link_target)
``` ```
<div id="del"></div><div id="strike"></div> <div id="del"></div><div id="strike"></div>
## Replace `<strike>` or `<s>` ## Replace `<strike>` or `<s>`
<span style="color:red">❌</span> Incorrect.
```<!---html--> ```<!---html-->
❌ <strike>striked through text</strike> <strike>striked through text</strike>
❌ <s>HTML 5 striked through text</s> <s>HTML 5 striked through text</s>
```
✔️ <del>HTML 5 striked through text</del> <span style="color:green">✔</span> Correct.
✔️ ~~markdown striked through text~~ ```<!---html-->
~~markdown striked through text~~
<del>HTML 5 striked through text</del>
``` ```
<div id="ins"></div><div id="underline"></div> <div id="ins"></div><div id="underline"></div>
## Replace `<u>` ## Replace `<u>`
<span style="color:red">❌</span> Incorrect.
```<!---html--> ```<!---html-->
❌ <u>old tags</u> <u>old tags</u>
✔️ <ins>HTML 5 tags</ins> ```
<span style="color:green">✔</span> Correct.
```<!---html-->
<ins>HTML 5 tags</ins>
``` ```
<div id="tt"></div> <div id="tt"></div>
## Replace `<tt>` ## Replace `<tt>`
<span style="color:red">❌</span> Incorrect.
```<!---html--> ```<!---html-->
❌ <tt>obsolete HTML</tt> <tt>obsolete HTML</tt>
✔️ <span style="font-family: monospace;">monospace font</span> ```
✔️ `markdown style monospace`
<span style="color:green">✔</span> Correct.
```<!---html-->
<span style="font-family: monospace;">monospace font</span>
`markdown style monospace`
``` ```
<div id="indent"></div> <div id="indent"></div>
## Indent code blocks by four spaces, not by TAB. ## Indent code blocks by four spaces, not by TAB.
<span style="color:red">❌</span> Incorrect.
```<!---sh--> ```<!---sh-->
❌ echo "This code block is NOT indented" echo "This code block is NOT indented"
``` ```
We request that you indent the code block by multiples of four (4) We request that you indent the code block by multiples of four (4)
ASCII SPACES, never TAB (␉): ASCII SPACES, never TAB (␉):
<span style="color:green">✔</span> Correct.
````<!---sh--> ````<!---sh-->
✔️ echo "This code block is indented by multiples of 4 spaces" echo "This code block is indented by multiples of 4 spaces"
✔️ # The top level starts with a 4 ASCII space indent. # The top level starts with a 4 ASCII space indent.
✔️ # #
✔️ # Only indent with multiples of 4 ASCII spaces. # Only indent with multiples of 4 ASCII spaces.
✔️ # 2nd level indent needs 8 ASCII spaces (no tabs). # 2nd level indent needs 8 ASCII spaces (no tabs).
✔️ # 3rd level indent needs 12 ASCII spaces (no tabs). # 3rd level indent needs 12 ASCII spaces (no tabs).
✔️ # etc. # etc.
```` ````
Alternatively its possible to use ` ``` ` marks, without the initial Alternatively its possible to use ` ``` ` marks, without the initial
four (4) space indentation. This is usually the better method. four (4) space indentation. This is usually the better method.
<span style="color:green">✔</span> Also correct.
````<!---markdown--> ````<!---markdown-->
✔️ ``` ```
✔️ The same thing applies to any markdown block bracketed by ``` lines. The same thing applies to any markdown block bracketed by ``` lines.
✔️ ``` ```
```` ````
<div id="tabs"></div><div id="spaces"></div> <div id="tabs"></div><div id="spaces"></div>
@@ -141,138 +173,131 @@ used as part of the leading whitespace within a markdown file.
If you need to indent two (2) or more levels, use multiples of four (4) If you need to indent two (2) or more levels, use multiples of four (4)
ASCII SPACES. ASCII SPACES.
<span style="color:red">❌</span> Incorrect for markdown files only.
````<!---markdown--> ````<!---markdown-->
``` ```
❌ ␉Please do **NOT**␉use ASCII tabs␉in markdown files. ␉Please do **NOT**␉use ASCII tabs␉in markdown files.
❌ ␉␉Please do **NOT** indent markdown with ASCII tabs. ␉␉Please do **NOT** indent markdown with ASCII tabs.
❌ ␉We␉don't␉mind␉tabs␉in␉general, ␉We␉don't␉mind␉tabs␉in␉general,
❌ ␉We just ask that you NOT use them in markdown files. ␉We just ask that you NOT use them in markdown files.
``` ```
```` ````
And to clarify, we are only talking about markdown files, not C code or <span style="color:green">✔</span> Ok for all file types, eg. `.c`, `.h`, `.mk`, `.sh`, **EXCEPT** `.md` markdown files.
any other non-markdown content:
````<!---c--> ````<!---c-->
✔️ ␉printf("It is fine␉to␉use tabs in Obfuscated C code.\n"); ␉printf("It is fine␉to␉use tabs in Obfuscated C code.\n");
✔️ ␉␉/*␉if␉you␉wish */ ␉␉/*␉if␉you␉wish */
✔️ ␉// We ask that you to NOT use ASCII tab characters in your remarks.md writeup, ␉// We ask that you to NOT use ASCII tab characters in your remarks.md writeup,
✔️ ␉// or in any other markdown files within your entry, please. ␉// or 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 do
**NOT** use any ASCII TAB (␉) characters in markdown files.
<div id="code"></div><div id="languages"></div> <div id="code"></div><div id="languages"></div>
## Use HTML comments for code block language syntax. ## Use HTML comments for code block language syntax.
We request that [fenced markdown code blocks](https://www.markdownguide.org/extended-syntax/#fenced-code-blocks) We request that [fenced markdown code blocks](https://www.markdownguide.org/extended-syntax/#fenced-code-blocks) **NOT** specify a language directly.
**NOT** specify a language directly.
<span style="color:red">❌</span> Incorrect
````<!---markdown--> ````<!---markdown-->
❌ ```c ```c
❌ int main(void) {return 0;} int main(void) {return 0;}
❌ ``` ```
```` ````
Instead, put the language inside an HTML comment, separated from the Instead, put the language inside an HTML comment, separated from the
markdown code block starting fence by a space: markdown code block starting fence by a space:
<span style="color:green">✔</span> Correct
````<!---markdown--> ````<!---markdown-->
✔️ ```<!---c--> ```<!---c-->
✔️ int main(void) {return 0;} int main(void) {return 0;}
✔️ ``` ```
```` ````
**IMPORTANT**: The **initial** &nbsp; **\` \` \`** &nbsp; must be
followed by an **ASCII SPACE**, and **THEN** an **opening** **
`<!---`** (a "`<`", a "`!`" and then three "`-`"s), and **THEN**
the **language** and **FINALLY** a **closing** "`-->`" (two "`-`"s
followed by a "`>`").
<div id="code-and-text"></div> <div id="code-and-text"></div>
## Ensure blank line between code block and text. ## Ensure blank line between code block and text.
Please do **NOT** place text on the next line after a markdown code <span style="color:red">❌</span> Incorrect, missing empty line after closing fence (` ``` `).
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
**NOT** properly indented.
````<!---markdown--> ````<!---markdown-->
``` ```
int int
main(int foo) main(int foo)
{ {
return foo; return foo;
} }
❌ ``` ```
❌ C compilers cannot be given a -Wno-main-arg-errors flag. C compilers cannot be given a -Wno-main-arg-errors flag.
````
``` <span style="color:green">✔</span> Correct, has empty line between closing fence and subsequent text.
int ````<!---markdown-->
main(int foo) ```
{ int
return foo; main(int foo)
} {
✔️ ``` return foo;
✔️ }
✔️ C compilers cannot be given a -Wno-main-arg-errors flag. ```
C compilers cannot be given a -Wno-main-arg-errors flag.
```` ````
<div id="tag-slash"></div> <div id="tag-slash"></div>
## Do not add trailing slash to void HTML tags. ## Do not add trailing slash to void HTML tags.
Please do **NOT** use a trailing slash on [void HTML elements](https://github.com/validator/validator/wiki/Markup-»-Void-elements). See also
this note on [trailing slashes in void-element start tags](https://github.com/validator/validator/wiki/Markup-»-Void-elements#trailing-slashes-in-void-element-start-tags-do-NOT-mark-the-start-tags-as-self-closing).
The trailing slash on void HTML elements has no effect and interacts The trailing slash on [void HTML elements](https://github.com/validator/validator/wiki/Markup-»-Void-elements) has no effect and interacts
badly with unquoted attribute values. badly with unquoted attribute values; do not use. See also this note
on [trailing slashes in void-element start tags](https://github.com/validator/validator/wiki/Markup-»-Void-elements#trailing-slashes-in-void-element-start-tags-do-NOT-mark-the-start-tags-as-self-closing).
<span style="color:red">❌</span> Incorrect
```<!---html--> ```<!---html-->
❌ <br/> <br/>
❌ <hr/> <hr/>
❌ <img src="1984-anonymous-tattoo.jpg" alt="image of a tattoo of <img src="1984-anonymous-tattoo.jpg" alt="image of a tattoo of
the 1984 anonymous C code" width=600 height=401 /> the 1984 anonymous C code" width=600 height=401 />
```
✔️ <br> <span style="color:green">✔</span> Correct
✔️ <hr> ```<!---html-->
✔️ <img src="1984-anonymous-tattoo.jpg" alt="image of a tattoo of <br>
the 1984 anonymous C code" width=600 height=401> <hr>
<img src="1984-anonymous-tattoo.jpg" alt="image of a tattoo of
the 1984 anonymous C code" width=600 height=401>
``` ```
<div id="br"></div><div id="backslash"></div> <div id="br"></div><div id="backslash"></div>
## Do not use a trailing backslash outside of a code block ## Do not use a trailing backslash outside of a code block
Unless the line is inside a markdown code block, please do **NOT** end <span style="color:red">❌</span> Incorrect, do not use escaped newlines outside of a code block.
a markdown line with a trailing backslash (`\`). Instead use a trailing
`<br>`.
```<!---markdown--> ```<!---markdown-->
❌ In markdown,\ In markdown,\
❌ do NOT use trailing\ do NOT use trailing\
❌ backslashes outside of\ backslashes outside of\
❌ a code block a code block
```
✔️ In markdown,<br> <span style="color:green">✔</span> Correct
✔️ use trailing<br> ````<!---html-->
✔️ br's outside of<br> In markdown,<br>
✔️ a code block use trailing<br>
br's outside of<br>
a code block
✔️ ``` ```
✔️ This is OK\ This is OK\
✔️ inside a\ inside a\
✔️ markdown code\ markdown code\
✔️ block block
✔️ ``` ```
✔️ `This is OK\` `This is OK\`
```` ````
Doing it this way will prevent `pandoc(1)` from generating deprecated Doing it this way will prevent `pandoc(1)` from generating deprecated
@@ -282,16 +307,18 @@ HTML elements, such as `<br />`.
## Do not use markdown style images ## Do not use markdown style images
Instead of using this markdown element to embed an image: <span style="color:red">❌</span> Incorrect
```<!---markdown--> ```<!---markdown-->
❌ ![alt text](filename.png "Title") ![alt text](filename.png "Title")
```
✔️ <img src="filename.png" <span style="color:green">✔</span> Correct
alt="describe the filename.png image for someone who cannot view it" ```<!---markdown-->
width=PIXEL_WIDTH height=PIXEL_HEIGHT> <img src="filename.png"
alt="describe the filename.png image for someone who cannot view it"
width=PIXEL_WIDTH height=PIXEL_HEIGHT>
Which allows for HTML <img> attributes `alt=`, `width=` and `length=`. Which allows for HTML <img> attributes `alt=`, `width=` and `length=`.
``` ```
The problem is that `pandoc(1)` generates problematic HTML from the The problem is that `pandoc(1)` generates problematic HTML from the
@@ -313,28 +340,36 @@ Such markdown causes `pandoc(1)` to generate `<hr />`. The `<hr />` has
no effect in standard HTML 5 and interacts badly with unquoted attribute no effect in standard HTML 5 and interacts badly with unquoted attribute
values. values.
<span style="color:red">❌</span> Incorrect
```<!---html--> ```<!---html-->
❌ * * * * * *
❌ - - - - - -
❌ --- ---
```
Regular divider... <span style="color:green">✔</span> Correct
✔️ <hr> ```<!---html-->
Regular divider...
<hr>
A short divider... A short divider...
✔️ <hr style="width:10%;text-align:left;margin-left:0"> <hr style="width:10%;text-align:left;margin-left:0">
``` ```
<div id="parentheses"></div> <div id="parentheses"></div>
## Do not put a literal "`(`" or "`)`" in markdown link titles ## Do not put a literal "`(`" or "`)`" in markdown link titles
<span style="color:red">❌</span> Incorrect
```<!---markdown--> ```<!---markdown-->
❌ [some (text)](https://example.com/curds) [some (text)](https://example.com/curds)
✔️ [some &lpar;text&rpar;](https://example.com/curds) [ls(1)](https://example.com/ls-man-page.1)
```
❌ [ls(1)](https://example.com/ls-man-page.1) <span style="color:green">✔</span> Correct
✔️ [ls&lpar;1&rpar;](https://example.com/ls-man-page.1) ```<!---markdown-->
[some &lpar;text&rpar;](https://example.com/curds)
[ls&lpar;1&rpar;](https://example.com/ls-man-page.1)
``` ```
<div id="closing-parentheses"></div> <div id="closing-parentheses"></div>
@@ -344,12 +379,16 @@ values.
Markdown links that end in "`))`" complicate parsing and sometimes lead Markdown links that end in "`))`" complicate parsing and sometimes lead
to incorrect URLs or file paths. to incorrect URLs or file paths.
<span style="color:red">❌</span> Incorrect
```<!---markdown--> ```<!---markdown-->
❌ [some text](https://example.com/foo_(bar)) [some text](https://example.com/foo_(bar))
✔️ [some text](https://example.com/foo_&lpar;bar&rpar;) This thing, ([some text](some/path)), is NOT ideal.
```
❌ This thing, ([some text](some/path)), is NOT ideal. <span style="color:green">✔</span> Correct
✔️ This thing, [some text](some/path), is better. ```<!---markdown-->
[some text](https://example.com/foo_&lpar;bar&rpar;)
This thing, [some text](some/path), is better.
``` ```
<div id="italics"></div> <div id="italics"></div>
@@ -361,13 +400,17 @@ Instead use an underscore (`_`). Using an asterisk can complicate
parsing and sometimes lead to incorrect results. This can especially parsing and sometimes lead to incorrect results. This can especially
go for when it is **_bold and italic_**. go for when it is **_bold and italic_**.
<span style="color:red">❌</span> Incorrect
```<!---markdown--> ```<!---markdown-->
❌ *this text is italic* *this text is italic*
✔️ _this text is italic_ ***this text is bold italic***
```
❌ ***this text is bold italic*** <span style="color:green">✔</span> Correct
✔️ **_this text is bold italic_** ```<!---markdown-->
✔️ _**this text is bold italic**_ _this text is italic_
**_this text is bold italic_**
_**this text is bold italic**_
``` ```
**BTW**: the astute reader might notice that some cases of `*` for italic **BTW**: the astute reader might notice that some cases of `*` for italic
might have slipped through. We do ask you, however, to please might have slipped through. We do ask you, however, to please