10 Markup

The markup corresponds to the markup of Vim’s viki-plugin. There are some minor deviations, though.

This chapter is mainly a test course.

10.1 The Basics

10.1.1 Elements and Particles

A deplate document is made up of elements (a.k.a. block elements in HTML, XML etc.) that consist of particles (a.k.a. inline elements). No particle can cross element boundaries. This distinction is important to understand, as commands and regions yield elements, but macros yield particles.

Although deplate has some facitilities for program control (conditional or repeated output), it really is rather a markup language but no programming language. Although you can define new elements right within a deplate document using deplate markup, this only works for really simple elements.

If a line matches an element pattern (usually defined by the beginning of the line), it marks the end of the previous element and starts a new element. If a line matches no pattern, it either starts a new paragraph or is added to the previous element. Elements like headings, anchors, or table rows are one-line patterns to which no unmatched line will be added. Other elements like list items or paragraphs can be made up of more than one line.

10.1.2 Backslashes

The deplate markup is based on inserting special characters into the text as in this example: __emphasized__, which will be printed as emphasized. If you want to prevent deplate from interpreting these markers, they must be preceded by a backslash.

  • The backslash is used as escape character that prevents the wikification of the following character.
  • There are two exceptions:
    1. A backslash at the end of the line makes a pattern include the next line; any whitespace at the beginning of the following line is removed.
    2. A backslash in front of a blank results in non-breaking space.
  • A backslash that should be printed must be preceded by a backslash.

10.1.3 Special Characters

You should especially take care with the following characters:

Curly braces ({})
Curly braces usually enclose macros; in other contexts, they should always be preceded by a backslash
  • There are some grey areas though that could cause problems, e.g. when input to a macro (e.g. the ruby macro) contains an unmatched curly brace
