Skriv Markup Language

Introduction & Rationale

  1. Introduction
  2. License
  3. Inspiration
  4. Rationale
  5. Used Terms
    1. Terms
    2. Characters

1. Introduction

Skriv Markup is a lightweight markup language. It defines a special syntax that can be used to write textual contents, with embedded layout information. Then it is possible to process these texts to generate some complex renderings.

In theory, this kind of language can be used to generate many types of document, like HTML pages, PDF files, DocBook exports, ... (for the time being, Skriv Markup implementation provides HTML and DocBook renderings)

By the way, “skriv” means “to write” in swedish.

2. License

The current markup.skriv.org website, the Skriv Markup syntax definition, and the SkrivMarkup library documentation are crossed-licensed under the terms of two licenses:

3. Inspiration

Skriv Markup took its inspiration from a lot of previously created wiki-like dialects.

  • First of all, the reputation of MediaWiki (as the core engine of Wikipedia) makes it an unavoidable source of inspiration.
  • Creole is a project of common language, led by contributors of many wiki engines.
  • Markdown is now a very well known syntax, used by a growing number of websites and softwares.
  • reStructuredText, used by the Python programming language's documentation.
  • POD, usually employed to write documentation for Perl source code.
  • txt2tags, one of the oldest and most complete syntax.
  • AsciiDoc, used among others to create the Git User's Manual and other technical books.
  • Textile, another well-known markup language.
  • WikiWikiWeb, the first wiki engine, and some other softwares like DokuWiki, TWiki, MoinMoin, Redmine, ...

4. Rationale

Main idea: Lightweight markup languages should stay lightweight. They are not intended to become some full-featured layout engines. No need to implement every single graphical functionality.

Some simple ideas conduct to the creation of Skriv Markup:

  1. It is designed to be fast to type. The main use-case is to write some pages of wiki content, or some kind of documentation. It is more important to be able to write these pages quickly than to keep the likeness of any text file.
  2. The syntax should be intuitive once explained. The code should be logical enough to be easy to remember.
  3. The language should not be ambiguous. A writer should never have to wonder about the result of what she is typing.

These ideas led to some choices:

  1. Except for two special block-span elements, all the syntax is context-free. As you write your text, you type the markups you need when you need them, and that's it.
  2. The different tags composing the Skriv syntax were chosen because their shape seems natural with their usage, or because they are already widely used.
  3. Most of the tags are based on a repetition of characters. For inline tags, they are doubled; for some block tags, they are tripled. As a result, it is very hard to type a Skriv Markup tag by mistake.

5. Used Terms

5.1 Terms

Skriv Markup (with a space between words) is the name of the lightweight markup language presented here.

  • “Skriv Markup Language”, “SkrivML” and "SkrivML" are common synonyms.
  • Text files containing Skriv Markup content should use the .skriv extension (the .sml extension is already used by Standard ML, SMIL and Simile softwares).

SkrivMarkup (without space) is the name of the official parsing library implemented in PHP.

5.2 Characters

Here is a list of special characters, and how they are named in this documentation.

<> angle brackets {} curly brackets
[] square brackets * asterisk
/ slash \ backslash
- minus sign # hash sign
= equal sign | pipe
~ tilde ^ caret
, comma ! exclamation mark
' single quote " quotation mark

(this table is inspired by Creole's terms and Wikipedia's page about punctuation)