aboutsummaryrefslogtreecommitdiff
path: root/README
diff options
context:
space:
mode:
Diffstat (limited to 'README')
-rw-r--r--README132
1 files changed, 132 insertions, 0 deletions
diff --git a/README b/README
new file mode 100644
index 0000000..950d98a
--- /dev/null
+++ b/README
@@ -0,0 +1,132 @@
+Em is a limited hypertext markup language.
+
+It is similar to Markdown, but it has a few key advantages:
+
+ 1. It is more readable.
+ 2. It is simpler to parse.
+ 3. There is *not* more than one way to do it (sorry Larry).
+
+Em takes plain-text readability seriously. You should be able to
+write em in a plain-text e-mail message without the recipient noticing.
+
+Em is implemented as a portable awk script, whose simplicity speaks
+for the benefits of em.
+
+== Syntax ==
+
+=== Block-level formatting ===
+
+*A single empty line* always marks a block break. There is
+no exception to this rule. The line is removed in the final output.
+
+All blocks support inline formatting, except headings,
+preformatted blocks and terms in definition lists.
+
+One block cannot be put within another block. For example,
+it is impossible to put a paragraph or a preformatted block
+inside a list item. If you want paragraph lists, just use paragraphs:
+
+ 1. Lorem ipsum dolor sit amet, consectetur adipiscing elit,
+ sed do eiusmod tempor incididunt ut labore et dolore
+ magna aliqua.
+
+ 2. Ut enim ad minim veniam, quis nostrud exercitation
+ ullamco laboris nisi ut aliquip ex ea commodo consequat.
+
+==== Headings ====
+
+Headings begin and end with the same number of equal signs:
+
+ = First-level heading =
+
+ == Second-level heading ==
+
+==== Lists ====
+
+Lists start with a single space. There are four types of lists:
+
+ - This is an unordered list
+ - With two items
+
+ 1. This is an ordered list
+ 2. With an item that spans
+ two lines
+
+ this is: a definition list
+
+ [1] This is a reference list
+ [2] With two items
+
+Unordered and ordered lists can be nested. An additional space
+at the beginning of the line increases the item level by one:
+
+ - First level
+ - Second level
+ - First level
+
+A reference list is a special type of list, unique to em. It is a
+type of footnote list, to which you can make inline referencess
+like this:
+
+ See footnote [1].
+
+There is a special type of reference list item called a *hyperlink
+reference*. It contains only a single word, without whitespace:
+
+ [1] http://example.com
+
+Hyperlink reference items are removed in the final output,
+but you can still reference them inline:
+
+ You can download the file here [1].
+
+==== Preformatted blocks ====
+
+Preformatted blocks start with a single tab:
+
+ #include <stdio.h>
+ main() { puts("Hello world!\n"); }
+
+==== Paragraphs ====
+
+Paragraphs start with no space:
+
+ This is a paragraph
+ with two lines.
+
+ This is another paragraph.
+
+=== Inline formatting ===
+
+_Italic, bold and teletype text_ is marked with the asterisk,
+the underscore and the backtick, respectively:
+
+ Example of *italic* text.
+
+The marks are only valid in certain positions:
+
+ 1. At word borders
+ 2. After an opening parenthesis
+ 3. Before any of `.,:;?!)`
+ 4. Before a closing parenthesis any of `.,:;?!`
+
+_Inline references_ are created with square brackets:
+
+ Example of an inline reference [12].
+
+They are valid in positions 1, 3 and 4.
+
+When referencing a hyperlink reference (see above),
+the reference is replaced with a link. For example:
+
+ It is available for download [1].
+
+ [1] v1.tgz
+
+translates into the following HTML:
+
+ <p>It is available for download (<a href="v1.tgz">link</a>).
+ </p>
+
+The default link text ("link") can be changed by setting
+the `linktext` environment variable.