Backticks (`)
Backticks are used to insert some symbols and should be escaped by a backslash in other contexts than inserting a special character.

Sequences of character you should notice:

Two underscores (__) followed by non-whitespace
Emphasized text
Two single quotes ('') followed by non-whitespace
Literal text set in typewriter font
Two colons (::) surrounded by whitespace
Used in definition lists

Characters with special meaning if they occur at the beginning of line:

Asterisks (*)
Headings, unordered lists
Sharp sign (#)
Anchors, commands, regions, ordered lists
Percent (%)
List markers
1., a., -, *, #, @, ?, ?.


The dollar sign ($)
Although it has currently to be enabled by loading a module, there is a chance that this will become the standard delimiter for mathematical expressions typed in latex (with the AMS packages enabled). The standard markup will be either $a = x + y$ or with blanks $ a = x + y $ as the dollar sign is most likely used before or after a digit.

Be aware that your editors line wrap can inadvertently place these characters at the beginning of a line.

Example 10.1: Text styles, backslash

__emphasize__, WikiName

\__noemphasize\__, \NoWikiName

One \


unnnnnnnnnnnnnnnnnn\ breakkkkkkkkkkkkkkkkkk\ ableeeeeeeeeeeeeeeeeeeeeeee


emphasize, WikiName

__noemphasize__, NoWikiName

One line


unnnnnnnnnnnnnnnnnn breakkkkkkkkkkkkkkkkkk ableeeeeeeeeeeeeeeeeeeeeeee

10.1.4 Argument Values

Arguments to macros, commands, and regions:

  • In argument values, the characters !=: and single double quotes must be preceded by a backslash
  • Alternatively, you can enclose a value in double quotes (which will be stripped off; doublequotes must be escaped using a backslash) or parentheses (which will be retained)
  • Argument values are stripped of whitespace; if you want an argument to contain leading or trailing whitespace, you have to enclose the argument in double quotes
Table 10.1: Key arguments
Example Key Arguments Body
{macro} {} ""
{macro: foo} {} "foo"
{macro boo!: foo} {"boo" ⇒ true} "foo"
{macro boo! bar=1: foo} {"boo" ⇒ true, "bar" ⇒ "1"} "foo"
{macro bar=object(id=1): foo} {"bar" ⇒ "object(id=1)"} "foo"
{macro bar="foo := bar": foo} {"bar" ⇒ "foo := bar"} "foo"
{macro bar=( boo=boo): foo} {"bar" ⇒ "( boo = boo)"} "foo"
{macro bar=\( boo=boo): foo} {"bar" ⇒ "(", "boo" ⇒ "boo)"} "foo"
{macro bar="(" boo=boo): foo} {"bar" ⇒ "(", "boo" ⇒ "boo)"} "foo"

There are two special arguments (fmt and if) that allow some control on whether an element will be included in the output. Please see 15.6 for details.

10.2 Comments (whole lines)

  • The percent sign has to be first non-blank character in the line. Otherwise it’s interpreted as a character.
  • A comment separates lines as paragraphs.
  • For intra-paragraph comments use the comment macro 13.2

Example 10.2: Comments

Line %1
Line %2


Line %1 Line %2

10.3 Paragraphs

A paragraph a sequence of non-empty lines that don’t match anything else.

Example 10.3: Paragraphs

Paragraph 1 finishes with an empty line. Paragraph 1 finishes with an 
empty line. Paragraph 1 finishes with an empty line.

Paragraph 2 finishes with an unordered list. Paragraph 2 finishes with 
an unordered list. Paragraph 2 finishes with an unordered list.
    - Item 1
    - Item 2


Paragraph 1 finishes with an empty line. Paragraph 1 finishes with an empty line. Paragraph 1 finishes with an empty line.

Paragraph 2 finishes with an unordered list. Paragraph 2 finishes with an unordered list. Paragraph 2 finishes with an unordered list.

  • Item 1
  • Item 2

10.4 Headings

NOTE: Headings can span more than one line by putting a backslash (‘\’) at the end of the line.

Known options:

prevent the heading from being listed in the toc; as you can see from the current heading, the heading number is increased nevertheless (which probably should be considered as a bug?)
the display name in the table of contents
the display name in a minitoc; with multi-file output, this argument defines the optional file name
similar to shortcaption; if an id and a shortcaption are given, the id will be used for the filename and the sort caption for the mini-toc
Don’t add any numbering to the heading. (Set the variable headings to “plain” if you want to turn off numbering for all headings.)
Turn a heading into a hyperlink; this requires the hyperHeading variable(see 15.1.2) to be set

If you set the variable autoFileNames, deplate will derive the file name from the heading.

* Level 1
#OPT: id=foo

** Level 2

*** Level 3
#OPT: noList! plain!

10.5 Lists (indented)

Example 10.4: List

    - Item
        * Item
            + Item
                1. Item 1
                    a. Item a
                    B. Item B
                    #Verb <<---------
                    EMBEDDED VERBATIM TEXT 
                2. Item 1
                    || Embedded || Table ||
                    |  x        |  1      |
                    |  y        |  2      |
        * Item
            # Item 1
                @ There is much to say about Item A, too much to be put 
                  in words or to be written down.

                  What else is there to say about Item A?

                @ Item B
            # Item 2
    - Do this
        #A _ Some task
        #B1 _ Some other task
    - Do that
        #A  x11-11-2050 Something was done!
        #B1 11-11-2050  Some other task


  • Item
    • Item
      • Item
        1. Item 1
          1. Item a
          1. Item B
        2. Item 1
          Embedded Table
          x 1
          y 2
    • Item
      1. Item 1
        1. There is much to say about Item A, too much to be put in words or to be written down.
          What else is there to say about Item A?
        2. Item B
      2. Item 2
  • Do this
    • A Some task
    • B1 Some other task
  • Do that
    • A 11-11-2050 Something was done!
    • B1 11-11-2050 Some other task

NOTE: “#” (numbered, ordered lists), and “@” (ordered lists with letters) are the preferred markers. If you use dashes as in LaTeX (i.e. “--”), a dash appears to be okay too. Be aware that, like LaTeX, deplate concatenates two normal dashes (“--”) to one long dash (“–”) – see also 10.10.

NOTE: If you run into troubles when nesting lists, consider the use of the list macro 13.5.

NOTE: Task lists are implemented as varlist in DocBook.

10.6 Description lists (indented)

Example 10.5: Description list

    Item :: Description



10.7 Tables

A table is marked as sequence of lines beginning and ending with one or two “|” symbols. Two pipe symbols (or whatever its name is) define a row belonging to the head or the foot.

A row containing only empty cells and cells with hyphens defines a ruler.

A cell containing only “^” means concatenate with the cell above. A cell containing only “<” means concatenate with the cell to the left.

Tables take the following options (via the OPT command):

The number of rows encompassing the table head
The number of rows encompassing the table foot
The rows to be highlighted
The columns to be highlighted
rows=ROWDEF1, ROWDEF2, ...
Define a row’s attributes
  • ROWDEF has the form: KEY1.VAL1 KEY2.VAL2 ...; KEY being one of
    The row height
  • a ruler counts as a row
cols=COLDEF1, COLDEF2, ...
Define a columns’s attributes
  • COLDEF has the form: KEY1.VAL1 KEY2.VAL2 ...; KEY being one of
    The column width
    The column’s justification (left, right, center, or justified)
    Add a left-handed vertical ruler (the value denotes the number of rulers or its thickness)
    • This option is currently only interpreted for LaTeX output
long!, short!
Define whether the longtable environment should be used in LaTeX output (by default, the longtable environment will be used for tables with more than 20 rows).
  • Switching between the table and the longtable environment has some effects on the layout. One consequence is that footnotes are set properly only in the longtable environment. On the other hand, the here, floatHere, align, and floatAlign options are currently ignored.
The table style (but see below)
Like style but ignore tableStyle
A short note concerning data source etc.

In addition, the following options for “floats” apply too:

here!, floatHere=1
In LaTeX output, add the h attribute to the table environment
align=[left|right|center], floatAlign=[left|right|center]
align the table; the first one is a table specific options, the second a global document option

Joining cells: If a cell contains nothing but “^” or “<”, the current cell will be joined with the left one or with the cell above. (The actual output depends on the formatter and the capabilities of the target format, though.)

It depends on the formatter whether these options are interpeted.

Example 10.6: Table

|| ----------------------------- ||
|| Head || Categories || <       ||
|  Row1 |  Value1     |  Value1   |
|       | ----------- |           |
|  Row2 |             |  Value2   |
|       | ----------- |           |
|  Row3 |  Value3     |  ^        |
|  -----------------------------  |
#OPT: hiCol=first hiRow=last cols=w.3cm j.right r.1, w.1cm,,r.1 rows=,h.3cm
#OPT: note=Source: My Head, 2004
#CAP: This Table


Table 10.2: This Table
Head Categories
Row1 Value1 Value1
Row2 Value2
Row3 Value3
Source: My Head, 2004

NOTE: Rows can span more than one line by putting a backslash (‘\’) at the end of the line.

NOTE: An empty cell is marked by at least 3 consecutive blanks.

You can also define a style for a table. The style attribute is currently only interpreted by the latex-styles module and to some degree emulated in HTML output – not so surprisingly, this works better in Firefox than in MS IExplorer.

The following styles are known (for one or another output format):

Draw all table borders/rulers
Draw a ruler at the top and the bottom of the table, as well as between groups
Like formal but add vertical rulers on both sides
Like box but draw the background of some rows and columns in gray or in colours
Horizontal rulers between each row
small, footnotesize, scriptsize
Smaller font sizes
decreased intercell spacing (there is a minor problem with line spacing)
rotate the table (LaTeX only, I assume)

Example 10.7: Table styles

#Var id=styledTableExample <<---
|| Head || A || B ||
|  Row1 |  1 |  2  |
|  Row2 |  3 |  4  |
|| Foot || X || Y ||
#OPT: hiCol=first

Test ''grid'' & ''scriptsize'' styles:
#INCLUDE var=styledTableExample
#OPT: style=grid,scriptsize

Test ''formal'' & ''footnotesize'' styles:
#INCLUDE var=styledTableExample
#OPT: style=formal,footnotesize

Test ''box'' & ''small'' styles:
#INCLUDE var=styledTableExample
#OPT: style=box,small

Test ''overlay'' style:
#INCLUDE var=styledTableExample
#OPT: style=overlay,landscape


Test grid & scriptsize styles:

Head A B
Foot X Y
Row1 1 2
Row2 3 4

Test formal & footnotesize styles:

Head A B
Foot X Y
Row1 1 2
Row2 3 4

Test box & small styles:

Head A B
Foot X Y
Row1 1 2
Row2 3 4

Test overlay style:

Head A B
Foot X Y
Row1 1 2
Row2 3 4

10.8 Anchors

Anchor (or labels respectively) are attached to the previous element, save if the previous element is a whitespace. In this case the anchor will be attached to the following element.

The name must begin with a lower letter. There mustn’t be non-whitespace character before the sharp sign.

Example 10.8: Anchors

* This is section one

Some text.

* This is section two

10.9 Wiki Names, URLs

deplate is inspired by several wiki engines. It thus also provides formatting of wiki names and URLs as hyperlinks. There are about four types of wiki names.

Any word in CamelCase is turned into a wiki name – save if wikification is prevented with a backslash – see 10.1.2.
Any text between [- and -] will be turned into a hyperlink.
An extended wiki name has the form: [[DESTINATION][OPTIONAL NAME]MODIFIER].
  • MODIFIER is optional.
    open page in new window
    set rel="nofollow"
    prevents deplate from adapting the reference’s suffix
    • deplate was created as the publishing framework (or so) for a personal wiki (namely the Vim viki plugin). As such it assumes that the files being referenced to are converted to the same target format as the current file, which is why deplate modfies an extended wiki destination’s suffix. Use this modifier to prevent deplate from doing so.
    • Often the chosen deplate output is only an intermediary file; in order to make deplate append the suffix of the final output file, set the document option suffix to the desired value. E.g. if you convert to docbook and then from docbook to html, pass the option -D suffix=html to deplate when converting the text sources.
  • If you want a hyperlink to have an image, use: [[http://www.example.com][{img: example_image}]]. See also 13.5.
An interwiki name is a shortcut to a different wiki. Any simple and quoted wiki name can be deferred to an interwiki by prepending NAMEINCAPITALS::. You have to define an interwiki before referring to it by adding something like this to your configuration file: InterWiki.add("ID", "http://BASEURL/", ".SUFFIX")

Wiki Names are automatically marked as index entries – see 12.4 and 12.5.

Example 10.9: Wiki names


[-some name-]#there

OTHERWIKI::[-some name-]
OTHERWIKI::[-some name-]#there


10.10 Symbols

The backtick (`) is used to introduce some symbols like quotation marks (e.g., in positions where deplate would choose the wrong one).

