-
+```
+✕
-## Please do NOT use the `name` attributes in HTML `...` hyperlink elements
-
-...
+```
+✕ old tags
+✔ HTML 5 tags
```
-where the `...` is the HTML you want to "name". The ``
-encapsulates the HTML you want to name: i.e., the target of some
-`` or some other ``
-for the given page URL.
+
+
+## Replace ``
-### IMPORTANT POINT:
-
-There are certain markdown constructs that **CANNOT** have an **internal** `
-
-Please do **NOT** use the obsolete `...
` element.
-
-An example is headings (lines that start with a `#`). For example:
-
-
-```
- # THIS WILL NOT WORK!
<=== this will not work
+```
+✕ obsolete HTML
+✔ monospace font
+✔ `markdown style monospace`
```
-For things like headings, you have to surround them with the `...
` element, as in:
+
+
+## Always indent code blocks 4 spaces, not tab.
-```
-
- # This will work
-
+```
+✕ echo "This code block is NOT indented"
```
-While some browsers will still recognize the HTML construct `...`, it is possible **they MIGHT NOT** in the future.
+We request that you indent the code block by multiples of four (4) ASCII SPACES, never TAB (␉):
-Jump to: [top](#)
+````
+✔ echo "This code block is indented by mutiples of 4 spaces"
-
-## If you can, it is PREFERABLE to use markdown links rather than `...`
-
+✔ # 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.
+````
-It is easier and preferred to use markdown links rather than HTML `..`
-anchors.
+Alternatively its possible to use ` ``` ` marks, without the initial four (4) space indentation. This is usually the better method.
-Instead of:
+````
+✔ ```
+✔ The same thing applies to any markdown block bracketed by ``` lines.
+✔ ```
+````
+
+
+## Do not use ASCII TAB in markdown files.
-```
- Use of
-
-## Please do NOT use the `` or the `` HTML element
-
-
-
-
-Please do **NOT** use the obsolete `` (_underline_) HTML element:
-
-```
- ... <=== no thank you
-```
-
-Use instead:
-
-```
- ...
-```
-
-Jump to: [top](#)
-
-
-## Please do NOT use the `` HTML element
-
-
-
-
-Please do **NOT** use the obsolete ``
-(**teletype**) HTML element:
-
-```
- The tt element is obsolete <=== no thank you
-```
-
-Instead use either a monospaced `` or an inline markdown code block:
-
-```
- Use of a monospaced font
- is one option,
- however ...
-```
-
-We recommend using the inline markdown code block method instead:
-
-```
- Using the `inline markdown code block` is easier and is **preferred**.
-```
-
-Jump to: [top](#)
-
-
-## Please do NOT use the `` HTML element
-
-
-
-
-Please do **NOT** start code blocks at the first column.
-
-For example:
-
-````
-``` <%%NO_COMMENT%%!---sh-->
-echo "This code block is NOT indented" <=== no thank you
+✕ ␉We don't␉mind␉tabs␉in␉general,
+✕ ␉We just ask that you NOT use them in markdown files.
```
````
-We request that you indent the code block by multiples of 4 ASCII **SPACES**:
+And to clarify, we are only talking about markdown files, not C code or any other non-markdown content:
-````
-``` <%%NO_COMMENT%%!---sh-->
- echo "This code block is indented by mutiples of 4 spaces"
+````
+✔ printf("It is fine to use tabs in Obfuscated C code.\n");
+✔ /* if you wish */
- # 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 ask that you to NOT use ASCII tab characters in your remarks.md writeup,
+✔ // or in any other markdown files within your entry, please.
````
-Moreover:
+**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.
-````
-```
- The same thing applies to any markdown block surrounded by ``` lines.
-```
-````
-
-Please do **NOT** indent using ASCII tab characters in markdown files.
-
-Jump to: [top](#)
-
-
-## Please do NOT use unindented code blocks
-
-
-
-
-Please do **NOT** indent with ASCII tabs, **OR** use any
-ASCII tab characters anywhere inside a markdown file.
-
-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**.
-
-For example:
-
-````
-```
- Please do **NOT** use ASCII tabs in markdown files. <=== no thank you
- Please do **NOT** indent markdown with ASCII tabs. <=== no thank you
-
- 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 or any other non-markdown content:
-
-````
- 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.
-````
-
-**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.
-
-Jump to: [top](#)
-
-
-## Please do NOT use ASCII tabs in markdown files
-
-
+
### Tip for `vim` users
-
-If you use `vim` you can put in your `.vimrc` file (usually `~/.vimrc`) the
-following settings to make sure the tabs are not put in without you noticing:
+If you use `vim` you can put in your `.vimrc` file (usually `~/.vimrc`) the following settings to make sure the tabs are not put in without you noticing:
-```
- set tabstop=8 " a tab is 8 spaces (or whatever you wish it to be set to)
- set softtabstop=4 " ...but when inserting/backspacing use 4 spaces
- set shiftwidth=4 " ...and auto-indent 4 spaces (when autoindent is set)
- set expandtab " ...expand tab into spaces
+```
+set tabstop=8 " a tab is 8 spaces (or whatever you wish it to be set to)
+set softtabstop=4 " ...but when inserting/backspacing use 4 spaces
+set shiftwidth=4 " ...and auto-indent 4 spaces (when autoindent is set)
+set expandtab " ...expand tab into spaces
```
-If you have file type detection enabled you can, if you prefer, have these
-settings set just for markdown files:
+If you have file type detection enabled you can, if you prefer, have these settings set just for markdown files:
-```
- autocmd! Filetype markdown setlocal set tabstop=8 softtabstop=4 shiftwidth=4 expandtab
+```
+autocmd! Filetype markdown setlocal set tabstop=8 softtabstop=4 shiftwidth=4 expandtab
```
-or so.
-
-This will prevent the tab key from inserting tabs; rather it will insert 4
-spaces.
+This will prevent the tab key from inserting tabs; rather it will insert four (4) spaces.
To **VERIFY** that there are no tabs in a file you may do, in command mode:
```
- /\t
+/\t
```
If you're in insert mode hit `ESC` first.
-Jump to: [top](#)
+
+
+## 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.
-
-For example:
-
-````
-```c <=== no thank you
+````
+```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:
+Instead, put the language inside an HTML comment, separated from the markdown code block starting fence by a space:
-````
-``` <%%NO_COMMENT%%!---c-->
+````
+```
int main(void) {return 0;}
```
````
-**IMPORTANT**: The **initial** **\` \` \`** must be followed by an **ASCII SPACE**,
-and **THEN** an **opening** **``" (two "`-`"s
-followed by a "`>`").
+**IMPORTANT**: The **initial** **\` \` \`** must be followed by an **ASCII SPACE**, and **THEN** an **opening** **``" (two "`-`"s followed by a "`>`").
+
+
+
+## Insure blank line between code block and text.
-Jump to: [top](#)
+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.
-
-## Please use HTML comments to specify a language for a code block
-
-
-
+````
+✕ ```
+✕ int
+✕ main(int foo)
+✕ {
+✕ return foo;
+✕ }
+✕ ```
+✕ C compilers cannot be given a -Wno-main-arg-errors flag.
-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.
-
-For example, please do **NOT** use markdown like these:
-
-```
-
-## Please do NOT add trailing slash to void HTML elements
-
-<=== no thank you - -
<=== no thank you - -
<=== no thank you
-```
-
-Instead use, respectively:
-
-```
- - -
- -
-```
-
-Jump to: [top](#)
-
-
-
-
-Unless the line is inside a markdown code block, please do **NOT**
-end a markdown line with a trailing backslash (`\`). Instead use
-a trailing `
-## Please do NOT use a TRAILING backslash (`\`) outside of a code block
-
-`. - -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 -``` +✔ ``` +✔ int +✔ main(int foo) +✔ { +✔ return foo; +✔ } +✔ ``` +✔ +✔ C compilers cannot be given a -Wno-main-arg-errors flag. ```` -as is: + + +## Do not add trailing slash to void HTML tags. -``` - `This is OK\` +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. + +``` +✕
+✕
+✕
+
+✔ +✔
+✔
```
-Doing it this way will prevent `pandoc(1)` from generating deprecated HTML
-elements such as ``. + + +## Do not use a trailing backslash (`\`) outside of a code block -Jump to: [top](#) +Unless the line is inside a markdown code block, please do **NOT** end a markdown line with a trailing backslash (`\`). Instead use a trailing `
`. -
-
+```
+✕ In markdown,\
+✕ do NOT use trailing\
+✕ backslashes outside of\
+✕ a code block
-Please do **NOT** use the markdown embedded image element.
+✔ In markdown,
-## Please do NOT use markdown style images
-
-+✔ use trailing
+✔ br's outside of
+✔ a code block + +✔ ``` +✔ This is OK\ +✔ inside a\ +✔ markdown code\ +✔ block +✔ ``` + +✔ `This is OK\` +```` + +Doing it this way will prevent `pandoc(1)` from generating deprecated HTML elements such as `
`. + + + +## Do not use markdown style images Instead of using this markdown element to embed an image: -``` -  <=== no thank you +``` +✕  + +✔
+
+ Which allows for HTML
-```
-
-For example, instead of:
-
-```
-  <=== no thank you
-```
-
-use this HTML:
-
-```
-
-```
-
-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.
-
-Jump to: [top](#)
-
-
-
-Please do **NOT** use `---` style lines in markdown to create horizontal
-lines or to separate sections.
+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).
+Unless something is inside a markdown **code block**, do **NOT** start a line with 3 or more dashes ("`-`"s).
-Such markdown causes `pandoc(1)` to generate `
-
-
+
+
+
## Please do NOT use markdown style horizontal lines
-
-`. The `
` has no -effect in standard HTML 5 and interacts badly with unquoted attribute values. +Such markdown 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: -``` -
+``` +✕ * * * +✕ - - - +✕ --- + + Regular divider... +✔
+ + A short divider... +✔
``` -If a short line is needed, use: + +## Do not put a literal "`(`" or "`)`" in markdown link titles -``` -
+``` +✕ [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) ``` + +## Do not end markdown links with "`))`" -Jump to: [top](#) +Markdown links that end in "`))`" complicate parsing and sometimes lead to incorrect URLs or file paths. -
-## Please do NOT put a LITERAL "`(`" or "`)`" in markdown link titles
-
+```
+✕ [some text](https://example.com/foo_(bar))
+✔ [some text](https://example.com/foo_(bar))
-Please do **NOT** use literal parentheses inside markdown link titles.
-
-Instead of:
-
-```
- [some (text)](https://example.com/curds) <=== no thank you
+✕ This thing, ([some text](some/path)), is NOT ideal.
+✔ This thing, [some text](some/path), is better.
```
-use:
-
-```
- [some (text)](https://example.com/curds)
-```
-
-Instead of:
-
-```
- [ls(1)](https://example.com/ls-man-page.1) <=== no thank you
-```
-
-use:
-
-```
- [ls(1)](https://example.com/ls-man-page.1)
-```
-
-Jump to: [top](#)
-
-
-## Please do NOT end markdown links with "`))`"
-
-
-Please do **NOT** end a markdown link 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
-```
-
-use:
-
-```
- [some text](https://example.com/foo_(bar))
-```
-
-
-
-As another example, instead of:
-
-```
- This thing, ([some text](some/path)), is NOT ideal. <=== no thank you
-```
-
-use:
-
-```
- This thing, [some text](some/path), is better.
-```
-
-Jump to: [top](#)
-
-
-
-
-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.
-
-Instead of:
-
-````
-```
- int
- main(int foo)
- {
- return foo;
- }
-```
-C compilers cannot be given a -Wno-main-arg-errors flag. <=== no thank you
-````
-
-use:
-
-````
-```
- int
- main(int foo)
- {
- return foo;
- }
-```
-
-C compilers cannot be given a -Wno-main-arg-errors flag.
-````
-
-**BTW**: Please note the blank line after the code block.
-
-Jump to: [top](#)
-
-
-
-
-## Please do NOT place text on the IMMEDIATE (very next) line after a markdown code block
-
-
-## Please use `_` for italics in markdown
-
+
+## Use `_` for italics in markdown
Please do **NOT** use `*` (single asterisk) for italics in markdown. 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_**.
-For example, instead of:
+```
+✕ *this text is italic*
+✔ _this text is italic_
-```
- *this text is italic* <=== no thank you
+✕ ***this text is bold italic***
+✔ **_this text is bold italic_**
+✔ _**this text is bold italic**_
```
-
-use:
-
-```
- _this text is italic_
-```
-
-Another example, for **_bold italic_**:
-
-Do **NOT** use:
-
-
-```
- ***this text is bold italic*** <=== no thank you
-```
-
-Instead use:
-
-```
- **_this text is bold italic_**
-```
-
-or:
-
-```
- _**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 observe this rule, as
best you can.