The lambwiki Manual

Dario Teixeira

March 2013

Table of Contents


lambwiki is a lightweight markup language for the description of documents. It is inspired by markdown[1] and creole[2], and remains for the most part compatible with the latter. Similarly to other lightweight markup languages, lambwiki is targeted at the description of documents consisting largely of utf-8 text, and where syntactic annotations are inspired by conventions used in email.

lambwiki is part of the family of markup languages supported by the lambdoc library[5]. However, lambwiki supports only a limited subset of all the features available in lambdoc. While not as powerful and flexible as a full-featured markup language like lambtex[4], the lightweight markup used by lambwiki should be sufficient to describe most simple documents. If your document requires a richer set of semantic elements, then obviously you should consider using instead a full-fledged markup like lambtex.

1Paragraphs and text formatting

A lambwiki document is composed of a sequence of blocks. Examples of blocks include paragraphs of text, quotes, and source-code listings. Blocks occupy the entire width of the page, and are vertically separated from other blocks by a small margin.

Paragraphs are the simplest of all blocks, being composed of just text (either plain or annotated with special formatting directives). To separate two paragraphs, you must put at least one blank line between them. However, the blank line is optional when separating a paragraph and a non-paragraph block. Moreover, linebreaks are irrelevant within the same paragraph.

It is possible to apply some special formatting to passages of text. This is done by enclosing the passage between special begin and end markers, which always consist of two identical characters. Tab. 1 lists all the formatting options and the begin/end markers used for each. Note that in many cases the begin marker is identical to the end marker. Also, bear in mind that nesting formatting directives is not allowed.

Begin markerEnd markerExample
****You can make some passages be bold.
////Here's another way to emphasise text.
{{}}You can also imitate a typewriter.
(())lambwiki supports text in small-caps.
^^^^The 1st of January has a superscript.
,,,,H2O requires a subscript.

Tab. 1:

Text formatting annotations. Simply wrap between the begin and end markers the passage of text you wish to format. Note that in many cases the end marker is identical to the begin marker.

lambwiki supports also hyperlinks into external resources. The general notation for hyperlinks is [[uri|description]], where uri is the actual resource identifier and description is the clickable hyperlink text. The latter is optional, meaning that [[uri]] will also produce a hyperlink, but one using the uri itself as description text.

The following source-code fragment illustrates the declaration of paragraphs in lambwiki, text formatting commands, and the use of hyperlinks:


Line breaks within one paragraph are not important,
since paragraphs are only terminated by a blank line.

Within a paragraph you can format certain passages
in **bold text**, //emphasised text//,
{{monospaced text}}, or even in ((small caps)).

For the sake of completeness, it is also possible
to declare superscripts such as 1^^st^^ of January,
and subscripts such as H,,2,,O.

