ioccc/markdown.md

IOCCC markdown guidelines

The IOCCC makes extensive use of markdown. For example, when submitting to the IOCCC, we have people submit remarks about their entry in markdown format. Every winning IOCCC entry uses a README.md markdown file as the basis for forming the index.html web page for that entry. All generated HTML pages on the Official IOCCC website start with some markdown content.

See the markdown syntax guide. See also the CommonMark Spec.

Nevertheless, the IOCCC does have certain practices that we ask authors to follow. Some of these relate to use of markdown directly and others relate to injecting HTML into the markdown file.

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 <a ..> hyperlink elements

Please do NOT use the HTML construct:

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

as those are NOT part of the HTML 5 standard.

Instead use:

    <div id="string">...</div>

where the ... is the HTML you want to "name". The <div> 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:

    # <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.

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

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

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

Use instead:

    <del>...</del>

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>

Or better and easier still, use an inline markdown code block:

    `inline markdown code block is easier and much better`

Please do NOT use unindented code blocks

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

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

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

```
    This code block
    is indented 4 spaces
```

One exception is where change bars are needed, such as those used in next/rules.md and in next/guidelines.md.

For example, next/guidelines.md uses this markdown code block:

```
    main() {
|       void please_do_not_submit_this() {
|           printf("The machine that goes BING!\n");
        }
|       please_do_not_submit_this();
    }
```

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

Instead use just:

    <br>

And for example, please do NOT use:

    <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

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 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 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))

Instead of:

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

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 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.

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

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)