« back to all changes in this revision
Viewing changes to markup.txt
- browse files at revision 1
- compare with another revision
- download diff
- download tarball
- view history from revision 1
- Committer: michael.owens at linterra
- Date: 2008-11-19 17:49:21 UTC
- Revision ID: michael.owens@linterra.org-20081119174921-5rh22x5qdh6ltf4o
Initial submission.
- files added:
- Src
added
removed
markup.txt
1
Markup of Nyctergatis Markup Engine
2
3
Text with markup is plain text with a few character sequences which
4
are recognized by the markup processor and change the format of the
5
result. The result is styled text with titles, paragraphs with
6
justification, bold and italic faces, etc.
7
8
There are two kinds of markup constructs: blocks and inline. Blocks
9
are paragraphs (indented or not), headings, list items, table cells,
10
horizontal rules and block extensions. Inline constructs are
11
character styles, verbatim text and links; they are part of blocks.
12
Except in preformatted blocks, sequences of spaces or tabs are
13
replaced with single spaces.
14
15
Paragraphs
16
17
Paragraphs are made of lines whose first character is not one of
18
*#:;= nor sequence {{{, ----, or <<<. Lines can begin with sequences
19
** and ##.
20
21
Paragraphs end with blank lines or next heading, list, table,
22
indented paragraph, preformatted block of text, horizontal rule or
23
block extension. They can contain styled text, links, spans of
24
verbatim text, and inline extensions.
25
26
Example
27
28
This is a paragraph
29
written in two lines.
30
31
This is another paragraph.
32
33
Indenting
34
35
Indented paragraphs are paragraphs which begin with a colon. Multiple
36
colons define the level of indenting. Indented paragraphs can contain
37
styled text, links, spans of verbatim text, and inline extensions.
38
39
Example
40
41
This is a normal paragraph.
42
:This is an indented
43
paragraph in two lines.
44
::This is more indented.
45
46
Headings
47
48
Headings are made of a single line beginning with an equal character.
49
The number of equal characters defines the level of title, from main
50
title (=) to sub-sub-subtitle (====). Headings may end with a
51
sequence of equal characters.
52
53
Examples
54
55
=Level 1 heading=
56
Paragraph
57
=Another level 1 heading, without trailing equal character
58
==Level 2 heading==
59
===Level 3 heading===
60
61
Lists
62
63
Lists are collections of items. There are three kinds of lists:
64
unnumbered lists, numbered lists, and definition lists. Lists can be
65
nested; they end with the next heading, indented paragraph, table, or
66
blank line.
67
68
Unnumbered lists are represented as indented paragraphs with a
69
bullet. Each item begins with a star character (*); it can span
70
multiple lines.
71
72
Numbered lists are represented as indented paragraphs with a number.
73
Items are numbered automatically with consecutive integers starting
74
at 1. Each item begins with a sharp character (#); it can span
75
multiple lines.
76
77
Definition lists are made of two kinds of items: title, typically
78
displayed in bold font, and definition, typically displayed indented.
79
Titles begin with a semicolon at the beginning of a line. Definitions
80
either follow the title, separated with a colon; or they begin on a
81
new line beginning with a colon.
82
83
List nesting can combine different kinds of lists. Sublist items
84
begin with multiple markers, the first one(s) corresponding to the
85
enclosing list(s). For instance, items of an unnumbered list nested
86
in a numbered list should start with #* at the beginning of the line,
87
without any preceding space. List markers must be used in a
88
consistent way; for example, ## at the beginning of a line in an
89
unnumbered list is not interpreted as a second-level numbered list
90
item, but as monospace style (see below).
91
92
Examples
93
94
* First item of unnumbered list.
95
* Second
96
item, in two lines.
97
*Third item without space (spaces are optional).
98
99
# First item of numbered list.
100
# Second item.
101
#* First item on unnumbered sublist.
102
#* Second item.
103
# Thirst item of top-level numbered list.
104
105
; First title of definition list
106
: Definition of first item.
107
; Second title: Second definition
108
beginning on the same line.
109
110
Paragraph separated with a blank line.
111
112
Tables
113
114
Tables are rectangular array of cells. They are made of one line per
115
row. Each cell begins with character |. Heading cells (typically
116
displayed in bold face) begin with |=. Rows may end with a trailing
117
|.
118
119
Example
120
121
In the table below, the first row and the first column contain
122
headings. The very first cell is empty.
123
124
||=First column|=Second column
125
|=First row|Cell 1,1|Cell 1,2
126
|=Second row|Cell 2,1|Cell 2,2
127
128
Preformatted
129
130
Preformatted text is a block of text displayed literally, including
131
line feeds. Preformatted text is preceded with a line containing {{{
132
and is followed by a line containing }}}.
133
134
Example
135
136
This is some C code:
137
{{{
138
double f(double x)
139
{
140
return 2 * x; // f(x) = 2x
141
}
142
}}}
143
144
In preformatted text, lines which begin with }}}, with leading spaces
145
or not, must have an additional space which is discarded in the
146
output.
147
148
Horizontal rules
149
150
Horizontal rules are single lines containing four hyphens.
151
152
Example
153
154
Paragraph.
155
----
156
Paragraph following a horizontal rule.
157
158
Extensions
159
160
Sequences << and <<< are reserved for extensions.
161
162
Character style
163
164
Inside paragraphs, indented paragraphs, headings, list elements, and
165
table cells, the following two-character sequences toggle on or off
166
the corresponding style. It is not mandatory to nest spans of styled
167
characters between matching style sequences. Style is reset at the
168
end of text block.
169
170
Markup Style
171
** Bold
172
// Italic
173
## Monospace
174
,, (two commas) Subscript
175
^^ Superscript
176
__ (two underscores) Underlined
177
178
Double stars and double sharps are interpreted as the beginning of
179
list items when they are the first characters of a line in the
180
context of lists. To be interpreted as style markup, they can be
181
preceded by a space.
182
183
Example
184
185
This is //italic text//, **bold text**,
186
and //**bold italic text**//.
187
188
Escape character
189
190
The tilde character, when followed by any character except space, tab
191
or line feed, is an escape character; it is not displayed and the
192
next character loses its special meaning, if any.
193
194
Example
195
196
Two stars: ~*~* or ~** or *~*; tilde: ~~.
197
198
is rendered as "Two stars: ** or ** or **; tilde: ~."
199
200
Verbatim
201
202
Verbatim text is a sequence of characters enclosed between {{{ and
203
}}}. After {{{, all characters are output verbatim, without any
204
markup interpreting, until the next }}} or the end of text block.
205
Multiple spaces and tabs and single line feeds are still converted to
206
single spaces, though. Verbatim text is an alternative to the escape
207
character; it is more convenient for sequences of characters.
208
209
Example
210
211
{{{**}}} //{{{{{{xx}}}}}}//
212
213
is rendered as "** {{{xx}}}".
214
215
Line break
216
217
Except in preformatted blocks, line breaks are not preserved. The
218
sequence \\ forces a line break.
219
220
Example
221
222
The next line of this paragraph begins...\\here!
223
224
Links
225
226
Hypertext links (URLs) are enclosed between [[ and ]]. The text
227
displayed as the link is either the same as the URL itself if there
228
is no | character, or it is what follows |. No markup is recognized
229
in the URL part; what follows | can contain styled text and verbatim
230
text. Spaces surrounding | are ignored.
231
232
Examples
233
234
* Simple link: [[http://www.calerga.com]]
235
* Link with link text: [[http://www.calerga.com | Calerga]]
236
* Link with styled link text: [[http://www.calerga.com | **Calerga**]]
237
238
----------
239
240
Copyright Yves Piguet, 24 October 2007 May be distributed with NME or
241
cited with proper attribution.
242
Loggerhead is a web-based interface for Breezy
Version: 2.0.1