MARKUP
author Timm S. Mueller <tmueller@neoscientists.org>
Sun, 29 Apr 2007 14:29:44 +0200
changeset 184 d6dab49fa14a
parent 107 d65bce457645
child 228 4386f52e29fb
permissions -rw-r--r--
Internal links are now always treated lowercase
tmueller@107
     1
tmueller@107
     2
== LOona markup notation ==
tmueller@107
     3
tmueller@123
     4
LOona's text markup is based on indentations and the systematic use
tmueller@123
     5
of text elements that you would expect in good-looking plain text
tmueller@123
     6
documents anyway. Albeit loosely based on the markup notation of
tmueller@123
     7
other, more popular WIKIs, LOona's markup notation has some features
tmueller@123
     8
to offer which recommend it especially for technical documentation.
tmueller@107
     9
tmueller@123
    10
'''NOTE''': To understand these instructions, click on 'Edit' to see
tmueller@123
    11
the plain text representation; use 'Preview' to try out some markup
tmueller@123
    12
of your own.
tmueller@107
    13
tmueller@107
    14
tmueller@107
    15
=== 1. Block ===
tmueller@107
    16
tmueller@107
    17
Text of a consistent indentation level running uninterrupted by empty
tmueller@123
    18
lines is combined into ''blocks''. Lines in blocks can break at any
tmueller@123
    19
position; the line breaks are not included to the result:
tmueller@107
    20
tmueller@107
    21
---------------------------------------------------------------------
tmueller@107
    22
tmueller@107
    23
 This is a block.
tmueller@107
    24
	
tmueller@107
    25
 This is another
tmueller@107
    26
 block.
tmueller@107
    27
	
tmueller@107
    28
---------------------------------------------------------------------
tmueller@107
    29
tmueller@107
    30
tmueller@107
    31
=== 2. Indentation ===
tmueller@107
    32
tmueller@123
    33
''Indentation'' is measured in the consecutive number of spaces at
tmueller@123
    34
the beginning of a line; different indentation levels are taken into
tmueller@107
    35
account accordingly:
tmueller@107
    36
tmueller@107
    37
---------------------------------------------------------------------
tmueller@107
    38
tmueller@107
    39
 This is a block.
tmueller@107
    40
	
tmueller@107
    41
  This is another 
tmueller@107
    42
  block.
tmueller@107
    43
		
tmueller@107
    44
   This is a third
tmueller@107
    45
   block.
tmueller@107
    46
	
tmueller@107
    47
---------------------------------------------------------------------
tmueller@107
    48
tmueller@107
    49
tmueller@107
    50
=== 3. Preformatted text ===
tmueller@107
    51
tmueller@123
    52
For blocks of code and other kinds of ''preformatted text'' use an
tmueller@107
    53
indentation that is ''two levels deeper'' than the current level,
tmueller@107
    54
e.g.:
tmueller@107
    55
tmueller@107
    56
---------------------------------------------------------------------
tmueller@107
    57
tmueller@107
    58
 Normal text
tmueller@107
    59
tmueller@107
    60
   /* Code markup */
tmueller@107
    61
			
tmueller@107
    62
 Back to normal
tmueller@107
    63
	
tmueller@107
    64
---------------------------------------------------------------------
tmueller@107
    65
tmueller@107
    66
tmueller@107
    67
=== 4. Code ===
tmueller@107
    68
tmueller@123
    69
Inlined ''code'' is marked up between double braces. It may occur at
tmueller@123
    70
any position in a line, but it must be the same line in which the
tmueller@123
    71
opening and the closing of the markup occurs:
tmueller@107
    72
tmueller@107
    73
---------------------------------------------------------------------
tmueller@107
    74
tmueller@107
    75
 This is {{code_markup}} in running text.
tmueller@107
    76
	
tmueller@107
    77
---------------------------------------------------------------------
tmueller@107
    78
tmueller@107
    79
tmueller@107
    80
=== 5. Lists ===
tmueller@107
    81
tmueller@123
    82
There are two types of items in ''lists''; ''soft'' and ''bulleted''
tmueller@107
    83
