wiki:MarkupSyntax
Last modified 4 years ago Last modified on 06.04.2015 00:52:17

Dashmarkup syntax

Following syntax is converted by parser to syntax tree, which is stored in database (for performance reasons, but also for preserving compatibility in case of changes in markup grammar).

Structure of syntax tree (list of node types and meaning of their children) is here: SyntaxTree.

in-line formatting

Backslash \ removes special meaning (if any) of any character directly after it. To have literal backslash in text, you need to double this character. Characters without special meaning that were preceded by \ are preserved as is (although backslash itself is removed).

font

  • bold: **bold**
  • italic: __italic__
  • strikeout: ~~strikeout~~
  • fixed width font: {{fixed width font}}

links and images

  • link to different wiki page: [[SomeWikiPage]]
    • link with description: [[SomeWikiPage some wiki page with description]]
  • link to external resource: [[http://www.example.net/]]
    • link with description: [[http://www.example.net/ link to example.net]]
  • inserting image: [[!/some/where.png]]
    • URL to image may be relative, absolute or with full protocol/host specification (the same options as with link)
  • link description may be a single image: [[StronaWiki [[!/somewhere/foo.png]]]]

macros

See Macros for explaination what are the macros.

  • macro call: [[@list_of_servers]]
    • inserting macro's return value second time (macro recall): $list_of_servers or ${list_of_servers} (useful for italic font)
  • macro call with parameter:
    • [[@server_status "onyx.example.net"]]
    • [[@free_disk_space $list_of_servers, "/"]]
    • supported paramter syntax:
      • number (integer or real) -?([1-9][0-9]*|0)(\.[0-9]+)?([eE][+-]?[0-9]+)?
      • string "([^\\"\n]|\\.)*"
      • macro recall \$[a-zA-Z_][a-zA-Z0-9_]*
      • macro call is unsupported -- for this there is a special syntax of silenced macro call
  • silenced macro call -- without inserting returned value in place of call (the value is still accessible using $foo): [[@@foo]]
  • macro call that can be recalled under a different name
    • [[@extract_json#date $server_status, "date"]] (recalled by $date, not by $extract_json)
    • mainly useful if there are several calls to the same macro, and one of them should be used further in argument to another call
  • special, pre-defined macros:
    • $page_name -- name of displayed wiki page
    • $page_param -- parameter to wiki page (if page name ends with slash /, all text after it is considered a parameter)
      • parametrized dashboard ServerStatus/
      • dashboard has defined layout for server, which name is passed in $page_param
      • page ServerStatus/onyx.atled.pl displays status for server onyx.atled.pl

block formatting

Similarly to in-line formatting, \ removes any special meaning from a single character.

comments

# Comments start with "#" character.
# Comments are not displayed in any way.
# Line with comment doesn't contain anything except for comment.
This means # is not a special character in the middle of a sentence.
\# may also be quoted, if it should not make a comment.

headers

= level 1 header =

== level 2 header ==

=== level 3 header ===

==== level 4 header ====

===== level 5 header =====

paragraph and line break

Paragraphs are separated with one or more empty line.

Paragraph one.

Paragraph two.

Lines in the same paragraph are separated with a sole period.

First line.
.
Second line.

Second paragraph.

The period may be, of course, quoted with \, although I don't see what for.

code (<pre>)

Preformatted text (e.g. source code snippet) should be independent paragraph beginning with {{{ and ending with }}} (each in its own line). First backslash in any line is always removed (this allows to quote }}} and still one may put \}}} line).

Some paragraph.

{{{
source snippet
further source
  code indented by 2 spaces
back
\}}}
}}}

Further paragraph.

tables

Simple tables are formatted semi-graphically. Table should be a paragraph.

# header cells (<th>)
||* server name *||* RAM (MB) *||* architecture *||
# regular cells (<td>)
||  onyx         ||  1024      ||  x86_64        ||
|| sandstone || 256 || i386 ||
# in the same row there may be <th> mixed with <td>
|| cfmaster || 256 ||* ARM *||

Example with a macro:

||* server name   *||* RAM (MB)        *||* architecture     *||
|| [[@servers]]    || [[@ram $servers]] || [[@arch $servers]] ||

lists

Unordered list is a paragraph. Elements start with with * indented exactly by two spaces. After breaking a line in wiki source, line may be indented even more to make up for missing * marker.

Sublist does not start with a paragraph break (empty line). Just break source line and add two spaces to marker indent.

Numbered list is similar to unordered list. Item marker is either [0-9]+\. or [a-z]\., what indicates type of list. Numbers and letters may be of any order; real values will be picked automatically.

Lists without any decoration or indent whatsoever are available with [] markers. Such lists on screen look similar to a paragraph with line breaks, but their items are repeated appropriately for macros returning lists, as opposed to line breaks.

Paragraph.

  1. first point
  1. second point
    a. second a)
    a. second b)
      * itemize
      * another itemize, now with slightly longer text,
        because of what the line break was needed
        .
        and this is how new line is inserted
    a. second c)
      # if @servers returns a list and @memory inserts a graph,
      # the following will expand to set of graphs (with no decorations)
      [] [[@@servers]] [[@memory $servers]]
  1. third point

Further paragraph.

Note: there's no way of returning from sub-list to parent list except for starting new list item.

sub-blocks

Sometimes there might be a need for a table cell to contain more than just simple text line. It may be a different (inner) table, list, paragraph or any combination.

||* server     *||* free space                      *||
|| [[@servers]] || [[%free_disk_on_server $servers]] ||

____
# ^-- this is four underscores

[[%free_disk_on_server $server]] {{{
||* mountpoint        *||* space                        *||
|| [[@mounts $server]] || [[@free_disk $server, $mounts]] ||
# period after closing marker is only for Trac formatting limitation
# in real world it should not be there
.}}}

TODO

  • pragmas
    • table of contents
    • colour definition for states returned by macros
    • this page requires login (sensitive data)
    • change the predefined variable name for $page_name or $page_param
    • page title (<title>...</title>)
    • table border
      • no border
      • inner table
      • border around table only
      • full border (including border between rows/cells)
      • others?
    • change repeatability of table elements: repeat cell instead of row for a macro returning list
    • others?
  • <div> and <span> with CSS classes
    • [[(css_class) some text]], [[<css_class> some text]]
    • class name: [_a-zA-Z]+[_a-zA-Z0-9-]*