Symbols are not expanded in text marked as typewriter/code and in verbatim regions.

Example 10.10: Symbols

<-, ->, <=, =>, <~, ~>, <->, <=>, <~>, !=, ~~, ..., --, ==, ```, `'', ``, `'

''->'', ''<-''

#Verb <<--
<-, ->, <=, =>

#Code id=symbolsTest syntax=ruby <<--
<-, ->, <=, =>


←, →, ⇐, ⇒, <~, ~>, ↔, ⇔, <~>, ≠, ≈, …, –, ≡, “, ”, ‘, ’

->, <-

<-, ->, <=, =>
<-, ->, <=, =>

NOTE: If you want to disable some of these symbols, you could add some ruby code like this to your config.rb:

class Deplate::Particle::Symbol
   @@symbols_table.delete_if {|k,v| ['<->', '<=>', '<~>'].include?(k)}

10.11 Markers

Markers are meant to highlight a position in the text. In order to avoid ambiguities with notes (see below), there should not be a space before or after the marker – i.e. it should immediately follow or precede the word it is referring to.

Example 10.11: Markers

    - elaborate+++
    - here###
    - questionable???
    - attention!!!


  • elaborate+++
  • here###
  • questionable???
  • attention!!!

10.12 Notes

Indented paragraphs that begin with a marker and a subsequent space start an annotation, i.e. the text of paragraph will be turned in a margin note or similar – depending on the output format.

Example 10.12: Notes

Indented paragraphs that begin with a marker and a subsequent space 
start an annotation.
    !!! Something like this.


Indented paragraphs that begin with a marker and a subsequent space start an annotation.

Something like this.

10.13 Strings, Smart Quotes

Example 10.13: Quotes

"Text in quotes"


“Text in quotes”

NOTE: Quotes are handled by two classes: Deplate::Particle::DoubleQuote and Deplate::Particle::SingleQuote. In order to disable smart quotes add this code to your config.rb:


10.14 Textstyles

Example 10.14: Text styles

__emphasize__, ''typewriter''


emphasize, typewriter

NOTE: There must not be a whitespace after the opening mark.

NOTE: Text in typewriter style is basically set verbatim with the expection of backslashes.

10.15 Breaks

A break is marked by at least 2 dashes, “8<”, and again at least 2 dashes.

I say so.

In HTML output, a break is represented by a horizontal line. In other output formates, a break actually denotes a page break.

10.16 Whitespace

A line of whitespace usually separates text elements – e.g. paragraphs,

Prev Home Next
1 Introduction
2 Getting deplate
3 Installation
4 Usage
5 Configuration
6 Input Formats
7 Output Formats
8 Themes
9 Modules
10 Markup
10.1 The Basics
10.2 Comments (whole lines)
10.3 Paragraphs
10.4 Headings
10.5 Lists (indented)
10.6 Description lists (indented)
10.7 Tables
10.8 Anchors
10.9 Wiki Names, URLs
10.10 Symbols
10.11 Markers
10.12 Notes
10.13 Strings, Smart Quotes
10.14 Textstyles
10.15 Breaks
10.16 Whitespace
11 Regions
12 Commands
13 Macros
14 Skeletons
15 Variables and options
16 Internals
17 Extending deplate
18 Bibliography
19 Index
About this page