diff --git a/markdown.md b/markdown.md
index 84a5de1a3..ea1bd103b 100644
--- a/markdown.md
+++ b/markdown.md
@@ -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
not apply to other markdown files), **PLEASE** start at level three up to level six:
+❌ Reserved in `remarks.md` only.
```
-❌ # Section Reserved
-❌ ## Section Reserved
-✔️ ### Section Level 3
-✔️ #### Section Level 4
-✔️ ##### Section Level 5
-✔️ ###### Section Level 6
+# Section Reserved
+## Section Reserved
+```
+
+✔ Available every where.
+```
+### Section Level 3
+#### Section Level 4
+##### Section Level 5
+###### Section Level 6
```
## Replace `` construct.
+❌ Incorrect.
```
-❌ ...
-✔️ ...
-✔️
-✔️ ### Section title
+Section title
+```
+
+✔ Correct.
+```
+
+
+### Section title
```
@@ -60,71 +70,93 @@ not apply to other markdown files), **PLEASE** start at level three up to level
## Markdown links instead of `...`
+❌ Incorrect.
```
-❌ This HTML link text works, but we prefer see below...
+```
+
+✔ Correct.
+```
+[markdown link text](#link_target)
```
## Replace `` or ``
+❌ Incorrect.
```
-❌ striked through text
-❌ HTML 5 striked through text
+striked through text
+HTML 5 striked through text
+```
-✔️ HTML 5 striked through text
-✔️ ~~markdown striked through text~~
+✔ Correct.
+```
+~~markdown striked through text~~
+HTML 5 striked through text
```
## Replace ``
+❌ Incorrect.
```
-❌ old tags
-✔️ HTML 5 tags
+old tags
+```
+
+✔ Correct.
+```
+HTML 5 tags
```
## Replace ``
+❌ Incorrect.
```
-❌ obsolete HTML
-✔️ monospace font
-✔️ `markdown style monospace`
+obsolete HTML
+```
+
+✔ Correct.
+```
+monospace font
+`markdown style monospace`
```
## Indent code blocks by four spaces, not by TAB.
+❌ Incorrect.
```
-❌ 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)
ASCII SPACES, never TAB (␉):
+✔ Correct.
````
-✔️ 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.
-✔️ #
-✔️ # 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.
+ # 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.
````
Alternatively its possible to use ` ``` ` marks, without the initial
four (4) space indentation. This is usually the better method.
+✔ Also correct.
````
-✔️ ```
-✔️ The same thing applies to any markdown block bracketed by ``` lines.
-✔️ ```
+```
+The same thing applies to any markdown block bracketed by ``` lines.
+```
````
@@ -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)
ASCII SPACES.
+❌ Incorrect for markdown files only.
````
```
-❌ ␉Please do **NOT**␉use ASCII tabs␉in markdown files.
-❌ ␉␉Please do **NOT** indent markdown with ASCII tabs.
+␉Please do **NOT**␉use ASCII tabs␉in markdown files.
+␉␉Please do **NOT** indent markdown with ASCII tabs.
-❌ ␉We␉don't␉mind␉tabs␉in␉general,
-❌ ␉We just ask that you NOT use them in markdown files.
+␉We␉don't␉mind␉tabs␉in␉general,
+␉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
-any other non-markdown content:
-
+✔ Ok for all file types, eg. `.c`, `.h`, `.mk`, `.sh`, **EXCEPT** `.md` markdown files.
````
-✔️ ␉printf("It is fine␉to␉use tabs in Obfuscated C code.\n");
-✔️ ␉␉/*␉if␉you␉wish */
+␉printf("It is fine␉to␉use tabs in Obfuscated C code.\n");
+␉␉/*␉if␉you␉wish */
-✔️ ␉// 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.
+␉// 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.
````
-**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.
-
## Use HTML comments for code block language syntax.
-We request that [fenced markdown code blocks](https://www.markdownguide.org/extended-syntax/#fenced-code-blocks)
-**NOT** specify a language directly.
+We request that [fenced markdown code blocks](https://www.markdownguide.org/extended-syntax/#fenced-code-blocks) **NOT** specify a language directly.
+❌ Incorrect
````
-❌ ```c
-❌ int main(void) {return 0;}
-❌ ```
+```c
+ int main(void) {return 0;}
+```
````
Instead, put the language inside an HTML comment, separated from the
markdown code block starting fence by a space:
+✔ Correct
````
-✔️ ```
-✔️ int main(void) {return 0;}
-✔️ ```
+```
+ int main(void) {return 0;}
+```
````
-**IMPORTANT**: The **initial** **\` \` \`** must be
-followed by an **ASCII SPACE**, and **THEN** an **opening** **
-``" (two "`-`"s
-followed by a "`>`").
-
## Ensure blank line between code block and text.
-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
-**NOT** properly indented.
-
+❌ Incorrect, missing empty line after closing fence (` ``` `).
````
- ```
- int
- main(int foo)
- {
- return foo;
- }
-❌ ```
-❌ C compilers cannot be given a -Wno-main-arg-errors flag.
+```
+int
+main(int foo)
+{
+ return foo;
+}
+```
+C compilers cannot be given a -Wno-main-arg-errors flag.
+````
- ```
- int
- main(int foo)
- {
- return foo;
- }
-✔️ ```
-✔️
-✔️ C compilers cannot be given a -Wno-main-arg-errors flag.
+✔ Correct, has empty line between closing fence and subsequent text.
+````
+```
+int
+main(int foo)
+{
+ return foo;
+}
+```
+
+C compilers cannot be given a -Wno-main-arg-errors flag.
````
## 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
-badly with unquoted attribute values.
+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; 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).
+
+❌ Incorrect
```
-❌
-❌
-❌
+
+
+
+```
-✔️
-✔️
-✔️
+✔ Correct
+```
+
+
+
```
## Do not use a 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
-`
`.
-
+❌ Incorrect, do not use escaped newlines outside of a code block.
```
-❌ In markdown,\
-❌ do NOT use trailing\
-❌ backslashes outside of\
-❌ a code block
+In markdown,\
+do NOT use trailing\
+backslashes outside of\
+a code block
+```
-✔️ In markdown,
-✔️ use trailing
-✔️ br's outside of
-✔️ a code block
+✔ Correct
+````
+In markdown,
+use trailing
+br's outside of
+a code block
-✔️ ```
-✔️ This is OK\
-✔️ inside a\
-✔️ markdown code\
-✔️ block
-✔️ ```
+```
+This is OK\
+inside a\
+markdown code\
+block
+```
-✔️ `This is OK\`
+`This is OK\`
````
Doing it this way will prevent `pandoc(1)` from generating deprecated
@@ -282,16 +307,18 @@ HTML elements, such as `
`.
## Do not use markdown style images
-Instead of using this markdown element to embed an image:
-
+❌ Incorrect
```
-❌ 
+
+```
-✔️
+✔ Correct
+```
+
- Which allows for HTML
attributes `alt=`, `width=` and `length=`.
+Which allows for HTML
attributes `alt=`, `width=` and `length=`.
```
The problem is that `pandoc(1)` generates problematic HTML from the
@@ -313,28 +340,36 @@ Such markdown causes `pandoc(1)` to generate `
`. The `
` has
no effect in standard HTML 5 and interacts badly with unquoted attribute
values.
+❌ Incorrect
```
-❌ * * *
-❌ - - -
-❌ ---
+* * *
+- - -
+---
+```
- Regular divider...
-✔️
+✔ Correct
+```
+Regular divider...
+
- A short divider...
-✔️
+A short divider...
+
```
## Do not put a literal "`(`" or "`)`" in markdown link titles
+❌ Incorrect
```
-❌ [some (text)](https://example.com/curds)
-✔️ [some (text)](https://example.com/curds)
+[some (text)](https://example.com/curds)
+[ls(1)](https://example.com/ls-man-page.1)
+```
-❌ [ls(1)](https://example.com/ls-man-page.1)
-✔️ [ls(1)](https://example.com/ls-man-page.1)
+✔ Correct
+```
+[some (text)](https://example.com/curds)
+[ls(1)](https://example.com/ls-man-page.1)
```
@@ -344,12 +379,16 @@ values.
Markdown links that end in "`))`" complicate parsing and sometimes lead
to incorrect URLs or file paths.
+❌ Incorrect
```
-❌ [some text](https://example.com/foo_(bar))
-✔️ [some text](https://example.com/foo_(bar))
+[some text](https://example.com/foo_(bar))
+This thing, ([some text](some/path)), is NOT ideal.
+```
-❌ This thing, ([some text](some/path)), is NOT ideal.
-✔️ This thing, [some text](some/path), is better.
+✔ Correct
+```
+[some text](https://example.com/foo_(bar))
+This thing, [some text](some/path), is better.
```
@@ -361,13 +400,17 @@ Instead use an underscore (`_`). Using an asterisk can complicate
parsing and sometimes lead to incorrect results. This can especially
go for when it is **_bold and italic_**.
+❌ Incorrect
```
-❌ *this text is italic*
-✔️ _this text is italic_
+*this text is italic*
+***this text is bold italic***
+```
-❌ ***this text is bold italic***
-✔️ **_this text is bold italic_**
-✔️ _**this text is bold italic**_
+✔ Correct
+```
+_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
might have slipped through. We do ask you, however, to please