Adding a hyperlink into the [[http://www.wikipedia.org/|Wikipedia]]
is easy.  Here's another one: [[http://www.wikipedia.org/]].

This is the corresponding output from the lambwiki composer:

Line breaks within one paragraph are not important, since paragraphs are only terminated by a blank line.

Within a paragraph you can format certain passages in bold text, emphasised text, monospaced text, or even in small caps.

For the sake of completeness, it is also possible to declare superscripts such as 1st of January, and subscripts such as H2O.

Adding a hyperlink into the Wikipedia is easy. Here's another one: http://www.wikipedia.org/.

2Special characters

lambwiki allows the direct use of html entities via the same notation used in html. More precisely, entities are to be enclosed between the characters '&' (ampersand) and ';' (semicolon), and may be specified by name or by unicode code point in decimal or hexadecimal notation. As an example, if the euro symbol '' is not readily available in your keyboard, you may enter it in either of the following three manners:

NameDecimalHexadecimal
€€€

The reader will have noted that lambwiki must interpret the character '&' (ampersand) differently, and therefore you need a workaround if you want to input an actual ampersand. In fact, there is another character that is interpreted differently by lambwiki, and as such also requires a special escaping sequence. That character is '\' (backslash), which also happens to be the character used for escaping. Therefore, displaying a backslash or an ampersand is achieved with \\ and \&, respectively. Another option is of course to use the #47 and amp html entities.

Note that in most practical situations you can get away with inputting an ampersand directly without escaping. This is because the scanner will only interpret an ampersand as the beginning of an entity declaration if it is immediately followed by an alphabetic or numeric sequence terminated by a semicolon. If it is not, then the ampersand is interpreted as plain text.

Besides individual characters, there are also some multi-character sequences that are interpreted differently by lambwiki. One example are the previously described two character markers used for text formatting. Tab. 2 lists all the other ones. Remember to use the escape character if you wish to input any of these sequences literally.

SequenceTranslation
---Typographic em-dash
(don't use at the beginning of a line)
--Typographic en-dash
(don't use at the beginning of a line)
``Opening double quotes
''Closing double quotes

Tab. 2:

Special character sequences and their lambwiki interpretation. Remember to use the backslash for escaping if you wish to input any of these sequences verbatim. Note that using dash(es) at the start of a line is the marker for unordered lists (see the next section for details).

3Lists

Lists in lambwiki come in two varieties: ordered and unordered. The former are denoted my prefixing each list item with the character '#', whereas in the latter case the prefix is '-'. Declaring sub-lists (ie, lists within lists) is also possible: simply repeat either '#' or '-' a number of times in accordance to the depth of the sub-list. These marker characters may be indented, as long as they are the first non-whitespace character in the line.

Separating a list from a preceding paragraph with a blank line is not required, though it is advisable. Similarly, usage of blank lines between list items is also optional. More importantly, make sure the list depth as indicated by the number of '#' or '-' characters makes sense: the lambwiki composer will complain if you declare at the top-level a list with depth higher than 1, or if a sub-list increases list depth by more than one unit.

The following sample illustrates lists in lambwiki. Note the flexible use of blank lines and whitespace for indentation.


The reasons are four:

# This is the first reason;

# This is the second reason; it is okay
  to break a line within each item.

# The third reason has a number of sub-clauses:

  -- Alpha
  -- Beta
  -- Gamma

# And here is the fourth and final reason.

This is the result as produced by the composer:

The reasons are four:

  1. This is the first reason;

  2. This is the second reason; it is okay to break a line within each item.

  3. The third reason has a number of sub-clauses:

    • Alpha

    • Beta

    • Gamma

  4. And here is the fourth and final reason.

4Quotations

Quotations in lambwiki follow the email tradition of prefixing each quoted line with the character '>' (the greater-than sign). Following this marker you may have a normal paragraph or a list definition, as the example below illustrates:


This is what you said:

> Eggs should be opened by their large end.
> Opening them by their small end is heresy.
> Here are three reasons why:
>
> # First;
> # Second;
> # Third.

I beg to differ. Let me expand on why.

This is the result produced by the composer:

This is what you said:

Eggs should be opened by their large end. Opening them by their small end is heresy. Here are three reasons why:

  1. First;

  2. Second;

  3. Third.

I beg to differ. Let me expand on why.

Quotations within quotations are also legal. The quotation level is indicated by the number of '>' characters that prefix the line. Whitespace between the '>' characters is optional. Consider thus the following lambwiki source:


This is your interpretation of the discussion:

>This is what you said:
>
>> Eggs should be opened by their large end.
>> Opening them by their small end is heresy.

This is the result:

This is your interpretation of the discussion:

This is what you said:

Eggs should be opened by their large end. Opening them by their small end is heresy.

5Verbatim blocks

A verbatim block denotes a fragment of text where linebreaks are significant and the text is to be rendered using a monospaced font. The primary application of verbatim blocks is to display ascii-art diagrams. In lambwiki, the beginning of a verbatim block is denoted by a line consisting entirely of the characters '(((' (plus optional extra specifiers, described below), and its termination by a line consisting only of the characters ')))'. There is no attempt at interpreting the characters inside a verbatim block; in other words, escaping is not possible, and neither is the input of html entities using the ampersand operator.

Verbatim environments accept a limited form of configuration. In the same line and immediately after the begin marker you may specify one or more class name declarations, separated by commas. Each class name maps directly to html class names, but preppended by 'doc_class_' (the prefix prevents name clashes). Note that classnames must begin with a lowercase Roman letter, and may contain only lowercase Roman letters, digits, the character '-' (dash), or the character '_' (underscore).

For your convenience, the css shipped with lambwiki includes some predefined class names for use with verbatim environments. These are mult0, mult1, and so forth until mult9. The integer indicates a multiplying factor for the contents of the environment. For a factor of x, the actual scaling relative to normal size is given by 2x. The default factor is 0, which corresponds to normal size. One common application of this feature is to display unicode characters as full-sized pictures. As an example, this is what the unicode snowman (code point U+2603) looks like with a multiplier of 7, corresponding to a font size 11.3 times larger than normal:

In addition, the default css also allows floatation specifiers to be used with verbatim blocks. Floating specifiers take the form of class names 'center', 'left', and 'right'. They declare that the block should be displayed either centered and occupying the entire width of the page (this is the default), floating on the left, or floating on the right, respectively. Note that they map directly to css float declarations.

To illustrate the use of verbatim blocks, consider the following lambwiki source-code fragment:


Here's a box:

(((
---------
|  Box  |
---------
)))

The result produced by the composer is shown below:

Here's a box:

---------
|  Box  |
---------

6Source-code blocks

While nothing prevents you from using the aforedescribed verbatim blocks for displaying source-code listings, lambwiki does have a dedicated facility for this purpose, with a number of advantages. Source-code blocks are declared in much the same way as verbatim blocks, but use '{{{' and '}}}' as delimiter characters instead. Moreover, they also accept — albeit different — style configuration options.

Similarly to verbatim blocks, the style configuration of a source-code environment is to be placed immediately after the '{{{' sequence that signals the beginning of the block (whitespace is optional both before and after, but the configuration must be on the same line). Because multiple configuration options are allowed, these should be separated by commas. Moreover, options come in two different types. The first was already discussed in the previous section about verbatim blocks: class name declarations. The second type is a key-value declaration, whose generic form is 'key=value', for a key 'key' and value 'value'.

There are two key-value configuration options available. The most important is undoubtedly 'lang', which when set with the name of a language, sets the rules for syntax highlighting. Also available is 'nums', which accepts a boolean value and dictates whether line numbers should be added to the source code listing. Valid boolean values are 'true', 'yes' and 'on' for truth value true and 'false', 'no' and 'off' for truth value false. It defaults to false.

The obligatory example, showing an OCaml source-code fragment:


{{{lang=ocaml,nums=true,zebra
type 'a tree =
    | Leaf
    | Node of 'a * 'a tree * 'a tree

let rec count = function
    | Leaf                     -> 0
    | Node (node, left, right) -> 1 + (count left) + (count right)
}}}

The result as produced from the composer is shown below. Note the syntax-highlighting following OCaml conventions, the zebra lines, and the display of line numbers:


1
2
3
4
5
6
7

type 'a tree =
    | Leaf
    | Node of 'a * 'a tree * 'a tree

let rec count = function
    | Leaf                     -> 0
    | Node (node, left, right) -> 1 + (count left) + (count right)

7Sectioning

lambwiki supports up to three levels of sectioning headers, designated as sections, sub-sections, and sub-sub-sections. These map directly to html's h1, h2, and h3 elements, respectively. The declaration of a header is done by prefixing the header text with one, two, or three times the character '=', where the number of equal signs corresponds to the sectioning level. Note that whitespace between the equal sign(s) and the header text is optional, and is discarded if present.

Consider thus the following lambwiki fragment:


= This is a section

Lorem ipsum dolor sit amet.

== This is a sub-section

Lorem ipsum dolor sit amet.

=== This is a sub-subsection

Lorem ipsum dolor sit amet.

Below is the result as produced by the lambwiki composer. Note that the numbering is automatically assigned.

1This is a section

Lorem ipsum dolor sit amet.

1.1This is a sub-section

Lorem ipsum dolor sit amet.

1.1.1This is a sub-subsection

Lorem ipsum dolor sit amet.

Appendix

Backmatter

Bibliography

  1. [1]

    John Gruber and Aaron Swartzmarkdown homepagehttp://daringfireball.net/projects/markdown/

  2. [2]

    Variouscreole homepagehttp://www.wikicreole.org/

  3. [3]

    Leslie LamportLaTeX: a Document Preparation System (2nd edition)Addison-Wesley Professional, 1994. ISBN 0-201-52983-1.

  4. [4]

    Dario Teixeiralambtex manualhttp://lambdoc.forge.ocamlcore.org/

  5. [5]

    Dario Teixeiralambdoc homepagehttp://lambdoc.forge.ocamlcore.org/