Author: Raimo Niskanen <raimo(at)erlang(dot)org>
Status: Active
Type: Process
Created: 31-Mar-2010
Post-History:
Replaces: 2, 3

EEP 33: Sample Markdown EEP Template

Abstract

This EEP provides a boilerplate or sample template for creating your own Markdown EEPs. In conjunction with the content guidelines in EEP 1, this should make it easy for you to conform your own EEPs to the format outlined below.

Note: if you are reading this EEP via the web, you should first grab the plaintext source of this EEP in order to complete the steps below. DO NOT USE THE HTML FILE AS YOUR TEMPLATE!

This document is based on PEP 9.

Rationale

EEP submissions come in a wide variety of forms, not all adhering to the format guidelines set forth below. Use this template, in conjunction with the content guidelines in EEP 1, to ensure that your EEP submission won't get automatically rejected because of form.

How to Use This Template

To use this template you must first decide whether your EEP is going to be an Process or Standards Track EEP. Most EEPs are Standards Track because they propose a new feature for the Erlang language or standard library. When in doubt, read EEP 1 for details or contact the EEP editors eeps@erlang.org.

Once you've decided which type of EEP yours is going to be, follow the directions below.

Markdown EEP Formatting Requirements

See the Markdown Syntax for general formatting syntax. On top of this Markdown EEPs has these requirements:

The first lines of the EEP is for EEP index generator parsing and the Markdow preprocessing so it must look like the first 10 lines of this file, with that specific style of horizontal rule and header 2 title. Your EEP may have more or less header lines.

EEP toplevel headings are type H1 i.e ==== underlined. The initial letter of each word must be capitalized as in book titles.

Acronyms should be in all capitals.

Code samples inside sections should be indented 4 spaces.

You must use three blank lines before all H1 headings, and two before all H2 headings.

You must adhere to the Emacs convention of adding two spaces at the end of every sentence. You should fill your paragraphs to column 70, but under no circumstances should your lines extend past column 79. If your code samples spill over column 79, you should rewrite them.

Tab characters must never appear in the document at all.

When referencing an external web page in the body of an EEP, you should include the title of the page in the text, with a footnote reference to the URL. Do not include the URL in the body text of the EEP. E.g:

Refer to the [Erlang Language web site][1] for more details.

:

[1]: http://www.erlang.org
    "Erlang Programming Language"

Footnote reference definitions should be placed second last in the document, right before the "Copyright" section and the Emacs magic. Note that these references are invisible in the by Markdown generated HTML.

When referring to another EEP, include the EEP number in the body text using an implicit link name footnote, such as [EEP 1][]. The title may optionally appear. The footnote body should include the EEP's title and author, and it should refer to its URL.

NOTE: The URL is relative to the current URL and the build tools will fix it to point to the .html file.

Example:

Refer to [EEP 1][] for more information about EEP style

:

[EEP 1]: eep-0001.md
    "EEP 1, EEP Purpose and Guidelines, Gustafsson"

EEP numbers in URLs must be padded with zeros from the left, so as to be exactly 4 characters wide, however EEP numbers in the text are never padded.

Copyright

This document has been placed in the public domain.