MARKUP
author Timm S. Mueller <tmueller@neoscientists.org>
Fri, 24 Oct 2008 01:35:27 +0200
changeset 251 2de5931b723d
parent 230 b12ab7d9c276
permissions -rw-r--r--
tek.os.posix has been moved to tek.lib.posix, module initialization procedure
simplified, added statvfs() under Linux
tmueller@107
     1
tmueller@228
     2
==( Overview : LOona markup notation )==
tmueller@107
     3
tmueller@123
     4
LOona's text markup is based on indentations and the systematic use
tmueller@228
     5
of text elements that you would also expect in good-looking plain
tmueller@228
     6
text documentation. 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@228
    15
===( 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@241
    19
position; the line breaks are not included in the result:
tmueller@107
    20
tmueller@107
    21
---------------------------------------------------------------------
tmueller@107
    22
tmueller@107
    23
 This is a block.
tmueller@228
    24
tmueller@107
    25
 This is another
tmueller@107
    26
 block.
tmueller@228
    27
tmueller@107
    28
---------------------------------------------------------------------
tmueller@107
    29
tmueller@107
    30
tmueller@228
    31
===( 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@228
    40
tmueller@228
    41
  This is another
tmueller@107
    42
  block.
tmueller@228
    43
tmueller@107
    44
   This is a third
tmueller@107
    45
   block.
tmueller@228
    46
tmueller@107
    47
---------------------------------------------------------------------
tmueller@107
    48
tmueller@107
    49
tmueller@228
    50
===( Preformatted )===
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@228
    61
tmueller@107
    62
 Back to normal
tmueller@228
    63
tmueller@107
    64
---------------------------------------------------------------------
tmueller@107
    65
tmueller@107
    66
tmueller@228
    67
===( 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@228
    76
tmueller@107
    77
---------------------------------------------------------------------
tmueller@107
    78
tmueller@107
    79
tmueller@228
    80
===( 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@228
    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@228
   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@228
   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@228
   126
===( 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@228
   137
===( Links )===
tmueller@107
   138
tmueller@107
   139
Links are enclosed in double squared brackets:
tmueller@228
   140
tmueller@228
   141
 * [[home]] -
tmueller@107
   142
 Internal link: Link target is description at the same time.
tmueller@228
   143
tmueller@228
   144
 * [[Home page][home]] -
tmueller@107
   145
 Internal link with description differing from the link target
tmueller@228
   146
tmueller@228
   147
 * [[http://loona.neoscientists.org/]] -
tmueller@107
   148
 External link
tmueller@228
   149
tmueller@107
   150
 * [[You know what cool is][http://loona.neoscientists.org/]] -
tmueller@107
   151
 External link with different description
tmueller@228
   152
tmueller@228
   153
 * [[@@/images/loona.png@@][http://loona.neoscientists.org/]] -
tmueller@107
   154
 Image link
tmueller@107
   155
tmueller@241
   156
As for external links, LOona's configuration file offers an option
tmueller@241
   157
to decide whether external links should open in a new browser window
tmueller@241
   158
or not. Many people disregard this feature, while businesses seem
tmueller@241
   159
to swear by it.
tmueller@107
   160
tmueller@107
   161
tmueller@228
   162
===( 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@228
   169
tmueller@107
   170
 First cell || Second cell
tmueller@107
   171
 Third cell || Fourth cell
tmueller@228
   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@241
   177
necessarily have to be aligned exactly below each other:
tmueller@107
   178
tmueller@107
   179
---------------------------------------------------------------------
tmueller@228
   180
tmueller@107
   181
 First cell ||  || third cell
tmueller@228
   182
      || fifth cell ||
tmueller@228
   183
tmueller@107
   184
---------------------------------------------------------------------
tmueller@107
   185
tmueller@107
   186
tmueller@228
   187
===( 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@228
   194
tmueller@107
   195
 == Heading 1 ==
tmueller@228
   196
tmueller@107
   197
 === Heading 2 ===
tmueller@228
   198
tmueller@107
   199
 ==== Heading 3 ====
tmueller@228
   200
tmueller@107
   201
---------------------------------------------------------------------
tmueller@107
   202
tmueller@107
   203
tmueller@228
   204
===( Rules )===
tmueller@107
   205
tmueller@107
   206
A minimum of four dashes is interpreted as a horizontal rule. Rules
tmueller@241
   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@228
   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@228
   219
===( 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@228
   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@228
   238
===( Nodes )===
tmueller@228
   239
tmueller@228
   240
''Nodes'' translate to anchors in a document, and a browser will
tmueller@228
   241
usually interprete them as jump targets. Visually, nodes translate
tmueller@228
   242
to headlines also; as usual, the number of equal signs with which
tmueller@241
   243
the heading is paired determines the significance and therefore
tmueller@228
   244
size of a headline:
tmueller@228
   245
tmueller@228
   246
---------------------------------------------------------------------
tmueller@228
   247
tmueller@228
   248
 =( Large )=
tmueller@228
   249
 ==( Medium )==
tmueller@228
   250
 ===( Small : Small node with alternate text )===
tmueller@228
   251
tmueller@228
   252
---------------------------------------------------------------------
tmueller@228
   253
tmueller@241
   254
In addition to normal node headlines, there is also a variant which
tmueller@241
   255
is marked up as code. This is especially useful for jump targets in
tmueller@241
   256
technical documentation:
tmueller@228
   257
tmueller@228
   258
---------------------------------------------------------------------
tmueller@228
   259
tmueller@228
   260
 ={ Large : Large code node }=
tmueller@230
   261
 =={ Medium : Medium code node }==
tmueller@228
   262
 ==={ Small : Small code node }===
tmueller@228
   263
tmueller@228
   264
---------------------------------------------------------------------
tmueller@228
   265
tmueller@228
   266
When referencing a node, use a number sign {{#}} followed by the
tmueller@241
   267
node name. This, by the way, also works when referencing nodes in
tmueller@230
   268
other documents.
tmueller@228
   269
tmueller@228
   270
For example, this link will take you to the beginning of this
tmueller@228
   271
document:
tmueller@228
   272
tmueller@228
   273
---------------------------------------------------------------------
tmueller@228
   274
tmueller@230
   275
 [[Top of document][#Overview]]
tmueller@228
   276
tmueller@228
   277
---------------------------------------------------------------------
tmueller@228
   278
tmueller@228
   279
'''NOTE''': Don't be too adventurous when selecting a node name;
tmueller@241
   280
if you need blanks or punctuation or if in doubt use the alternate
tmueller@228
   281
text notation.
tmueller@228
   282
tmueller@228
   283
tmueller@107
   284
== Final note ==
tmueller@107
   285
tmueller@107
   286
If in doubt, use fewer markup. Sparse application of compositional
tmueller@107
   287
elements usually leads to better readability and stylistic clarity.
tmueller@123
   288
If you can't produce the looks you project, first and foremost think
tmueller@123
   289
of improving your stylesheet.