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