items. They are recognized by their initiatory character (dash or
tmueller@107
    84
asterisk), followed by a whitespace at the beginning of a line:
tmueller@107
    85
tmueller@107
    86
---------------------------------------------------------------------
tmueller@107
    87
tmueller@107
    88
 - soft item
tmueller@107
    89
 * bulleted item
tmueller@107
    90
	
tmueller@107
    91
---------------------------------------------------------------------
tmueller@107
    92
tmueller@107
    93
Soft items are, by the way, a natural means to enforce line breaks:
tmueller@107
    94
tmueller@107
    95
---------------------------------------------------------------------
tmueller@107
    96
tmueller@107
    97
 - this is a line,
tmueller@107
    98
 - this is another line,
tmueller@107
    99
 - this is a third line.
tmueller@107
   100
	
tmueller@107
   101
---------------------------------------------------------------------
tmueller@107
   102
tmueller@107
   103
Lists follow the same indentation rules as normal text:
tmueller@107
   104
tmueller@107
   105
---------------------------------------------------------------------
tmueller@107
   106
		
tmueller@107
   107
 * one
tmueller@107
   108
 * two
tmueller@107
   109
 * three
tmueller@107
   110
  * eins
tmueller@107
   111
  * zwei
tmueller@107
   112
   - ichi
tmueller@107
   113
   - ni
tmueller@107
   114
   - san
tmueller@107
   115
  * drei
tmueller@107
   116
tmueller@107
   117
---------------------------------------------------------------------
tmueller@107
   118
tmueller@107
   119
'''NOTE''': Although not striclty required, it is recommended to
tmueller@107
   120
indent lists by one level. This will help the parser to avoid
tmueller@107
   121
ambiguities; otherwise, when a regular block follows an unindented
tmueller@107
   122
list, it would be concatenated with the last item, as empty lines are
tmueller@107
   123
not sufficient to break out from a list.
tmueller@107
   124
tmueller@107
   125
tmueller@107
   126
=== 6. Images ===
tmueller@107
   127
tmueller@107
   128
Image references are enclosed by at signs:
tmueller@107
   129
tmueller@107
   130
---------------------------------------------------------------------
tmueller@107
   131
tmueller@107
   132
 @@/images/loona.png@@
tmueller@107
   133
tmueller@107
   134
---------------------------------------------------------------------
tmueller@107
   135
tmueller@107
   136
tmueller@107
   137
=== 7. Links ===
tmueller@107
   138
tmueller@107
   139
Links are enclosed in double squared brackets:
tmueller@107
   140
 
tmueller@107
   141
 * [[home]] - 
tmueller@107
   142
 Internal link: Link target is description at the same time.
tmueller@107
   143
 
tmueller@107
   144
 * [[Home page][home]] - 
tmueller@107
   145
 Internal link with description differing from the link target
tmueller@107
   146
 
