``` <!---sh-->
-echo "This code block is NOT indented\" <=== no thank you
+``` <!---sh-->
+echo "This code block is NOT indented" <=== no thank you
```
-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"
+We request that you indent the code block by multiples of 4 ASCII SPACES:
+``` <!---sh-->
+ echo "This code block is indented by mutiples of 4 spaces"
# The top level starts with a 4 ASCII space indent.
#
@@ -462,19 +496,23 @@ echo "This code block is NOT indented\" <===
# etc.
```
Moreover:
-```
+```
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 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
+SPACES. Please do NOT indent with ASCII tabs, OR use any
ASCII tab characters anywhere inside a markdown file:
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
@@ -483,7 +521,7 @@ ASCII tab characters anywhere inside a markdown file:
```
And to clarify, we are only talking about markdown files,
not C code or any other non-markdown content:
- printf("Is is fine to use tabs in Obfucated C code.\n");
+ 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,
@@ -491,35 +529,67 @@ not C code or any other non-markdown content:
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.
+
+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:
+ 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 " ...but don't expand tab to spaces.
+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
+or so.
+This will prevent the tab key from inserting tabs; rather it will insert 4
+spaces.
+To VERIFY that there are no tabs in a file you may do, in command mode:
+ /\t
+If you’re in insert mode hit ESC first.
+
+
+Please do NOT directly specify a language for a code block
+
+
+We request that fenced markdown code
+blocks
+NOT specify a language directly.
For example:
-```c <=== no thank you
+```c <=== no thank you
int main(void) {return 0;}
```
Instead, put the language inside an HTML comment, separated from the
markdown code block starting fence by a space:
-``` <!---c-->
+``` <!---c-->
int main(void) {return 0;}
```
-IMPORTANT: The initial ` ` ` must be followed by an ASCII space,
-then by an opening <!---, then by the language, then by a closing -->.
-Please do NOT add trailing slash to HTML elements
+IMPORTANT: The initial ` ` ` 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 “>”).
+
+
+Please do NOT add trailing slash to void HTML elements
+
+
Please do NOT use a trailing slash on void HTML
elements.
See also this note on trailing slashes in void-element start
tags.
The trailing slash on void HTML elements has no effect and interacts badly with
unquoted attribute values.
-For example, please do NOT use:
+For example, please do NOT use:
<br/> <=== no thank you
Instead use just:
<br>
-And for example, please do NOT use:
+And for example, please do NOT use:
<hr/> <=== no thank you
Instead use just:
+ <br>
+and
<hr>
-And for example, please do NOT use:
+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
@@ -528,7 +598,11 @@ unquoted attribute values.
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
+
+
+Please 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 <br>.
@@ -542,8 +616,9 @@ a trailing <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:
-```
+Again, use of a trailing backslash (\) inside a markdown fenced code
+block is fine:
+```
This is OK\
inside a\
markdown code\
@@ -551,11 +626,15 @@ a trailing <br>.
```
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:
 <=== no thank you
-Use an <img ..> HTML element with alt=, width= and length=
+
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"
@@ -567,40 +646,66 @@ attributes:
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
+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
+
+
+
+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.
+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 <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 markdown links in “))”
-Please do NOT end a markdown links with a double closed parenthesis “))”.
-Markdown links that end in “))” complicate parsing and sometimes lead
+
+Please do NOT end markdown links with “))”
+
+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
-Use:
+use:
[some text](https://example.com/foo_(bar))
-Instead of:
+As another example, instead of:
This thing, ([some text](some/path)), is NOT ideal. <=== no thank you
-Use:
+use:
This thing, [some text](some/path), is better.
-Please do NOT place text on the next line after a markdown code block
+
+Please do NOT put a LITERAL “(” or “)” in markdown link titles
+
+Please do NOT use literal parentheses inside markdown link titles.
+Instead of:
+ [some (text)](https://example.com/cyrds) <=== no thank you
+use:
+ [some (text)](https://example.com/cyrds)
+Instead of:
+ [ls(1)](https://example.com/ls-man-page.1) <=== no thank you
+use:
+ [ls(1)](https://example.com/ls-man-page.1)
+
+
+
+Please do NOT place text on the IMMEDIATE (very 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
-NOT properly indented.
+NOT properly indented.
Instead of:
-```
+```
int
main(int foo)
{
@@ -608,8 +713,8 @@ NOT properly indented.
}
```
C compilers cannot be given a -Wno-main-arg-errors flag. <=== no thank you
-Use:
-```
+use:
+```
int
main(int foo)
{
@@ -619,16 +724,24 @@ C compilers cannot be given a -Wno-main-arg-errors flag. <=== no thank y
C compilers cannot be given a -Wno-main-arg-errors flag.
BTW: Please note the blank line after the code block.
-Please do NOT put “(”s or “)”s in markdown link titles
-Please do NOT use literal parentheses inside the markdown link titles.
-Instead of:
- [some (text)](https://example.com/cyrds) <=== no thank you
-Use:
- [some (text)](https://example.com/cyrds)
-Instead of:
- [ls(1)](https://example.com/ls-man-page.1) <=== no thank you
-Use:
- [ls(1)](https://example.com/ls-man-page.1)
+
+Please 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* <=== no thank you
+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**_
diff --git a/markdown.md b/markdown.md
index f79e76992..562664e01 100644
--- a/markdown.md
+++ b/markdown.md
@@ -1,4 +1,6 @@
+
# IOCCC markdown guidelines
+
The IOCCC makes extensive use of [markdown](https://daringfireball.net/projects/markdown/).
For example, when submitting to the IOCCC
@@ -22,11 +24,15 @@ In particular there are things we ask people to please **NOT** use in
markdown files for the IOCCC:
-## Please do NOT use name attributes in HTML `` hyperlink elements
+
+
+## Please do NOT use the `name` attributes in HTML `...` hyperlink elements
+
+
Please do **NOT** use the HTML construct:
-```
+```
... <=== no thank you
```
@@ -34,7 +40,7 @@ as those are **NOT** part of the HTML 5 standard.
Instead use:
-```
+```
...
```
@@ -43,69 +49,108 @@ encapsulates the HTML you want to name: i.e., the target of some
`` or some other ``
for the given page URL.
-There are certain HTML Elements that cannot have internal `...`.
+### IMPORTANT POINT:
-For example:
+There are certain markdown constructs that **CANNOT** have an **internal** `...` element.
-```
+An example is headings (lines that start with a `#`). For example:
+
+
+```
# THIS WILL NOT WORK! <=== this will not work
```
-For things like headings, you have to surround them, as in:
+For things like headings, you have to surround them with the `...` element, as in:
-```
+```
# This will work
```
While some browsers will still recognize the HTML construct `...`, it is possible they might NOT in the future.
+name="string">...`, it is possible **they MIGHT NOT** in the future.
-## Please do NOT use the `` or the `` HTML element
+
+## If you can, it is PREFERABLE to use markdown links rather than `...`
+
-Please do NOT use the obsolete `` or the obsolete `` (_strikeout_) HTML elements:
+It is easier and preferred to use markdown links rather than HTML `..`
+anchors.
+Instead of:
+
+
+```
+ Use of
+
+## Please do NOT use the `` or the `` HTML element
+
+
+
+Please do **NOT** use the obsolete `` or the obsolete ``
+(**strikeout**) HTML elements:
+
+```
... <=== no thank you
... <=== no thank you
```
Use instead:
-```
+```
...
```
+
+
## Please do NOT use the `` HTML element
+
+
-Please NOT use the obsolete `` (_underline_) HTML element:
+Please **NOT** use the obsolete `` (_underline_) HTML element:
-```
+```
... <=== no thank you
```
Use instead:
-```
+```
...
```
+
+
## Please do NOT use the `` HTML element
+
+
-Please do **NOT** use the obsolete `` (_teletype_) HTML element:
+Please do **NOT** use the obsolete ``
+(**teletype**) HTML element:
-```
- The obsolete tt element is obsolete <=== no thank you
+```
+ The tt element is obsolete <=== no thank you
```
-Instead use either a monospaced span:
+Instead use either a monospaced `` or an inline markdown code block:
-```
+```
Use of a monospaced font
is one option,
however ...
@@ -113,28 +158,32 @@ Instead use either a monospaced span:
We recommend using the inline markdown code block method instead:
-```
- Using the `inline markdown code block` is easier and is `preferred`.
+```
+ 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.
+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
+echo "This code block is NOT indented" <=== no thank you
```
````
-We request that you indent the code block by multiples of 4 ASCII spaces:
+We request that you indent the code block by multiples of 4 ASCII **SPACES**:
-````
+````
``` <%%NO_COMMENT%%!---sh-->
- echo "This code block is intended by mutiples of 4 spaces"
+ echo "This code block is indented by mutiples of 4 spaces"
# The top level starts with a 4 ASCII space indent.
#
@@ -147,7 +196,7 @@ We request that you indent the code block by multiples of 4 ASCII spaces:
Moreover:
-````
+````
```
The same thing applies to any markdown block surrounded by ``` lines.
```
@@ -156,19 +205,23 @@ Moreover:
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
+**SPACES**. Please do **NOT** indent with ASCII tabs, **OR** use any
ASCII tab characters anywhere inside a markdown file:
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
@@ -181,8 +234,8 @@ For example:
And to clarify, we are only talking about markdown files,
not C code or any other non-markdown content:
-````
- printf("Is is fine to use tabs in Obfucated C code.\n");
+````
+ 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,
@@ -193,14 +246,54 @@ not C code or any other non-markdown content:
your C code and other non-markdown files. We simply ask that you **NOT** use any
ASCII tab characters in markdown files.
+
+### Tip for `vim` users
+
-## Please do NOT specify a language for a code block
+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:
-We request that (fenced) markdown code blocks **NOT** specify a language.
+```
+ 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 " ...but don't expand tab to spaces.
+```
+
+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
+```
+
+or so.
+
+This will prevent the tab key from inserting tabs; rather it will insert 4
+spaces.
+
+To **VERIFY** that there are no tabs in a file you may do, in command mode:
+
+```
+ /\t
+```
+
+If you're in insert mode hit `ESC` first.
+
+
+
+
+## Please do NOT _directly_ specify a language for a code block
+
+
+
+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
int main(void) {return 0;}
```
@@ -209,18 +302,24 @@ For example:
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`**,
-then by an **opening** **``**.
+**IMPORTANT**: The **initial** **\` \` \`** must be followed by an **ASCII SPACE**,
+and **THEN** an **opening** **``" (two "`-`"s
+followed by a "`>`").
-## Please do NOT add trailing slash to HTML elements
+
+
+## Please do NOT add trailing slash to void HTML elements
+
+
Please do **NOT** use a trailing slash on [void HTML
elements](https://github.com/validator/validator/wiki/Markup-»-Void-elements).
@@ -231,33 +330,39 @@ tags](https://github.com/validator/validator/wiki/Markup-»-Void-elements#traili
The trailing slash on void HTML elements has no effect and interacts badly with
unquoted attribute values.
-For example, please do NOT use:
+For example, please do **NOT** use:
-```
+```
<=== no thank you
```
Instead use just:
-```
+```
```
-And for example, please do NOT use:
+And for example, please do **NOT** use:
-```
+```
<=== no thank you
```
Instead use just:
+```
+
```
+
+and
+
+```
```
-And for example, please do NOT use:
+And for example, please do **NOT** use:
-```
+```
<=== no thank you
@@ -265,7 +370,7 @@ And for example, please do NOT use:
Instead use just:
-```
+```
@@ -274,7 +379,11 @@ Instead use just:
etc.
-## Please do NOT use trailing backslash outside of a code block
+
+
+## Please 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
@@ -282,7 +391,7 @@ a trailing `
`.
Instead of:
-```
+```
In markdown,\ <=== no thank you
do NOT use trailing\
backslashes outside of\
@@ -291,16 +400,17 @@ Instead of:
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:
+Again, use of a trailing backslash (`\`) inside a markdown [**fenced code
+block**](https://www.markdownguide.org/extended-syntax/#fenced-code-blocks) is fine:
-````
+````
```
This is OK\
inside a\
@@ -313,20 +423,24 @@ 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:
-```
+```
 <=== no thank you
```
-Use an `![]()
` HTML element with `alt=`, `width=` and `length=`
+Use an `![]()
` HTML element with `alt=`, `width=` and `length=`
attributes:
-```
+```
@@ -334,91 +448,136 @@ attributes:
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
+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
+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 causes `pandoc(1)` to generate `
`. 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:
-```
+```
```
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 "))".
+
+## Please do NOT end markdown links with "`))`"
+
-Markdown links that end in "))" complicate parsing and sometimes lead
+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
```
-Use:
+use:
-```
+```
[some text](https://example.com/foo_(bar))
```
-Instead of:
+As another example, instead of:
-```
+```
This thing, ([some text](some/path)), is NOT ideal. <=== no thank you
```
-Use:
+use:
-```
+```
This thing, [some text](some/path), is better.
```
-## Please do NOT place text on the next line after a markdown code block
+
+## Please do NOT put a LITERAL "`(`" or "`)`" in markdown link titles
+
+
+Please do **NOT** use literal parentheses inside markdown link titles.
+
+Instead of:
+
+```
+ [some (text)](https://example.com/cyrds) <=== no thank you
+```
+
+use:
+
+```
+ [some (text)](https://example.com/cyrds)
+```
+
+Instead of:
+
+```
+ [ls(1)](https://example.com/ls-man-page.1) <=== no thank you
+```
+
+use:
+
+```
+ [ls(1)](https://example.com/ls-man-page.1)
+```
+
+
+
+
+## Please do NOT place text on the IMMEDIATE (very 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
-NOT properly indented.
+**NOT** properly indented.
Instead of:
-````
+````
```
int
main(int foo)
@@ -429,9 +588,9 @@ Instead of:
C compilers cannot be given a -Wno-main-arg-errors flag. <=== no thank you
````
-Use:
+use:
-````
+````
```
int
main(int foo)
@@ -446,30 +605,45 @@ C compilers cannot be given a -Wno-main-arg-errors flag.
**BTW**: Please note the blank line after the code block.
-## Please do NOT put "("s or ")"s in markdown link titles
+
+## Please use `_` for italics in markdown
+
-Please do **NOT** use literal parentheses inside the markdown link titles.
+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_**.
-Instead of:
+For example, instead of:
-```
- [some (text)](https://example.com/cyrds) <=== no thank you
+```
+ *this text is italic* <=== no thank you
```
-Use:
+use:
-```
- [some (text)](https://example.com/cyrds)
+```
+ _this text is italic_
```
-Instead of:
+Another example, for **_bold italic_**:
-```
- [ls(1)](https://example.com/ls-man-page.1) <=== no thank you
+Do **NOT** use:
+
+
+```
+ ***this text is bold italic*** <=== no thank you
```
-Use:
+Instead use:
+```
+ **_this text is bold italic_**
```
- [ls(1)](https://example.com/ls-man-page.1)
+
+or:
+
+```
+ _**this text is bold italic**_
```
+