tmueller@107
   147
 * [[http://loona.neoscientists.org/]] - 
tmueller@107
   148
 External link
tmueller@107
   149
 
tmueller@107
   150
 * [[You know what cool is][http://loona.neoscientists.org/]] -
tmueller@107
   151
 External link with different description
tmueller@107
   152
 
tmueller@107
   153
 * [[@@/images/loona.png@@][http://loona.neoscientists.org/]] - 
tmueller@107
   154
 Image link
tmueller@107
   155
tmueller@107
   156
As for external links, LOona's configuration file offers a global
tmueller@123
   157
option to decide whether external links should open in a new browser
tmueller@123
   158
window or not. (Many people disregard this feature, while businesses
tmueller@123
   159
seem to swear by it.)
tmueller@107
   160
tmueller@107
   161
tmueller@107
   162
=== 8. Tables ===
tmueller@107
   163
tmueller@107
   164
Lines running uninterrupted with at least one cell separator in each
tmueller@107
   165
of them automatically form a table. The cell separator is a double
tmueller@107
   166
vertical bar:
tmueller@107
   167
tmueller@107
   168
---------------------------------------------------------------------
tmueller@107
   169
	
tmueller@107
   170
 First cell || Second cell
tmueller@107
   171
 Third cell || Fourth cell
tmueller@107
   172
	
tmueller@107
   173
---------------------------------------------------------------------
tmueller@107
   174
tmueller@107
   175
It is also possible to create empty cells as long as the separators
tmueller@107
   176
are present. Note, by the way, that cell separators do not
tmueller@107
   177
necessarily need to be aligned exactly below each other:
tmueller@107
   178
tmueller@107
   179
---------------------------------------------------------------------
tmueller@107
   180
	
tmueller@107
   181
 First cell ||  || third cell
tmueller@107
   182
      || fifth cell || 
tmueller@107
   183
	
tmueller@107
   184
---------------------------------------------------------------------
tmueller@107
   185
tmueller@107
   186
tmueller@107
   187
=== 9. Headings ===
tmueller@107
   188
tmueller@107
   189
Headings occupy an entire line. They are enclosed by at least one
tmueller@107
   190
equal sign and a whitspace on each side; the more equal signs, the
tmueller@107
   191
less significant the section:
tmueller@107
   192
tmueller@107
   193
---------------------------------------------------------------------
tmueller@107
   194
 
tmueller@107
   195
 == Heading 1 ==
tmueller@107
   196
			
tmueller@107
   197
 === Heading 2 ===
tmueller@107
   198
	
tmueller@107
   199
 ==== Heading 3 ====
tmueller@107
   200
	
tmueller@107
   201
---------------------------------------------------------------------
tmueller@107
   202
tmueller@107
   203
tmueller@107
   204
=== 10. Rules ===
tmueller@107
   205
tmueller@107
   206
A minimum of four dashes is interpreted as a horizontal rule. Rules
tmueller@107
   207
may occur at arbitrary indentation levels, but otherwise, they must
tmueller@107
   208
occupy the whole line:
tmueller@107
   209
tmueller@107
   210
---------------------------------------------------------------------
tmueller@107
   211
		
tmueller@107
   212
 before the rule
tmueller@107
   213
 ----------------------------------------------
tmueller@107
   214
 after the rule
tmueller@107
   215
tmueller@107
   216
---------------------------------------------------------------------
tmueller@107
   217
tmueller@107
   218
tmueller@107
   219
=== 11. Emphasis ===
tmueller@107
   220
tmueller@107
   221
An emphasized portion of text may occur at any position in a line,
tmueller@107
   222
but the opening and the closing of the markup must occur in the same
tmueller@107
   223
line to be recognized. 
tmueller@107
   224
tmueller@107
   225
The emphasized text is surrounded by at least two ticks on each side;
tmueller@107
   226
the more ticks, the stronger the emphasis.
tmueller@107
   227
tmueller@107
   228
---------------------------------------------------------------------
tmueller@107
   229
tmueller@107
   230
 - normal
tmueller@107
   231
 - ''emphasis''
tmueller@107
   232
 - '''strong emphasis'''
tmueller@107
   233
 - ''''very strong emphasis''''
tmueller@107
   234
tmueller@107
   235
---------------------------------------------------------------------
tmueller@107
   236
tmueller@107
   237
tmueller@107
   238
== Final note ==
tmueller@107
   239
tmueller@107
   240
If in doubt, use fewer markup. Sparse application of compositional
tmueller@107
   241
elements usually leads to better readability and stylistic clarity.
tmueller@123
   242
If you can't produce the looks you project, first and foremost think
tmueller@123
   243
of improving your stylesheet.
tmueller@107
   244
tmueller@107
   245
Ok, for the desperate: There's a single lone hack in LOona's markup
tmueller@107
   246
format which allows you to produce additional padding between
tmueller@107
   247
elements, list items which may appear to be empty, etc. It can come
tmueller@123
   248
to the rescue in some darned situations. It's the non-breaking space;
tmueller@123
   249
produce it either by inserting the character code 160 (see your
tmueller@123
   250
browser or operating system manuals on how to achieve this), or by
tmueller@123
   251
writing the HTML equivalent (' &nbsp; '). (See the plain text
tmueller@123
   252
representation of this document, as it cannot be escaped.)